Discover Your Schema

RushDB is self-aware — it continuously understands its own structure: labels, field types, value distributions, relationships, and semantic search readiness. The db.ai ontology methods expose this as either Markdown (for LLM injection) or structured JSON (for schema UIs, autocomplete, or property-ID lookups).

---

Why Agents Need This

Traditional databases assume the application knows the schema at build time. AI agents face a different reality:

• The knowledge graph may have been populated by other agents, batch imports, or live event streams.
• The schema drifts over time as new label types and properties appear.
• Agents cannot be pre-programmed with field names they have never seen.

RushDB's answer is schema-on-read for agents: call getOntologyMarkdown() once per session and receive the full, current schema as a single response. The agent can then construct valid queries referencing only labels and properties that actually exist — no hallucinated field names.

What the Ontology Contains

Component	Description
Label inventory	All label names in the project, with record counts
Property manifest per label	Property name, type, and either sample values (strings/booleans) or a min–max range (numbers/datetimes)
Relationship map	Which labels connect to which, via which relationship type, and in which direction
Semantic index status	Which properties have embedding indexes and whether they are ready for db.ai.search()

---

Get Ontology as Markdown

The recommended format for LLM context injection — compact, token-efficient, and ready to paste into a system prompt.

Python

db.ai.get_ontology_markdown()

from rushdb import RushDB

db = RushDB("RUSHDB_API_KEY")

# Inject into LLM at session start
response = db.ai.get_ontology_markdown()
schema = response.data

messages = [
    {"role": "system", "content": f"You are a data assistant.\n\n{schema}"},
    {"role": "user",   "content": "How many paid orders are there?"}
]

# Scope to specific labels
order_response = db.ai.get_ontology_markdown({"labels": ["Order"]})

# Bypass the 1-hour cache and force a fresh recalculation
fresh_response = db.ai.get_ontology_markdown({"force": True})

TSTypeScript

db.ai.getOntologyMarkdown()

// Inject into LLM at session start
const { data: schema } = await db.ai.getOntologyMarkdown()
const messages = [
  { role: 'system', content: `You are a data assistant.\n\n${schema}` },
  { role: 'user', content: 'How many paid orders are there?' }
]

// Scope to specific labels
const { data: orderSchema } = await db.ai.getOntologyMarkdown({
  labels: ['Order']
})

// Bypass the 1-hour cache and force a fresh recalculation
const { data: freshSchema } = await db.ai.getOntologyMarkdown({ force: true })

shell

POST /api/v1/ai/ontology/md

# Full schema
curl -X POST https://api.rushdb.com/api/v1/ai/ontology/md \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{}'

# Scoped to specific labels
curl -X POST https://api.rushdb.com/api/v1/ai/ontology/md \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"labels": ["Order"]}'

# Force cache bypass
curl -X POST https://api.rushdb.com/api/v1/ai/ontology/md \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"force": true}'

Request body fields

Field	Type	Required	Description
labels	string[]	no	Restrict output to specific labels. Omit (or pass []) for the full schema.
force	boolean	no	Bypass the 1-hour cache and force a full recalculation.

Example Markdown output

# Graph Ontology

## Labels

| Label     | Count |
|-----------|------:|
| `Order`   |  1840 |
| `User`    |   312 |
| `Product` |    95 |

---

## `Order` (1840 records)

### Properties

| Property    | Type     | Values / Range                         | Semantic Search                |
|-------------|----------|----------------------------------------|--------------------------------|
| `status`    | string   | `pending`, `paid`, `shipped` (+2 more) | —                              |
| `total`     | number   | `4.99`..`2499.00`                      | —                              |
| `name`      | string   | `Widget A`, `Widget B` (+8 more)       | `managed` cosine 1536d [ready] |
| `createdAt` | datetime | `2024-01-03`..`2026-02-27`             | —                              |

### Relationships

| Type        | Direction | Other Label |
|-------------|-----------|-------------|
| `PLACED_BY` | out       | `User`      |
| `CONTAINS`  | out       | `Product`   |

Agent quickstart

Call get_ontology_markdown() / getOntologyMarkdown() first in every AI session. Without it, models will hallucinate field and label names.

---

Get Ontology (Structured JSON)

Returns the same ontology as a structured array — useful for schema UIs, autocomplete, or looking up property IDs for db.properties.values().

Python

db.ai.get_ontology()

