AntflyAntfly

Index Management#

Create and manage indexes for full-text search, vector similarity search, and multimodal content.

Index Types#

Antfly supports two primary index types:

full_text - Full-Text Search Index#

BM25-based full-text search using Antfly's native Zig full-text index (a segmented, Lucene-style inverted index). Automatically uses schema information for field mappings.

Configuration:

{
  "type": "full_text",
  "name": "search_idx",
  "mem_only": false
}

Options:

  • mem_only (optional): If true, stores index in memory only (useful for testing)

Features:

  • BM25 ranking algorithm
  • Field-specific queries (title:computer)
  • Boolean operators (AND, OR, NOT)
  • Range queries (year:>2020)
  • Phrase queries ("exact phrase")
  • Uses schema's x-antfly-types for field analyzers
  • Respects x-antfly-include-in-all for cross-field search

embeddings - Vector Similarity Index#

Approximate k-nearest neighbors (AKNN) index for semantic similarity search using vector embeddings.

Performance Features:

  • Hardware-accelerated distance calculations using SIMD instructions
  • x86/AMD: AVX2 and AVX-512 optimizations for vector operations
  • ARM: NEON and SME (Scalable Matrix Extension) acceleration
  • RaBitQ quantization for reduced memory footprint and faster search
  • No GPU required - optimized for CPU-based deployments

Basic Configuration:

{
  "type": "embeddings",
  "name": "embedding_idx",
  "field": "description",
  "embedder": {
    "provider": "ollama",
    "model": "all-minilm",
    "url": "http://localhost:11434"
  }
}

Index Modes:

Managed indexes (external: false, default)

  • Antfly owns embedding generation
  • Must specify field or template
  • Must specify embedder
  • Reject manual _embeddings writes for that index

External indexes (external: true)

  • Your application owns embedding generation
  • Must not specify field, template, or embedder
  • Dense external indexes must specify dimension
  • Vectors are written directly through the document _embeddings field

Managed Index Fields:

  • field: Field to embed using JSONPath syntax (e.g., "description", "metadata.content", "$.user.bio")
  • template: Handlebars template for custom prompt generation
  • embedder: Embedder configuration for generating vectors
  • dimension: Optional for dense indexes; inferred from the embedder if omitted
  • mem_only: Store index in memory only

External Index Fields:

  • external: true
  • dimension: Required for dense indexes
  • sparse: true: Use sparse vectors supplied through _embeddings

External Dense Example:

{
  "type": "embeddings",
  "name": "manual_dense_idx",
  "external": true,
  "dimension": 384
}

External Sparse Example:

{
  "type": "embeddings",
  "name": "manual_sparse_idx",
  "external": true,
  "sparse": true
}

Writing Manual Embeddings:

  • Manual _embeddings writes are only accepted for external: true indexes
  • Dense vectors use arrays: "_embeddings": { "manual_dense_idx": [0.1, 0.2, 0.3] }
  • Sparse vectors use token-weight maps: "_embeddings": { "manual_sparse_idx": { "7": 1.5, "42": 2.0 } }
  • Explicit delete uses null: "_embeddings": { "manual_dense_idx": null }
  • Omitting _embeddings[<index>] is a no-op; it does not delete the stored vector

Embedder Providers#

Managed index creation supports antfly, ollama, openai, and bedrock through the purpose-specific IndexEmbedderConfig. Other providers in the broader EmbedderConfig are available only on surfaces whose runtime can execute them.

Antfly Inference#

{
  "provider": "antfly",
  "model": "BAAI/bge-small-en-v1.5"
}

Ollama (Local Models)#

{
  "provider": "ollama",
  "model": "all-minilm",
  "url": "http://localhost:11434"
}

Popular models: all-minilm, nomic-embed-text, mxbai-embed-large

OpenAI#

{
  "provider": "openai",
  "model": "text-embedding-3-small",
  "api_key": "sk-..."
}

Models: text-embedding-3-small (1536d), text-embedding-3-large (3072d), text-embedding-ada-002 (1536d)

AWS Bedrock#

{
  "provider": "bedrock",
  "model": "amazon.titan-embed-text-v1",
  "region": "us-east-1"
}

Models: amazon.titan-embed-text-v1, amazon.titan-embed-text-v2, cohere.embed-english-v3, cohere.embed-multilingual-v3

Multimodal Indexing#

EmbeddingsIndexConfig does not accept a summarizer. For two-stage multimodal indexing, generate a textual description into a document field before indexing and configure the managed index against that field. If the application already owns the final vectors, use an external: true index and write them through _embeddings.

Template-Based Prompts#

Customize how documents are converted to text before embedding using Handlebars templates:

{
  "type": "embeddings",
  "dimension": 384,
  "field": "description",
  "template": "Product: {{title}}\nCategory: {{category}}\nDescription: {{description}}",
  "embedder": {
    "provider": "ollama",
    "model": "all-minilm"
  }
}

