Basic Queries
This document provides fundamental query examples for retrieving and filtering data from the Quran Knowledge Graph.1. Retrieve Chapters (Surahs)
Description
Retrieves basic information about chapters (surahs) in the Quran, including their names, revelation place, and verse count.Query
Parameters
limit: Maximum number of chapters to return (e.g., 10)
Expected Results
A table of chapters with their basic information, ordered by chapter number:Variations
- Filter chapters by revelation place:
WHERE c.revelation_place = "Meccan" - Sort by verses count:
ORDER BY c.verses_count DESC - Get only chapter names:
RETURN c.chapter_number, c.name_english
2. Get Verses from a Chapter
Description
Retrieves verses from a specific chapter, including their text and position information.Query
Parameters
chapter_id: ID of the chapter (e.g., 1 for Al-Fatiha)limit: Maximum number of verses to return (e.g., 20)
Expected Results
A table of verses from the specified chapter:Variations
- Include additional verse properties:
RETURN v.id, v.verse_key, v.juz_number, v.page_number - Filter by verse number range:
WHERE v.verse_number BETWEEN 1 AND 10 - Include translation:
OPTIONAL MATCH (v)-[:HAS_TRANSLATION]->(t:Translation) RETURN v.verse_key, v.text_uthmani, t.text
3. Get a Specific Verse by Key
Description
Retrieves detailed information about a specific verse identified by its verse key (chapter:verse format).Query
Parameters
verse_key: Verse identifier in chapter:verse format (e.g., “2:255” for Ayatul Kursi)
Expected Results
Detailed information about the specified verse:Variations
- Include additional metadata:
RETURN v.verse_key, v.juz_number, v.hizb_number, v.page_number - Get verse with translation:
MATCH (v:Verse {verse_key: $verse_key})-[:HAS_TRANSLATION]->(t:Translation) RETURN v.text_uthmani, t.text, t.language_name - Get verse with tafsir:
MATCH (v:Verse {verse_key: $verse_key})-[:HAS_TAFSIR]->(t:Tafsir) RETURN v.text_uthmani, t.text, t.resource_name
4. Get Words in a Verse
Description
Retrieves the individual words in a specific verse, including their position and text.Query
Parameters
verse_key: Verse identifier in chapter:verse format (e.g., “1:1”)limit: Maximum number of words to return (e.g., 30)
Expected Results
A table of words from the specified verse, ordered by position:Variations
- Include word morphology:
MATCH (w)-[:HAS_ROOT]->(r:Root) RETURN w.text_uthmani, r.text_clean - Get words with specific properties:
WHERE w.text_uthmani CONTAINS "الله" - Include page and line information:
RETURN w.text_uthmani, w.page_number, w.line_number
5. Get Topics
Description
Retrieves topics from the knowledge graph, including their names and hierarchical information.Query
Parameters
limit: Maximum number of topics to return (e.g., 20)
Expected Results
A table of topics with their basic information:Variations
- Filter by parent topic:
WHERE t.parent_id = $parent_id - Get only top-level topics:
WHERE t.parent_id IS NULL OR t.parent_id = 0 - Sort by name:
ORDER BY t.name
6. Get Translations for a Verse
Description
Retrieves available translations for a specific verse in different languages.Query
Parameters
verse_key: Verse identifier in chapter:verse format (e.g., “1:1”)
Expected Results
A table of translations for the specified verse:Variations
- Filter by language:
WHERE t.language_name = "English" - Filter by translator:
WHERE t.resource_name = "Sahih International" - Include original text:
RETURN v.text_uthmani, t.language_name, t.text
7. Get Adjacent Verses
Description
Retrieves verses that come before and after a specific verse, providing context.Query
Parameters
verse_key: Verse identifier in chapter:verse format (e.g., “2:255”)context_size: Number of verses to include before and after (e.g., 2)
Expected Results
A table of verses providing context around the specified verse:Variations
- Include translations:
OPTIONAL MATCH (v_context)-[:HAS_TRANSLATION]->(t:Translation) WHERE t.language_name = "English" RETURN v_context.verse_key, v_context.text_uthmani, t.text - Adjust context size dynamically: Use different values for before and after
- Include chapter information:
RETURN c.name_english, v_context.verse_key, v_context.text_uthmani