# List all labels with counts
response = db.ai.get_ontology()
for item in response.data:
    print(f"{item['label']}: {item['count']} records")

# Scope to specific labels
book_response = db.ai.get_ontology({"labels": ["Book"]})
book_schema = book_response.data[0]

# Get property ID for value enumeration
genre_prop = next(p for p in book_schema["properties"] if p["name"] == "genre")
genres = db.properties.values(genre_prop["id"])

# Identify semantically searchable properties
indexed = [p for p in book_schema["properties"] if p.get("vectorIndexes")]
# indexed[0]["vectorIndexes"][0]["status"] == "ready" → queryable with db.ai.search()

# Bypass the 1-hour cache
fresh_response = db.ai.get_ontology({"force": True})

TSTypeScript

db.ai.getOntology()

// List all labels with counts
const { data: ontology } = await db.ai.getOntology()
for (const item of ontology) {
  console.log(`${item.label}: ${item.count} records`)
}

// Get property ID for value enumeration
const {
  data: [bookSchema]
} = await db.ai.getOntology({ labels: ['Book'] })
const genreProp = bookSchema.properties.find((p) => p.name === 'genre')
const { data: genres } = await db.properties.values({ id: genreProp.id })

// Identify semantically-searchable properties
const indexed = bookSchema.properties.filter((p) => p.vectorIndexes?.length)
// indexed[0].vectorIndexes[0].status === 'ready' → queryable with db.ai.search()

// Bypass the 1-hour cache
const { data: fresh } = await db.ai.getOntology({ force: true })

shell

POST /api/v1/ai/ontology

# Full schema (structured JSON)
curl -X POST https://api.rushdb.com/api/v1/ai/ontology \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{}'

# Scoped to specific labels
curl -X POST https://api.rushdb.com/api/v1/ai/ontology \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"labels": ["Book"]}'

TypeScript types

type OntologyItem = {
  label: string
  count: number
  properties: OntologyProperty[]
  relationships: OntologyRelationship[]
}

type OntologyProperty = {
  id: string // use with db.properties.values()
  name: string
  type: string // 'string' | 'number' | 'boolean' | 'datetime'
  values?: Array<string | number> // up to 10 samples (string/boolean only)
  min?: number | string // number/datetime only
  max?: number | string
  /** Non-empty when embedding indexes exist — property is queryable with db.ai.search() */
  vectorIndexes?: OntologyVectorIndex[]
}

type OntologyVectorIndex = {
  id: string
  sourceType: string // 'managed' | 'external'
  similarityFunction: string // 'cosine' | 'euclidean'
  dimensions: number
  status: string // 'pending' | 'indexing' | 'ready' | 'error'
  modelKey: string
}

type OntologyRelationship = {
  label: string
  type: string
  direction: 'in' | 'out'
}

---

Caching

Caching

Both methods share a 1-hour cache per project. The first call after TTL expiry triggers a full graph scan; all subsequent calls within the hour are instant. Pass { force: true } to bypass the cache and trigger an immediate recalculation.

---

Agent Skills

@rushdb/skills is a collection of Agent Skills — installable instructions that teach any skills-compatible AI agent (Claude, GitHub Copilot, Cursor, Windsurf, and others) to use RushDB efficiently, without manual system-prompt engineering.

npx skills add rush-db/rushdb --path packages/skills

Skill	What it teaches
rushdb-query-builder	Discovery-first workflow, SearchQuery syntax, aggregation, relationship traversal, and semantic search
rushdb-agent-memory	Using RushDB as persistent structured memory — store, link, and semantically recall sessions, decisions, and entities
rushdb-data-modeling	LMPG model design, label/property naming conventions, nested JSON import, and schema evolution
rushdb-faceted-search	Build faceted filter UIs — discover properties and types, enumerate distinct values, map to widgets, assemble a live where clause
rushdb-domain-template	Design a tailored schema for any domain through guided conversation — interview, entity/relationship mapping, bootstrap payload, and 10 built-in domain templates

Each skill bundles a SKILL.md with concise instructions and optional reference files (like the full SearchQuery spec) that the agent loads on demand.

MCP server vs. Agent Skills

The MCP server gives agents direct tool access to RushDB at runtime. Agent Skills teach agents how to use those tools correctly — they complement each other.

---

See also

• Labels & Properties — enumerate schema at a low level
• Semantic Search — use indexed properties for similarity search
• Manage Embedding Indexes — view index status in ontology output