Template System:

  • Syntax: Handlebars templating (https://handlebarsjs.com/guide/)
  • Caching: Templates are automatically cached with configurable TTL (default: 5 minutes)
  • Context: Templates receive the full document as context

Basic Syntax:

  • {{fieldName}}: Insert field value
  • {{#if field}}...{{/if}}: Conditional logic
  • {{#each array}}...{{/each}}: Iterate arrays
  • {{#unless condition}}...{{/unless}}: Inverse conditional
  • {{@index}}, {{@key}}, {{@first}}, {{@last}}: Loop variables

Built-in Helpers:

  1. scrubHtml - Remove script/style tags and extract clean text from HTML

    {{scrubHtml html_content}}
    • Removes <script> and <style> tags
    • Adds newlines after block elements (p, div, h1-h6, li, etc.)
    • Returns plain text with preserved readability

  2. eq - Equality comparison for conditionals

    {{#if (eq status "active")}}Active{{/if}}
{{#if (eq @key "special")}}Special field{{/if}}

  3. media - GenKit dotprompt media directive for multimodal content

    {{media url=imageDataURI}}
{{media url=this.image_url}}
{{media url="https://example.com/image.jpg"}}
{{media url="s3://endpoint/bucket/image.png"}}
{{media url="file:///path/to/image.jpg"}}

    Supported URL Schemes:

    • data: - Base64 encoded data URIs (e.g., data:image/jpeg;base64,...)
    • http:// / https:// - Web URLs with automatic content type detection
    • file:// - Local filesystem paths
    • s3:// - S3-compatible storage (format: s3://endpoint/bucket/key)

    Automatic Content Processing:

    • Images: Downloaded, resized (if needed), converted to data URIs
    • PDFs: Text extracted or first page rendered as image
    • HTML: Readable text extracted using Mozilla Readability

    Security Controls: Downloads are protected by content security settings:

    • Allowed host whitelist
    • Private IP blocking (prevents SSRF attacks)
    • Download size limits (default: 100MB)
    • HTTP downloads time out after 30 seconds by default; zero disables the deadline
    • Image dimension limits (default: 2048px, auto-resized)

    See: https://antfly.io/docs/configuration#security--cors

  4. encodeToon is not available in these templates. It is a helper of the retrieval agent's document_renderer, which renders documents into the generation prompt as TOON by default.

Without a template, the field value is used directly, or the entire document is serialized.

Field Extraction with JSONPath#

The field parameter supports JSONPath syntax for extracting values from nested document structures:

{
  "type": "embeddings",
  "field": "metadata.description",
  "embedder": {"provider": "ollama", "model": "all-minilm"}
}

JSONPath Examples:

  • "title" - Top-level field
  • "user.bio" - Nested field (auto-prepends $. if not present)
  • "$.metadata.content" - Explicit JSONPath
  • "$.items[0].name" - Array indexing

The extracted value must be a string. Use template for complex transformations or combining multiple fields.

Configuration Examples#

Simple Text Embedding#

{
  "type": "embeddings",
  "field": "content",
  "embedder": {
    "provider": "ollama",
    "model": "all-minilm"
  }
}

Note: dimension is omitted and will be inferred from the all-minilm model (384).

Text Embedding with Custom Template#

{
  "type": "embeddings",
  "dimension": 1536,
  "template": "{{title}}: {{description}}",
  "embedder": {
    "provider": "openai",
    "model": "text-embedding-3-small"
  }
}

Production OpenAI Setup#

{
  "type": "embeddings",
  "dimension": 1536,
  "field": "body",
  "embedder": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "api_key": "${OPENAI_API_KEY}"
  }
}

Best Practices#

  • Choose dimension wisely: Higher dimensions improve accuracy but increase storage/compute costs
  • Use templates for structured data: Combine multiple fields into meaningful prompts
  • Local vs Cloud: Ollama for development/privacy, cloud providers for production/scale
  • Field specification: Specify field when embedding a single field to avoid whole-document serialization

To implement autocomplete/search-as-you-type functionality:

1. Define schema with search_as_you_type type:

{
  "document_schemas": {
    "product": {
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "x-antfly-types": ["text", "search_as_you_type"]
          }
        }
      }
    }
  }
}

2. Create full-text index:

{
  "indexes": {
    "search_idx": {
      "type": "full_text"
    }
  }
}

3. Query with bool-prefix multi-match:

{
  "full_text_search": {
    "multi_match": {
      "query": "lap",
      "type": "bool_prefix",
      "fields": ["name"]
    }
  }
}

The search_as_you_type type creates shingle and prefix subfields that match partial input as users type. For example, "lap" matches "laptop", "lapel", etc.

Reindexing Data#

What happens when you need to reindex? Antfly handles reindexing through async enrichment, automatically rebuilding indexes in the background. Here's what to expect when reindexing data (after adding a new index or changing configuration):

Adding a New Index to Existing Table#

Antfly handles reindexing automatically through async enrichment:

1. Add the index:

POST /tables/{tableName}/indexes/{indexName}
{
  "type": "embeddings",
  "embedder": {...}
}

2. Enrichment happens automatically:

  • Existing documents are enriched in the background
  • New writes are enriched immediately
  • Leader-only processing prevents duplicate work
  • Check index status to monitor progress

3. Monitor progress:

GET /tables/{tableName}/indexes/{indexName}

Look at shard_status for enrichment progress per shard.

Error Handling for Async Enrichment#

When embedding generation or enrichment fails, Antfly handles errors gracefully:

Retry Behavior:

  • Failed enrichments are automatically retried with exponential backoff
  • Leader-only processing ensures no duplicate work during retries
  • Enrichment continues for other documents even if some fail

Monitoring Failures:

  • Check index status (GET /tables/{table}/indexes/{index}) for error counts
  • Prometheus metrics expose enrichment failure rates
  • Failed documents remain searchable via full-text index (if configured)

Common Failure Scenarios:

  1. Embedding API Unavailable

    • Enrichment retries automatically when service recovers
    • Documents remain indexed (without embeddings) for full-text search
    • Use sync_level: enrichments to precompute enrichments before committing. A synchronous producer failure rejects the write. Failures detected after a document has committed retain it and may report committed_repair_required so operators can repair the derived state.

  2. Rate Limiting

    • Automatic backoff and retry
    • Consider using local Ollama to avoid rate limits
    • Or increase API quota with embedding provider

  3. Model Errors (invalid input, size limits)

    • Logged with document ID for investigation
    • Retries stop after max attempts
    • Document remains in table without enrichment

Changing Index Configuration#

To change index configuration:

  1. Drop the existing index: DELETE /tables/{table}/indexes/{index}
  2. Recreate with new config: POST /tables/{table}/indexes/{index}
  3. Existing data is automatically re-enriched

Note: Full-text indexes (full_text) reindex immediately on creation and automatically rebuild when schema changes are made. Vector indexes (embeddings) enrich asynchronously in the background.

Backup Before Major Reindexing#

For large datasets, backup before reindexing:

POST /tables/{tableName}/backup
{
  "backup_id": "before-reindex-2025-01",
  "location": "s3://mybucket/backups/products"
}

Graph Indexes and Edge TTL#

Graph indexes (graph) enable relationship modeling and traversal queries. Edge TTL is under development. The stateful runtime currently stamps edge artifacts and selects live projected contributors for adjacency reads, but authoritative cleanup, metric invalidation, and serverless visibility are not complete. Do not rely on graph TTL in production until those pieces are implemented.

Graph Index Overview#

Graph indexes store directed edges between documents, enabling queries like:

  • Finding all connections from a document
  • Traversing multi-hop paths
  • Filtering relationships by type

Basic graph index:

{
  "type": "graph",
  "name": "social_graph"
}

Edge TTL Configuration#

Graph indexes accept an index-level ttl.duration policy. The legacy ttl_duration field is an alias; do not specify both.

{
  "type": "graph",
  "name": "recent_interactions",
  "ttl": {"duration": "7d"}
}

The duration uses the same format as document TTL, such as 30s, 5m, 24h, or 7d. Each source contribution receives a server-assigned creation timestamp. Stateful graph reads filter expired contributions and select the highest-priority live source when sources overlap.

Graph TTL is currently incomplete. There is no authoritative edge cleanup worker, published graph metric invalidation at a deadline, or serverless segment expiration filter. See zig/GRAPH.md for the design and current implementation status.

Execute a graph metric operational action#

POST/tables/{tableName}/indexes/{indexName}/graph-metrics/{metricName}:{action}

Refresh, rebuild, delete, pause, or resume maintenance for a configured graph metric. The metric configuration remains owned by the graph index. Refresh and rebuild durably enqueue bounded, resumable maintenance and return the aggregate shard status without waiting for graph-sized work. delete clears materialized metric state and durably disables automatic maintenance. A later refresh, rebuild, or resume action re-enables the metric and can publish a new generation.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/indexes/{indexName}/graph-metrics/{metricName}:{action}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "status": {
    "state": "string",
    "phase": "idle",
    "edge_filter": {
      "mode": "all",
      "types": [
        "string"
      ]
    },
    "metadata_version": 0,
    "config_fingerprint": "string",
    "maintenance_paused": true,
    "build_queued": true,
    "published_generation": 0,
    "edge_generation": 0,
    "target_edge_generation": 0,
    "queued_generation": 0,
    "building_generation": 0,
    "build_job_id": 0,
    "build_started_at_ms": 0,
    "build_iteration": 0,
    "build_lease_expires_at_ms": 0,
    "build_worker_id": "string",
    "build_cursor": "string",
    "build_completed_units": 0,
    "build_total_units": 0,
    "build_pages": [
      {
        "phase": "string",
        "iteration": 0,
        "page_id": 0,
        "state": "pending",
        "range_kind": "full",
        "worker_id": "string",
        "lease_expires_at_ms": 0,
        "attempt": 0,
        "cursor": "string",
        "completed_units": 0,
        "total_units": 0,
        "last_error": "string"
      }
    ],
    "build_pages_truncated": true,
    "retry_count": 0,
    "last_error": "string",
    "progress": 0,
    "converged": true,
    "iterations_completed": 0,
    "delta": 0,
    "computed_at_ms": 0,
    "last_event": {
      "sequence": 0,
      "kind": "publish",
      "at_ms": 0,
      "target_edge_generation": 0,
      "published_generation": 0,
      "score_count": 0
    },
    "recent_events": [
      {
        "sequence": 0,
        "kind": "publish",
        "at_ms": 0,
        "target_edge_generation": 0,
        "published_generation": 0,
        "score_count": 0
      }
    ]
  }
}

Execute a graph metric operational action#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/graph-metrics/{metricName}:{action}

Refresh, rebuild, delete, pause, or resume maintenance for a configured graph metric. The metric configuration remains owned by the graph index. Refresh and rebuild durably enqueue bounded, resumable maintenance and return the aggregate shard status without waiting for graph-sized work. delete clears materialized metric state and durably disables automatic maintenance. A later refresh, rebuild, or resume action re-enables the metric and can publish a new generation.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/graph-metrics/{metricName}:{action}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "status": {
    "state": "string",
    "phase": "idle",
    "edge_filter": {
      "mode": "all",
      "types": [
        "string"
      ]
    },
    "metadata_version": 0,
    "config_fingerprint": "string",
    "maintenance_paused": true,
    "build_queued": true,
    "published_generation": 0,
    "edge_generation": 0,
    "target_edge_generation": 0,
    "queued_generation": 0,
    "building_generation": 0,
    "build_job_id": 0,
    "build_started_at_ms": 0,
    "build_iteration": 0,
    "build_lease_expires_at_ms": 0,
    "build_worker_id": "string",
    "build_cursor": "string",
    "build_completed_units": 0,
    "build_total_units": 0,
    "build_pages": [
      {
        "phase": "string",
        "iteration": 0,
        "page_id": 0,
        "state": "pending",
        "range_kind": "full",
        "worker_id": "string",
        "lease_expires_at_ms": 0,
        "attempt": 0,
        "cursor": "string",
        "completed_units": 0,
        "total_units": 0,
        "last_error": "string"
      }
    ],
    "build_pages_truncated": true,
    "retry_count": 0,
    "last_error": "string",
    "progress": 0,
    "converged": true,
    "iterations_completed": 0,
    "delta": 0,
    "computed_at_ms": 0,
    "last_event": {
      "sequence": 0,
      "kind": "publish",
      "at_ms": 0,
      "target_edge_generation": 0,
      "published_generation": 0,
      "score_count": 0
    },
    "recent_events": [
      {
        "sequence": 0,
        "kind": "publish",
        "at_ms": 0,
        "target_edge_generation": 0,
        "published_generation": 0,
        "score_count": 0
      }
    ]
  }
}

List table artifact enrichments#

GET/tables/{tableName}/artifacts

Returns table-level generated artifact enrichments configured for a table, including enrichments declared inline by indexes. This is the artifact control-plane view; use the document artifact routes to inspect materialized manifests for a specific source document.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/artifacts" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "table_name": "string",
  "artifacts": [
    {
      "name": "string",
      "kind": "chunk",
      "source": {
        "group_by": "string",
        "order_by": "string",
        "segment_by": "string",
        "field": "string",
        "filter": {},
        "max_bytes": 1,
        "max_members": 1,
        "window_ordinals": 1
      },
      "prior_context": {
        "artifact": "string",
        "render": "string",
        "max_items": 1,
        "max_bytes": 1,
        "horizon_segments": 1
      },
      "field": "string",
      "template": "string",
      "source_artifact_name": "string",
      "expected_dims": 0,
      "vector_space": "string",
      "chunk_size": 0,
      "chunk_overlap": 0,
      "chunker": {
        "provider": "antfly",
        "model": "fixed",
        "text": {
          "target_tokens": 500,
          "overlap_tokens": 50
        }
      },
      "chunker_json": "string",
      "full_text_index": true,
      "content_type": "string",
      "producer": {
        "type": "copy",
        "config": {
          "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
          },
          "instructions": "string",
          "output_schema": {},
          "output": "auto",
          "batch": {
            "max_items_per_call": 1,
            "max_input_bytes": 1
          }
        }
      },
      "producer_json": "string",
      "neighbor_context": {
        "graph_index": "string",
        "edge_types": [
          "string"
        ],
        "direction": "out",
        "limit": 1
      },
      "execution": {
        "batch_items": 1,
        "batch_bytes": 1,
        "max_document_pages": 1
      },
      "transcriber": {
        "provider": "openai",
        "model": "string",
        "api_url": "https://example.com",
        "base_url": "https://example.com",
        "api_key": "string",
        "project_id": "string",
        "location": "string",
        "credentials_path": "string",
        "language_code": "string",
        "timestamps": true,
        "diarization": true,
        "max_download_bytes": 1,
        "download_assets": true
      }
    }
  ]
}

Register or replace an artifact enrichment#

PUT/tables/{tableName}/artifacts/{artifactName}/enrichment

Registers a table-level generated artifact definition. Reusing the same artifact name replaces the existing mapping. Chunk or asset enrichments may set full_text_index: true to map generated text into the table's default full-text index.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "name": "string",
    "kind": "chunk",
    "source": {
        "group_by": "string",
        "order_by": "string",
        "segment_by": "string",
        "field": "string",
        "filter": {},
        "max_bytes": 1,
        "max_members": 1,
        "window_ordinals": 1
    },
    "prior_context": {
        "artifact": "string",
        "render": "string",
        "max_items": 1,
        "max_bytes": 1,
        "horizon_segments": 1
    },
    "field": "string",
    "template": "string",
    "source_artifact_name": "string",
    "expected_dims": 0,
    "vector_space": "string",
    "chunk_size": 0,
    "chunk_overlap": 0,
    "chunker": {
        "provider": "antfly",
        "model": "fixed",
        "text": {
            "target_tokens": 500,
            "overlap_tokens": 50
        }
    },
    "chunker_json": "string",
    "full_text_index": true,
    "content_type": "string",
    "producer": {
        "type": "copy",
        "config": {
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "instructions": "string",
            "output_schema": {},
            "output": "auto",
            "batch": {
                "max_items_per_call": 1,
                "max_input_bytes": 1
            }
        }
    },
    "producer_json": "string",
    "neighbor_context": {
        "graph_index": "string",
        "edge_types": [
            "string"
        ],
        "direction": "out",
        "limit": 1
    },
    "execution": {
        "batch_items": 1,
        "batch_bytes": 1,
        "max_document_pages": 1
    },
    "transcriber": {
        "provider": "openai",
        "model": "string",
        "api_url": "https://example.com",
        "base_url": "https://example.com",
        "api_key": "string",
        "project_id": "string",
        "location": "string",
        "credentials_path": "string",
        "language_code": "string",
        "timestamps": true,
        "diarization": true,
        "max_download_bytes": 1,
        "download_assets": true
    }
}

Code Examples#

curl -X PUT "/db/v1/tables/{tableName}/artifacts/{artifactName}/enrichment" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "string",
    "kind": "chunk",
    "source": {
        "group_by": "string",
        "order_by": "string",
        "segment_by": "string",
        "field": "string",
        "filter": {},
        "max_bytes": 1,
        "max_members": 1,
        "window_ordinals": 1
    },
    "prior_context": {
        "artifact": "string",
        "render": "string",
        "max_items": 1,
        "max_bytes": 1,
        "horizon_segments": 1
    },
    "field": "string",
    "template": "string",
    "source_artifact_name": "string",
    "expected_dims": 0,
    "vector_space": "string",
    "chunk_size": 0,
    "chunk_overlap": 0,
    "chunker": {
        "provider": "antfly",
        "model": "fixed",
        "text": {
            "target_tokens": 500,
            "overlap_tokens": 50
        }
    },
    "chunker_json": "string",
    "full_text_index": true,
    "content_type": "string",
    "producer": {
        "type": "copy",
        "config": {
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "instructions": "string",
            "output_schema": {},
            "output": "auto",
            "batch": {
                "max_items_per_call": 1,
                "max_input_bytes": 1
            }
        }
    },
    "producer_json": "string",
    "neighbor_context": {
        "graph_index": "string",
        "edge_types": [
            "string"
        ],
        "direction": "out",
        "limit": 1
    },
    "execution": {
        "batch_items": 1,
        "batch_bytes": 1,
        "max_document_pages": 1
    },
    "transcriber": {
        "provider": "openai",
        "model": "string",
        "api_url": "https://example.com",
        "base_url": "https://example.com",
        "api_key": "string",
        "project_id": "string",
        "location": "string",
        "credentials_path": "string",
        "language_code": "string",
        "timestamps": true,
        "diarization": true,
        "max_download_bytes": 1,
        "download_assets": true
    }
}'

Responses#

{}

Delete an artifact enrichment#

DELETE/tables/{tableName}/artifacts/{artifactName}/enrichment

Removes the table-level generated artifact definition. Local table reconciliation drops no-longer-desired enrichment registrations when it is safe to do so.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X DELETE "/db/v1/tables/{tableName}/artifacts/{artifactName}/enrichment" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{}

List all indexes for a table#

GET/tables/{tableName}/indexes

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/indexes" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

[
  {
    "shard_status": {},
    "config": {
      "name": "string",
      "description": "string",
      "version": 0,
      "enrichments": [
        {
          "name": "string",
          "kind": "chunk",
          "source": {
            "group_by": "string",
            "order_by": "string",
            "segment_by": "string",
            "field": "string",
            "filter": {},
            "max_bytes": 1,
            "max_members": 1,
            "window_ordinals": 1
          },
          "prior_context": {
            "artifact": "string",
            "render": "string",
            "max_items": 1,
            "max_bytes": 1,
            "horizon_segments": 1
          },
          "field": "string",
          "template": "string",
          "source_artifact_name": "string",
          "expected_dims": 0,
          "vector_space": "string",
          "chunk_size": 0,
          "chunk_overlap": 0,
          "chunker": {
            "provider": "antfly",
            "model": "fixed",
            "text": {
              "target_tokens": 500,
              "overlap_tokens": 50
            }
          },
          "chunker_json": "string",
          "full_text_index": true,
          "content_type": "string",
          "neighbor_context": {
            "graph_index": "string",
            "edge_types": [
              "string"
            ],
            "direction": "out",
            "limit": 1
          },
          "execution": {
            "batch_items": 1,
            "batch_bytes": 1,
            "max_document_pages": 1
          }
        }
      ]
    },
    "status": {
      "index_type": "full_text",
      "readiness": {
        "state": "pending",
        "queryable": true,
        "complete": true,
        "incarnation": "string",
        "target_revision": 0,
        "published_revision": 0,
        "pending_reasons": [
          "load_failure"
        ],
        "sources": [
          {
            "artifact": "string",
            "state": "pending",
            "complete": true,
            "pending_reasons": [
              "index_failed"
            ]
          }
        ]
      },
      "incarnation": "string",
      "target_revision": 0,
      "published_revision": 0,
      "milestones": {
        "queryable": {
          "reached": true,
          "blockers": [
            "string"
          ]
        },
        "complete": {
          "reached": true,
          "blockers": [
            "string"
          ]
        }
      },
      "error": "string",
      "total_indexed": 0,
      "disk_usage": 0,
      "rebuilding": true,
      "repair": {
        "state": "rebuilding",
        "action_required": true,
        "blocks_queryable": true,
        "blocks_complete": true,
        "reason": "string"
      },
      "backfill_active": true,
      "backfill_progress": 0,
      "backfill_items_processed": 0,
      "backfill_state": "string",
      "doc_count": 0,
      "term_count": 0,
      "replay_applied_sequence": 0,
      "replay_target_sequence": 0,
      "replay_catch_up_required": true,
      "runtime_present": true,
      "runtime_fresh": true,
      "runtime_source": "string",
      "runtime_freshness": "string",
      "catch_up_active": true,
      "catch_up_phase": "string",
      "catch_up_applied_sequence": 0,
      "catch_up_target_sequence": 0,
      "text_merge": {},
      "async_indexing": {},
      "projection_checkpoint_status": "string",
      "projection_checkpoint_applied_sequence": 0,
      "projection_checkpoint_generation": 0,
      "projection_checkpoint_config_fingerprint": "string",
      "checkpoint_replay_tail_sequence_count": 0,
      "repair_scan_issue_count": 0,
      "edge_count": 0,
      "node_count": 0,
      "repair_degraded": true,
      "repair_issue_count": 0,
      "repair_summary_ready": true,
      "repair_issue_count_estimated": true,
      "expected_groups": 0,
      "reported_groups": 0,
      "fresh_groups": 0,
      "stale_groups": 0,
      "missing_groups": 0,
      "unknown_remote_groups": 0,
      "resolution": {},
      "promotion": {}
    }
  }
]

Retry a failed index build#

POST/tables/{tableName}/indexes/{indexName}/retry

Generation-fenced relational index maintenance. Requires table ADMIN permission. Retry accepts failed generations. Owners are admitted independently and durably; exact request replay resumes after partial acknowledgements. Unsupported index types return 405.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/indexes/{indexName}/retry" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}'

Responses#

{
  "acknowledged_groups": [
    "string"
  ]
}

Repair an index generation#

POST/tables/{tableName}/indexes/{indexName}/repair

Generation-fenced relational index maintenance. Requires table ADMIN permission. Repair accepts ready or failed generations and rebuilds their derived records. Owners are admitted independently and durably; exact request replay resumes after partial acknowledgements. Unsupported index types return 405.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/indexes/{indexName}/repair" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}'

Responses#

{
  "acknowledged_groups": [
    "string"
  ]
}

Add an index to a table#

POST/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "description": "string",
    "version": 0,
    "enrichments": [
        {
            "name": "string",
            "kind": "chunk",
            "source": {
                "group_by": "string",
                "order_by": "string",
                "segment_by": "string",
                "field": "string",
                "filter": {},
                "max_bytes": 1,
                "max_members": 1,
                "window_ordinals": 1
            },
            "prior_context": {
                "artifact": "string",
                "render": "string",
                "max_items": 1,
                "max_bytes": 1,
                "horizon_segments": 1
            },
            "field": "string",
            "template": "string",
            "source_artifact_name": "string",
            "expected_dims": 0,
            "vector_space": "string",
            "chunk_size": 0,
            "chunk_overlap": 0,
            "chunker": {
                "provider": "antfly",
                "model": "fixed",
                "text": {
                    "target_tokens": 500,
                    "overlap_tokens": 50
                }
            },
            "chunker_json": "string",
            "full_text_index": true,
            "content_type": "string",
            "producer": {
                "type": "copy",
                "config": {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "instructions": "string",
                    "output_schema": {},
                    "output": "auto",
                    "batch": {
                        "max_items_per_call": 1,
                        "max_input_bytes": 1
                    }
                }
            },
            "producer_json": "string",
            "neighbor_context": {
                "graph_index": "string",
                "edge_types": [
                    "string"
                ],
                "direction": "out",
                "limit": 1
            },
            "execution": {
                "batch_items": 1,
                "batch_bytes": 1,
                "max_document_pages": 1
            },
            "transcriber": {
                "provider": "openai",
                "model": "string",
                "api_url": "https://example.com",
                "base_url": "https://example.com",
                "api_key": "string",
                "project_id": "string",
                "location": "string",
                "credentials_path": "string",
                "language_code": "string",
                "timestamps": true,
                "diarization": true,
                "max_download_bytes": 1,
                "download_assets": true
            }
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "description": "string",
    "version": 0,
    "enrichments": [
        {
            "name": "string",
            "kind": "chunk",
            "source": {
                "group_by": "string",
                "order_by": "string",
                "segment_by": "string",
                "field": "string",
                "filter": {},
                "max_bytes": 1,
                "max_members": 1,
                "window_ordinals": 1
            },
            "prior_context": {
                "artifact": "string",
                "render": "string",
                "max_items": 1,
                "max_bytes": 1,
                "horizon_segments": 1
            },
            "field": "string",
            "template": "string",
            "source_artifact_name": "string",
            "expected_dims": 0,
            "vector_space": "string",
            "chunk_size": 0,
            "chunk_overlap": 0,
            "chunker": {
                "provider": "antfly",
                "model": "fixed",
                "text": {
                    "target_tokens": 500,
                    "overlap_tokens": 50
                }
            },
            "chunker_json": "string",
            "full_text_index": true,
            "content_type": "string",
            "producer": {
                "type": "copy",
                "config": {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "instructions": "string",
                    "output_schema": {},
                    "output": "auto",
                    "batch": {
                        "max_items_per_call": 1,
                        "max_input_bytes": 1
                    }
                }
            },
            "producer_json": "string",
            "neighbor_context": {
                "graph_index": "string",
                "edge_types": [
                    "string"
                ],
                "direction": "out",
                "limit": 1
            },
            "execution": {
                "batch_items": 1,
                "batch_bytes": 1,
                "max_document_pages": 1
            },
            "transcriber": {
                "provider": "openai",
                "model": "string",
                "api_url": "https://example.com",
                "base_url": "https://example.com",
                "api_key": "string",
                "project_id": "string",
                "location": "string",
                "credentials_path": "string",
                "language_code": "string",
                "timestamps": true,
                "diarization": true,
                "max_download_bytes": 1,
                "download_assets": true
            }
        }
    ]
}'

Responses#

{
  "name": "string",
  "description": "string",
  "version": 0,
  "enrichments": [
    {
      "name": "string",
      "kind": "chunk",
      "source": {
        "group_by": "string",
        "order_by": "string",
        "segment_by": "string",
        "field": "string",
        "filter": {},
        "max_bytes": 1,
        "max_members": 1,
        "window_ordinals": 1
      },
      "prior_context": {
        "artifact": "string",
        "render": "string",
        "max_items": 1,
        "max_bytes": 1,
        "horizon_segments": 1
      },
      "field": "string",
      "template": "string",
      "source_artifact_name": "string",
      "expected_dims": 0,
      "vector_space": "string",
      "chunk_size": 0,
      "chunk_overlap": 0,
      "chunker": {
        "provider": "antfly",
        "model": "fixed",
        "text": {
          "target_tokens": 500,
          "overlap_tokens": 50
        }
      },
      "chunker_json": "string",
      "full_text_index": true,
      "content_type": "string",
      "neighbor_context": {
        "graph_index": "string",
        "edge_types": [
          "string"
        ],
        "direction": "out",
        "limit": 1
      },
      "execution": {
        "batch_items": 1,
        "batch_bytes": 1,
        "max_document_pages": 1
      }
    }
  ]
}

Drop an index from a table#

DELETE/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X DELETE "/db/v1/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

No response body

Get index details#

GET/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "shard_status": {},
  "config": {
    "name": "string",
    "description": "string",
    "version": 0,
    "enrichments": [
      {
        "name": "string",
        "kind": "chunk",
        "source": {
          "group_by": "string",
          "order_by": "string",
          "segment_by": "string",
          "field": "string",
          "filter": {},
          "max_bytes": 1,
          "max_members": 1,
          "window_ordinals": 1
        },
        "prior_context": {
          "artifact": "string",
          "render": "string",
          "max_items": 1,
          "max_bytes": 1,
          "horizon_segments": 1
        },
        "field": "string",
        "template": "string",
        "source_artifact_name": "string",
        "expected_dims": 0,
        "vector_space": "string",
        "chunk_size": 0,
        "chunk_overlap": 0,
        "chunker": {
          "provider": "antfly",
          "model": "fixed",
          "text": {
            "target_tokens": 500,
            "overlap_tokens": 50
          }
        },
        "chunker_json": "string",
        "full_text_index": true,
        "content_type": "string",
        "neighbor_context": {
          "graph_index": "string",
          "edge_types": [
            "string"
          ],
          "direction": "out",
          "limit": 1
        },
        "execution": {
          "batch_items": 1,
          "batch_bytes": 1,
          "max_document_pages": 1
        }
      }
    ]
  },
  "status": {
    "index_type": "full_text",
    "readiness": {
      "state": "pending",
      "queryable": true,
      "complete": true,
      "incarnation": "string",
      "target_revision": 0,
      "published_revision": 0,
      "pending_reasons": [
        "load_failure"
      ],
      "sources": [
        {
          "artifact": "string",
          "state": "pending",
          "complete": true,
          "pending_reasons": [
            "index_failed"
          ]
        }
      ]
    },
    "incarnation": "string",
    "target_revision": 0,
    "published_revision": 0,
    "milestones": {
      "queryable": {
        "reached": true,
        "blockers": [
          "string"
        ]
      },
      "complete": {
        "reached": true,
        "blockers": [
          "string"
        ]
      }
    },
    "error": "string",
    "total_indexed": 0,
    "disk_usage": 0,
    "rebuilding": true,
    "repair": {
      "state": "rebuilding",
      "action_required": true,
      "blocks_queryable": true,
      "blocks_complete": true,
      "reason": "string"
    },
    "backfill_active": true,
    "backfill_progress": 0,
    "backfill_items_processed": 0,
    "backfill_state": "string",
    "doc_count": 0,
    "term_count": 0,
    "replay_applied_sequence": 0,
    "replay_target_sequence": 0,
    "replay_catch_up_required": true,
    "runtime_present": true,
    "runtime_fresh": true,
    "runtime_source": "string",
    "runtime_freshness": "string",
    "catch_up_active": true,
    "catch_up_phase": "string",
    "catch_up_applied_sequence": 0,
    "catch_up_target_sequence": 0,
    "text_merge": {},
    "async_indexing": {},
    "projection_checkpoint_status": "string",
    "projection_checkpoint_applied_sequence": 0,
    "projection_checkpoint_generation": 0,
    "projection_checkpoint_config_fingerprint": "string",
    "checkpoint_replay_tail_sequence_count": 0,
    "repair_scan_issue_count": 0,
    "edge_count": 0,
    "node_count": 0,
    "repair_degraded": true,
    "repair_issue_count": 0,
    "repair_summary_ready": true,
    "repair_issue_count_estimated": true,
    "expected_groups": 0,
    "reported_groups": 0,
    "fresh_groups": 0,
    "stale_groups": 0,
    "missing_groups": 0,
    "unknown_remote_groups": 0,
    "resolution": {},
    "promotion": {}
  }
}

List indexes for an explicit namespace table#

GET/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes

Lists index metadata through an explicit database and namespace route.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

[
  {
    "shard_status": {},
    "config": {
      "name": "string",
      "description": "string",
      "version": 0,
      "enrichments": [
        {
          "name": "string",
          "kind": "chunk",
          "source": {
            "group_by": "string",
            "order_by": "string",
            "segment_by": "string",
            "field": "string",
            "filter": {},
            "max_bytes": 1,
            "max_members": 1,
            "window_ordinals": 1
          },
          "prior_context": {
            "artifact": "string",
            "render": "string",
            "max_items": 1,
            "max_bytes": 1,
            "horizon_segments": 1
          },
          "field": "string",
          "template": "string",
          "source_artifact_name": "string",
          "expected_dims": 0,
          "vector_space": "string",
          "chunk_size": 0,
          "chunk_overlap": 0,
          "chunker": {
            "provider": "antfly",
            "model": "fixed",
            "text": {
              "target_tokens": 500,
              "overlap_tokens": 50
            }
          },
          "chunker_json": "string",
          "full_text_index": true,
          "content_type": "string",
          "neighbor_context": {
            "graph_index": "string",
            "edge_types": [
              "string"
            ],
            "direction": "out",
            "limit": 1
          },
          "execution": {
            "batch_items": 1,
            "batch_bytes": 1,
            "max_document_pages": 1
          }
        }
      ]
    },
    "status": {
      "index_type": "full_text",
      "readiness": {
        "state": "pending",
        "queryable": true,
        "complete": true,
        "incarnation": "string",
        "target_revision": 0,
        "published_revision": 0,
        "pending_reasons": [
          "load_failure"
        ],
        "sources": [
          {
            "artifact": "string",
            "state": "pending",
            "complete": true,
            "pending_reasons": [
              "index_failed"
            ]
          }
        ]
      },
      "incarnation": "string",
      "target_revision": 0,
      "published_revision": 0,
      "milestones": {
        "queryable": {
          "reached": true,
          "blockers": [
            "string"
          ]
        },
        "complete": {
          "reached": true,
          "blockers": [
            "string"
          ]
        }
      },
      "error": "string",
      "total_indexed": 0,
      "disk_usage": 0,
      "rebuilding": true,
      "repair": {
        "state": "rebuilding",
        "action_required": true,
        "blocks_queryable": true,
        "blocks_complete": true,
        "reason": "string"
      },
      "backfill_active": true,
      "backfill_progress": 0,
      "backfill_items_processed": 0,
      "backfill_state": "string",
      "doc_count": 0,
      "term_count": 0,
      "replay_applied_sequence": 0,
      "replay_target_sequence": 0,
      "replay_catch_up_required": true,
      "runtime_present": true,
      "runtime_fresh": true,
      "runtime_source": "string",
      "runtime_freshness": "string",
      "catch_up_active": true,
      "catch_up_phase": "string",
      "catch_up_applied_sequence": 0,
      "catch_up_target_sequence": 0,
      "text_merge": {},
      "async_indexing": {},
      "projection_checkpoint_status": "string",
      "projection_checkpoint_applied_sequence": 0,
      "projection_checkpoint_generation": 0,
      "projection_checkpoint_config_fingerprint": "string",
      "checkpoint_replay_tail_sequence_count": 0,
      "repair_scan_issue_count": 0,
      "edge_count": 0,
      "node_count": 0,
      "repair_degraded": true,
      "repair_issue_count": 0,
      "repair_summary_ready": true,
      "repair_issue_count_estimated": true,
      "expected_groups": 0,
      "reported_groups": 0,
      "fresh_groups": 0,
      "stale_groups": 0,
      "missing_groups": 0,
      "unknown_remote_groups": 0,
      "resolution": {},
      "promotion": {}
    }
  }
]

Get index details for an explicit namespace table#

GET/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "shard_status": {},
  "config": {
    "name": "string",
    "description": "string",
    "version": 0,
    "enrichments": [
      {
        "name": "string",
        "kind": "chunk",
        "source": {
          "group_by": "string",
          "order_by": "string",
          "segment_by": "string",
          "field": "string",
          "filter": {},
          "max_bytes": 1,
          "max_members": 1,
          "window_ordinals": 1
        },
        "prior_context": {
          "artifact": "string",
          "render": "string",
          "max_items": 1,
          "max_bytes": 1,
          "horizon_segments": 1
        },
        "field": "string",
        "template": "string",
        "source_artifact_name": "string",
        "expected_dims": 0,
        "vector_space": "string",
        "chunk_size": 0,
        "chunk_overlap": 0,
        "chunker": {
          "provider": "antfly",
          "model": "fixed",
          "text": {
            "target_tokens": 500,
            "overlap_tokens": 50
          }
        },
        "chunker_json": "string",
        "full_text_index": true,
        "content_type": "string",
        "neighbor_context": {
          "graph_index": "string",
          "edge_types": [
            "string"
          ],
          "direction": "out",
          "limit": 1
        },
        "execution": {
          "batch_items": 1,
          "batch_bytes": 1,
          "max_document_pages": 1
        }
      }
    ]
  },
  "status": {
    "index_type": "full_text",
    "readiness": {
      "state": "pending",
      "queryable": true,
      "complete": true,
      "incarnation": "string",
      "target_revision": 0,
      "published_revision": 0,
      "pending_reasons": [
        "load_failure"
      ],
      "sources": [
        {
          "artifact": "string",
          "state": "pending",
          "complete": true,
          "pending_reasons": [
            "index_failed"
          ]
        }
      ]
    },
    "incarnation": "string",
    "target_revision": 0,
    "published_revision": 0,
    "milestones": {
      "queryable": {
        "reached": true,
        "blockers": [
          "string"
        ]
      },
      "complete": {
        "reached": true,
        "blockers": [
          "string"
        ]
      }
    },
    "error": "string",
    "total_indexed": 0,
    "disk_usage": 0,
    "rebuilding": true,
    "repair": {
      "state": "rebuilding",
      "action_required": true,
      "blocks_queryable": true,
      "blocks_complete": true,
      "reason": "string"
    },
    "backfill_active": true,
    "backfill_progress": 0,
    "backfill_items_processed": 0,
    "backfill_state": "string",
    "doc_count": 0,
    "term_count": 0,
    "replay_applied_sequence": 0,
    "replay_target_sequence": 0,
    "replay_catch_up_required": true,
    "runtime_present": true,
    "runtime_fresh": true,
    "runtime_source": "string",
    "runtime_freshness": "string",
    "catch_up_active": true,
    "catch_up_phase": "string",
    "catch_up_applied_sequence": 0,
    "catch_up_target_sequence": 0,
    "text_merge": {},
    "async_indexing": {},
    "projection_checkpoint_status": "string",
    "projection_checkpoint_applied_sequence": 0,
    "projection_checkpoint_generation": 0,
    "projection_checkpoint_config_fingerprint": "string",
    "checkpoint_replay_tail_sequence_count": 0,
    "repair_scan_issue_count": 0,
    "edge_count": 0,
    "node_count": 0,
    "repair_degraded": true,
    "repair_issue_count": 0,
    "repair_summary_ready": true,
    "repair_issue_count_estimated": true,
    "expected_groups": 0,
    "reported_groups": 0,
    "fresh_groups": 0,
    "stale_groups": 0,
    "missing_groups": 0,
    "unknown_remote_groups": 0,
    "resolution": {},
    "promotion": {}
  }
}

