Resources Tools Docs FAQ CMS

Tutorial 13: Similar Ayah End-to-End

This tutorial is for users who want to show ayah-to-ayah similarity results (matched words, coverage, and score).

1) What This Resource Is

Similar Ayah resources provide ayah-level similarity records.

Typical fields include:

  • verse_key
  • matched_ayah_key
  • matched_words_count
  • coverage
  • score
  • match_words_range (word position range in matched ayah)

Primary category:

2) When to Use It

Use similar-ayah data when building:

  • Compare-verses tools
  • Pattern discovery across Quranic wording
  • Memorization reinforcement features

3) How to Get Your First Example Resource

  1. Open https://qul.tarteel.ai/resources/similar-ayah.
  2. Keep default listing order and open the first published card.
  3. Confirm the detail page includes:
    • Similar Ayah Preview tab
    • Help tab
  4. Confirm available downloads (json, sqlite).

This keeps onboarding concrete without hardcoded IDs.

4) What the Preview Shows (Website-Aligned)

On similar-ayah detail pages:

  • Similar Ayah Preview tab:
    • Jump to Ayah
    • Source ayah card for selected ayah
    • "X has N similar ayahs" banner
    • List of matching ayahs for selected ayah
    • Highlighted matched words inside matched ayah text
    • Match summaries ("This ayah matches N words with X% coverage and a similarity score of Y")
  • Help tab:
    • Field definitions (verse_key, matched_ayah_key, matched_words_count, coverage, score, match_words_range)
    • Export format notes

Practical meaning:

  • Similarity is scored data, not binary “same/different”.
  • You should sort by score/coverage and let users inspect why matches appear.

5) Download and Use (Step-by-Step)

  1. Download selected package (json or sqlite).
  2. Import similarity rows.
  3. Group rows by verse_key.
  4. Sort matches by score and/or coverage.
  5. Join with script text for readable display.
  6. Use match_words_range to highlight matched words in the matched ayah.

Starter integration snippet (JavaScript):

JavaScript
const matchesForAyah = (rows, ayahKey) =>
  rows
    .filter((row) => row.verse_key === ayahKey)
    .sort((a, b) => b.score - a.score || b.coverage - a.coverage);

const summaryText = (row) =>
  `This ayah matches ${row.matched_words_count} words with ${row.coverage}% coverage and a similarity score of ${row.score}`;

const isMatchedWordPosition = (wordIndexOneBased, range) => {
  if (!Array.isArray(range) || range.length !== 2) return false;
  const [from, to] = range;
  return wordIndexOneBased >= from && wordIndexOneBased <= to;
};

6) Real-World Example: Top Similar Ayahs Panel

Goal:

  • User opens an ayah and sees top similar ayahs ranked by score.

Inputs:

  • Similar Ayah package
  • Quran Script package

Processing:

  1. Filter rows by selected verse_key.
  2. Sort by score (and coverage as tie-breaker).
  3. Join matched ayah text and highlight words by match_words_range.
  4. Display per-match summary sentence.

Expected output:

  • Ranked similarity results that are interpretable, with visible highlighted overlap.

Interactive preview (temporary sandbox):

You can edit this code for testing. Edits are not saved and may not persist after refresh.

JavaScript Playground
Editor
Preview

7) Common Mistakes to Avoid

  • Treating similarity score as strict equivalence.
  • Ignoring coverage and matched-word context.
  • Not sorting results (raw order can be misleading).

8) When to Request Updates or Changes

Open an issue if you find:

  • Mismatched verse_key/matched_ayah_key pairs
  • Invalid score/coverage values
  • Broken json/sqlite downloads

Issue tracker:

Related Docs