Patantara — Query API Reference

This document gives an AI agent (or any programmatic client) enough context to query the Patantara Carnatic music graph database via its public read-only API endpoint.

Endpoint

POST https://patantara.net/api/query
Content-Type: application/json

Request

{
  "cypher": "MATCH (m:Musician) RETURN m.name LIMIT 5",
  "params": {}
}

• cypher (required): A Cypher read query. Writes (CREATE, MERGE, SET, DELETE, REMOVE) are rejected by the database.
• params (optional): Object of named parameters for parameterized queries (e.g., $name in Cypher maps to {"name": "Tyagaraja"}).

Response

{
  "results": [
    { "m.name": "Purandara Dasa" },
    { "m.name": "Venkatamakhin" }
  ],
  "count": 2
}

On error:

{ "error": "error message" }

Constraints

• Read-only: The endpoint uses a Neo4j read transaction. Any write operation is rejected at the database engine level.
• No CALL: Stored procedure calls (CALL ...) are blocked.
• No authentication required.

Database Schema

Node Types

Musician (223 nodes)

People in the Carnatic music tradition — composers, performers, scholars, instrumentalists.

Song (1252 nodes)

Musical compositions in the Carnatic tradition.

Transliteration convention: Capital letters mid-word represent retroflex or long vowels (e.g., "SrI" = Śrī, "rAma" = Rāma), not word boundaries.

Book (30 nodes)

Published texts — music treatises, notation compilations, journals.

SongTransmission (185 nodes)

Hypernode representing a documented instance of a song being taught from one musician to another.

Relationship Types

Key Edge Properties

GURU_OF edges carry: source_url, source_title, excerpt, uncertain (boolean).

KNEW edges carry: - source_url, source_title, excerpt — citation info (present on ~1260 of 2270) - year (integer) — year of earliest known performance/recording (present on ~703). NULL for book-sourced entries.

CONTAINS edges carry: - appears_as — how the song name appears in the book's index - source_url — link to the book/page - form — e.g., "Notation available", "Sāhitya only" - serial — index number within the book

COMPOSED is undirected with no properties.

Important Querying Notes

1. ragam not raga: The song property is ragam. This is the single most common mistake.

2. COMPOSED is undirected: Always match with -[:COMPOSED]- (no arrow), not -[:COMPOSED]->. Using a directed match will miss half the results due to arbitrary stored direction.

3. KNEW direction: Always (musician)-[:KNEW]->(song). This is a directed relationship.

4. Parameterize user input: Use $param syntax with the params field to avoid injection.

5. Book years are publication years: Useful for temporal queries (e.g., "performed before publication").

6. KNEW.year: When present, this is the year of the earliest known performance/recording. Not all KNEW edges have this.

Books in the Database

The 17 DKM books follow the naming pattern: "Dikshita Kirtana Mala — Part N (YYYY)".

Key Composers

These three are the "Trinity" of Carnatic music and account for the vast majority of songs.

Example Queries

Basic lookups

// All songs in a raga
MATCH (s:Song {ragam: "tODi"}) RETURN s.name, s.ragam

// Find a musician
MATCH (m:Musician) WHERE m.name CONTAINS "Tyagaraja" RETURN m

// Songs by a composer
MATCH (m:Musician {name: "Muthuswami Dikshitar"})-[:COMPOSED]-(s:Song)
RETURN s.name, s.ragam ORDER BY s.ragam

// Books containing a song
MATCH (b:Book)-[c:CONTAINS]->(s:Song {name: "nagumomu ganalEni"})
RETURN b.name, b.year, c.appears_as

Relationships

// Students of a guru
MATCH (guru:Musician {name: "Tyagaraja"})-[:GURU_OF]->(student:Musician)
RETURN student.name, student.born ORDER BY student.born

// Who performed a song?
MATCH (m:Musician)-[k:KNEW]->(s:Song {name: "nagumomu ganalEni"})
RETURN m.name, k.year ORDER BY k.year

// Guru lineage (variable-length path)
MATCH path = (ancestor:Musician)-[:GURU_OF*1..5]->(descendant:Musician {name: "Ariyakudi Ramanuja Iyengar"})
RETURN [n IN nodes(path) | n.name] AS lineage

Analytical queries

// Songs performed before they appeared in any book
MATCH (m:Musician)-[k:KNEW]->(s:Song)<-[:CONTAINS]-(b:Book)
WHERE k.year IS NOT NULL AND k.year < b.year
RETURN DISTINCT s.name, s.ragam, k.year AS performed, min(b.year) AS first_published
ORDER BY performed

// Dikshitar kritis not in any book
MATCH (d:Musician {name: "Muthuswami Dikshitar"})-[:COMPOSED]-(s:Song)
WHERE NOT EXISTS { MATCH (b:Book)-[:CONTAINS]->(s) }
RETURN s.name, s.ragam ORDER BY s.ragam

// Most-performed songs (by number of performers)
MATCH (m:Musician)-[:KNEW]->(s:Song)
RETURN s.name, s.ragam, count(m) AS performers
ORDER BY performers DESC LIMIT 20

// How many Dikshitar kritis were performed before they appeared in a book?
MATCH (d:Musician {name: "Muthuswami Dikshitar"})-[:COMPOSED]-(s:Song)
MATCH (m:Musician)-[k:KNEW]->(s) WHERE k.year IS NOT NULL
MATCH (b:Book)-[:CONTAINS]->(s)
WITH s, min(k.year) AS first_performed, min(b.year) AS first_published
WHERE first_performed < first_published
RETURN count(s) AS count

// Songs in SSP but not in any DKM volume
MATCH (:Book {name: "Sangita Sampradaya Pradarshini"})-[:CONTAINS]->(s:Song)
WHERE NOT EXISTS {
  MATCH (b:Book)-[:CONTAINS]->(s)
  WHERE b.name STARTS WITH "Dikshita Kirtana Mala"
}
RETURN s.name, s.ragam ORDER BY s.ragam

// Song transmission details
MATCH (teacher:Musician)-[:TAUGHT_IN]->(st:SongTransmission)<-[:LEARNT_IN]-(student:Musician),
      (st)-[:OF_SONG]->(s:Song)
RETURN teacher.name, student.name, s.name, st.excerpt

Using parameters

// Pass {"composer": "Tyagaraja", "ragam": "kalyANi"} as params
MATCH (m:Musician {name: $composer})-[:COMPOSED]-(s:Song {ragam: $ragam})
RETURN s.name ORDER BY s.name

curl example:

curl -s -X POST https://patantara.net/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "cypher": "MATCH (m:Musician {name: $composer})-[:COMPOSED]-(s:Song {ragam: $ragam}) RETURN s.name",
    "params": {"composer": "Tyagaraja", "ragam": "kalyANi"}
  }'