Add an index to an explicit namespace table#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "description": "string",
    "version": 0,
    "enrichments": [
        {
            "name": "string",
            "kind": "chunk",
            "source": {
                "group_by": "string",
                "order_by": "string",
                "segment_by": "string",
                "field": "string",
                "filter": {},
                "max_bytes": 1,
                "max_members": 1,
                "window_ordinals": 1
            },
            "prior_context": {
                "artifact": "string",
                "render": "string",
                "max_items": 1,
                "max_bytes": 1,
                "horizon_segments": 1
            },
            "field": "string",
            "template": "string",
            "source_artifact_name": "string",
            "expected_dims": 0,
            "vector_space": "string",
            "chunk_size": 0,
            "chunk_overlap": 0,
            "chunker": {
                "provider": "antfly",
                "model": "fixed",
                "text": {
                    "target_tokens": 500,
                    "overlap_tokens": 50
                }
            },
            "chunker_json": "string",
            "full_text_index": true,
            "content_type": "string",
            "producer": {
                "type": "copy",
                "config": {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "instructions": "string",
                    "output_schema": {},
                    "output": "auto",
                    "batch": {
                        "max_items_per_call": 1,
                        "max_input_bytes": 1
                    }
                }
            },
            "producer_json": "string",
            "neighbor_context": {
                "graph_index": "string",
                "edge_types": [
                    "string"
                ],
                "direction": "out",
                "limit": 1
            },
            "execution": {
                "batch_items": 1,
                "batch_bytes": 1,
                "max_document_pages": 1
            },
            "transcriber": {
                "provider": "openai",
                "model": "string",
                "api_url": "https://example.com",
                "base_url": "https://example.com",
                "api_key": "string",
                "project_id": "string",
                "location": "string",
                "credentials_path": "string",
                "language_code": "string",
                "timestamps": true,
                "diarization": true,
                "max_download_bytes": 1,
                "download_assets": true
            }
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "description": "string",
    "version": 0,
    "enrichments": [
        {
            "name": "string",
            "kind": "chunk",
            "source": {
                "group_by": "string",
                "order_by": "string",
                "segment_by": "string",
                "field": "string",
                "filter": {},
                "max_bytes": 1,
                "max_members": 1,
                "window_ordinals": 1
            },
            "prior_context": {
                "artifact": "string",
                "render": "string",
                "max_items": 1,
                "max_bytes": 1,
                "horizon_segments": 1
            },
            "field": "string",
            "template": "string",
            "source_artifact_name": "string",
            "expected_dims": 0,
            "vector_space": "string",
            "chunk_size": 0,
            "chunk_overlap": 0,
            "chunker": {
                "provider": "antfly",
                "model": "fixed",
                "text": {
                    "target_tokens": 500,
                    "overlap_tokens": 50
                }
            },
            "chunker_json": "string",
            "full_text_index": true,
            "content_type": "string",
            "producer": {
                "type": "copy",
                "config": {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "instructions": "string",
                    "output_schema": {},
                    "output": "auto",
                    "batch": {
                        "max_items_per_call": 1,
                        "max_input_bytes": 1
                    }
                }
            },
            "producer_json": "string",
            "neighbor_context": {
                "graph_index": "string",
                "edge_types": [
                    "string"
                ],
                "direction": "out",
                "limit": 1
            },
            "execution": {
                "batch_items": 1,
                "batch_bytes": 1,
                "max_document_pages": 1
            },
            "transcriber": {
                "provider": "openai",
                "model": "string",
                "api_url": "https://example.com",
                "base_url": "https://example.com",
                "api_key": "string",
                "project_id": "string",
                "location": "string",
                "credentials_path": "string",
                "language_code": "string",
                "timestamps": true,
                "diarization": true,
                "max_download_bytes": 1,
                "download_assets": true
            }
        }
    ]
}'

Responses#

{
  "name": "string",
  "description": "string",
  "version": 0,
  "enrichments": [
    {
      "name": "string",
      "kind": "chunk",
      "source": {
        "group_by": "string",
        "order_by": "string",
        "segment_by": "string",
        "field": "string",
        "filter": {},
        "max_bytes": 1,
        "max_members": 1,
        "window_ordinals": 1
      },
      "prior_context": {
        "artifact": "string",
        "render": "string",
        "max_items": 1,
        "max_bytes": 1,
        "horizon_segments": 1
      },
      "field": "string",
      "template": "string",
      "source_artifact_name": "string",
      "expected_dims": 0,
      "vector_space": "string",
      "chunk_size": 0,
      "chunk_overlap": 0,
      "chunker": {
        "provider": "antfly",
        "model": "fixed",
        "text": {
          "target_tokens": 500,
          "overlap_tokens": 50
        }
      },
      "chunker_json": "string",
      "full_text_index": true,
      "content_type": "string",
      "neighbor_context": {
        "graph_index": "string",
        "edge_types": [
          "string"
        ],
        "direction": "out",
        "limit": 1
      },
      "execution": {
        "batch_items": 1,
        "batch_bytes": 1,
        "max_document_pages": 1
      }
    }
  ]
}

Drop an index from an explicit namespace table#

DELETE/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X DELETE "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}" \
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

No response body

Retry a failed index build#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/retry

Generation-fenced relational index maintenance. Requires table ADMIN permission. Retry accepts failed generations. Owners are admitted independently and durably; exact request replay resumes after partial acknowledgements. Unsupported index types return 405.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/retry" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}'

Responses#

{
  "acknowledged_groups": [
    "string"
  ]
}

Repair an index generation#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/repair

Generation-fenced relational index maintenance. Requires table ADMIN permission. Repair accepts ready or failed generations and rebuilds their derived records. Owners are admitted independently and durably; exact request replay resumes after partial acknowledgements. Unsupported index types return 405.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/indexes/{indexName}/repair" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table_id": "string",
    "schema_version": 0,
    "owners": [
        {
            "group_id": "string",
            "generation": "string",
            "slot": 0,
            "owner": "string",
            "comparison": "string",
            "progress_digest": "string",
            "maintenance_epoch": "string"
        }
    ]
}'

Responses#

{
  "acknowledged_groups": [
    "string"
  ]
}