Embedding Indexes

An embedding index is a policy that tells RushDB to vectorize a specific string property for a label. Once status is ready, every record matching that label+property pair is searchable via POST /api/v1/ai/search.

---

How indexes work

Indexes are scoped to (label, propertyName). Book:description and Article:description are completely independent — they maintain separate vector stores and never interfere.

Index policy
  label:          "Book"
  propertyName:   "description"
  sourceType:     "managed"
  dimensions:     1536
  status:         "ready"

↓  backfill runs automatically

Each Book record gets one vector in the index, bound to the record;
the record's own properties are unchanged.

When new records are created or existing records are updated, the index transitions back to pending and vectors are recomputed on the next backfill cycle.

---

List Embedding Indexes

GET /api/v1/ai/indexes

Returns all embedding index policies for the project.

Example Response

{
  "data": [
    {
      "id": "idx_abc123",
      "projectId": "proj_xyz",
      "label": "Article",
      "propertyName": "description",
      "sourceType": "managed",
      "similarityFunction": "cosine",
      "modelKey": "text-embedding-3-small",
      "dimensions": 1536,
      "vectorPropertyName": "_emb_managed_cosine_1536",
      "enabled": true,
      "status": "ready",
      "createdAt": "2025-01-10T12:00:00.000Z",
      "updatedAt": "2025-01-10T12:05:00.000Z"
    }
  ],
  "success": true
}

---

Create Embedding Index

POST /api/v1/ai/indexes

Creates a new embedding index policy scoped to a label. If the property already exists in the graph, its type must be string (scalar or list). If no records with this property exist yet, the index is created without type validation — the property appears in the catalog when the first record carrying it is written.

Request Body

Field	Type	Required	Description
name	string	no	Unique within the project: 1–64 letters, digits, ., _, : or -. Defaults to <label>.<property>.<model>.<dimensions>.<similarity>; POST /api/v1/ai/indexes/name-suggestion returns it.
label	string	yes	Label to scope this index to (e.g. "Article", "Product")
propertyName	string	yes	Name of the property to embed (e.g. "description")
sourceType	string	no	"managed" (default) or "external". See Advanced Indexing.
similarityFunction	string	no	"cosine" (default) or "euclidean"
dimensions	number	no	Vector length. Defaults to the managed model's dimensions. Required for external indexes.

The managed model is RushDB Cloud's. Each index records the model it was embedded with as modelKey.

Example — simplest form

curl -X POST https://api.rushdb.com/api/v1/ai/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"label": "Article", "propertyName": "description"}'

Example — with explicit parameters

curl -X POST https://api.rushdb.com/api/v1/ai/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{
    "label": "Article",
    "propertyName": "description",
    "similarityFunction": "cosine",
    "dimensions": 1536
  }'

Example Response

{
  "data": {
    "id": "idx_abc123",
    "label": "Article",
    "propertyName": "description",
    "sourceType": "managed",
    "similarityFunction": "cosine",
    "dimensions": 1536,
    "status": "pending"
  },
  "success": true
}

Index lifecycle

Status	Description
pending	Policy created, waiting for backfill scheduler
indexing	Backfill in progress
awaiting_vectors	External index — waiting for client to push vectors
ready	All existing records have vectors; search is available
error	Backfill failed; check server logs for the cause

Error cases

Status	When
422	The property exists in the graph but is not string type
422	Embedding model is not configured on the server
409	An index for this (label, propertyName, sourceType, similarityFunction, dimensions) tuple already exists

---

Delete Embedding Index

DELETE /api/v1/ai/indexes/:id

Deletes an embedding index policy and its vectors. :id accepts the index's name as well as its id.

Example Request

curl -X DELETE https://api.rushdb.com/api/v1/ai/indexes/idx_abc123 \
  -H "Authorization: Bearer $RUSHDB_API_KEY"

Example Response

{ "data": { "deleted": true }, "success": true }

---

Get Embedding Index Stats

GET /api/v1/ai/indexes/:id/stats

Returns the current indexing progress — useful for progress monitoring or health checks before running search.

Example Response

{
  "data": {
    "totalRecords": 1840,
    "indexedRecords": 1234
  },
  "success": true
}

---

Waiting for an index to become ready

For managed indexes, backfill runs asynchronously. Poll GET /api/v1/ai/indexes until status is ready:

# Shell polling loop
while true; do
  STATUS=$(curl -s https://api.rushdb.com/api/v1/ai/indexes \
    -H "Authorization: Bearer $RUSHDB_API_KEY" | \
    jq -r '.data[] | select(.id == "idx_abc123") | .status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "ready" ]; then break; fi
  if [ "$STATUS" = "error" ]; then echo "Index entered error state" && exit 1; fi
  sleep 3
done

Or in JavaScript:

async function waitForIndexReady(apiKey, indexId, timeoutMs = 90_000) {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
    const res = await fetch('https://api.rushdb.com/api/v1/ai/indexes', {
      headers: { Authorization: `Bearer ${apiKey}` }
    })
    const { data: indexes } = await res.json()
    const idx = indexes.find((i) => i.id === indexId)
    if (idx?.status === 'ready') return
    if (idx?.status === 'error') throw new Error('Index entered error state')
    await new Promise((r) => setTimeout(r, 3_000))
  }
  throw new Error('Index did not become ready in time')
}

---

Multiple indexes on the same property

You can have more than one index per (label, propertyName) pair, provided the signature differs (sourceType, similarityFunction, or dimensions):

# Cosine index
curl -X POST https://api.rushdb.com/api/v1/ai/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"label": "Product", "propertyName": "description", "similarityFunction": "cosine", "dimensions": 768}'

# Euclidean index on the same property
curl -X POST https://api.rushdb.com/api/v1/ai/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{"label": "Product", "propertyName": "description", "similarityFunction": "euclidean", "dimensions": 768}'

When searching or writing vectors against a property with multiple indexes, specify similarityFunction to disambiguate. See Advanced Indexing for details.

---

Index response shape

{
  "id": "string",
  "projectId": "string",
  "label": "string",
  "propertyName": "string",
  "modelKey": "string",
  "sourceType": "managed | external",
  "similarityFunction": "cosine | euclidean",
  "dimensions": 1536,
  "vectorPropertyName": "string",
  "enabled": true,
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

---

String Array Properties

List<String>

String array properties are supported. Each item in the array is embedded individually, then mean-pooled into a single vector stored on the relationship.