# Antfly Table Management API

**Canonical:** https://apis.io/apis/antfly/antfly-table-management-api/  
**Provider:** Antfly — https://apis.io/providers/antfly/  
**Base URL:** https://api.antfly.io  
**Documentation:** https://antfly.io/docs/api

Antfly Table Management API is one of 20 APIs that [Antfly](https://apis.io/providers/antfly/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include table_management. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

Manage tables in your Antfly cluster. Tables store your documents and support multiple indexes. ## Schema Schemas define the structure and types of data in your tables using **JSON Schema** with custom Antfly extensions. While optional, defining a schema provides several benefits: - **Type Safety**: Ensures data consistency across documents - **Optimized Indexing**: Full Text Index uses type information for appropriate field mappings in Antfly's native full-text index - **Better Search**: Type-aware indexing improves search relevance and performance - **Query Optimization**: Enables type-specific query operations ## JSON Schema Structure Antfly uses standard JSON Schema with custom extensions: ```json { "document_schemas": { "article": { "schema": { "type": "object", "properties": { "title": { "type": "string", "x-antfly-types": ["text", "keyword"] }, "body": { "type": "string", "x-antfly-types": ["html"] }, "tags": { "type": "array", "items": {"type": "string"}, "x-antfly-types": ["keyword"] }, "metadata": { "type": "object", "properties": { "author": {"type": "string"} } } }, "additionalProperties": false, "x-antfly-include-in-all": ["title", "body"] } } } } ``` **Dynamic Indexing** (`additionalProperties`): - `"additionalProperties": false` - Reject documents that carry fields not defined in `properties` (standard JSON Schema validation); only declared fields exist, so only declared fields are indexed - `"additionalProperties": true` - Store undeclared fields and index them dynamically (flexible but slower) - If not specified, undeclared fields are stored but not indexed Dynamic indexing only ever applies to undeclared fields. A property listed in `properties` is indexed exactly as its declaration says: one declared with `x-antfly-index: false`, or with a non-text type such as `blob` or `embedding`, stays out of the text index even when the enclosing object sets `"additionalProperties": true`. **Nested Objects**: - Use `"type": "object"` with nested `properties` for structured data - Nested objects don't inherit `x-antfly-include-in-all` from parent - Arrays of objects: Use `"type": "array"` with `"items": {"type": "object", ...}` ## Antfly Extensions ### `x-antfly-types` Array of Antfly type strings specifying how to index a field. Multiple types create multiple field mappings: - **Single type**: `"x-antfly-types": ["text"]` - Creates standard text field - **Multiple types**: `"x-antfly-types": ["text", "keyword"]` - Creates `fieldName` (text) and `fieldName.keyword` - **With search-as-you-type**: `"x-antfly-types": ["text", "search_as_you_type"]` - Creates `fieldName` (text), `fieldName._2gram`, `fieldName._3gram`, and `fieldName._index_prefix` - **With substring**: `"x-antfly-types": ["text", "substring"]` - Creates `fieldName` (text) and `fieldName._substring`, a suffix-indexed companion that answers "contains" queries without scanning the term dictionary **Type Combination Rules**: - `text` and `html` are mutually exclusive (choose one as primary type) - Primary types (`text`, `html`) can be combined with variants (`keyword`, `search_as_you_type`, `substring`) - `search_as_you_type` or `substring` + `keyword` allowed without primary type (auto-adds `text`) `x-antfly-types` remains supported as the compact multi-mapping/search shorthand. Exact scalar names in that array describe how a field is searched, but do not opt the field into the typed doc-value storage required by production `order_by`. ### `x-antfly-field` Use an explicit field mapping for fields that participate in exact sort. Set `sortable: true` on a keyword, numeric/number/integer, boolean/bool, datetime/date/timestamp, or link mapping. Antfly derives the internal typed doc values; `doc_values` is intentionally not a public setting. The mapping type must accept the property's JSON Schema value type. Explicit property mappings take precedence over dynamic templates. When multiple document types declare the same dotted field path, their normalized physical mappings must be identical. ```json { "created_at": { "type": "string", "format": "date-time", "x-antfly-field": {"type": "date", "sortable": true} }, "title": { "type": "string", "x-antfly-field": { "type": "text", "fields": { "keyword": {"type": "keyword", "sortable": true} } } } } ``` Sort the examples above with `created_at` and `title.keyword`, respectively. An analyzed `text` field is never directly sortable. Adding `sortable: true` to an existing table is a physical mapping change. Once the write or rebuild visibility barrier completes, clients may issue `order_by` directly. Antfly validates cold physical coverage on first use and fails closed when it is incomplete; status reads do not warm columns, so `sort_lifecycle_state` may remain `declared` until that validation succeeds. ### `x-antfly-index` Boolean to disable indexing for a field: ```json {"type": "string", "x-antfly-index": false} ``` The value is still stored and returned with the document, but nothing at or below that path is indexed: no text postings, no typed doc values, and no dynamic indexing even when the enclosing object sets `"additionalProperties": true`. On an object or an array's `items` it applies to the whole subtree. This is the way to keep a large field that exists only as the source of an embeddings index out of the text index. Adding `x-antfly-index: false` to an existing table is a schema migration, not an in-place edit: the current full-text index keeps serving the field's existing postings until the replacement index has been rebuilt under the new schema, and only then are they gone. The table does not shrink on the schema update itself. ### `x-antfly-include-in-all` Schema-level array of field names to include in the special `_all` field for cross-field search: ```json { "x-antfly-include-in-all": ["title", "body", "description"] } ``` Only text-based types (`text`, `html`, `keyword`, `search_as_you_type`, `substring`, `link`) are included, and only the primary field (not `.keyword`, `._2gram`, `._3gram`, `._index_prefix`, or `._substring` variants). ## Antfly Types ### Text Types - `text` - Full-text searchable with tokenization and analysis. Use for articles, descriptions, searchable content. - `html` - Full-text searchable with HTML tag stripping. Use for HTML content. - `keyword` - Exact-match strings (not analyzed). Use for IDs, tags, categories, filters. - `search_as_you_type` - Search-as-you-type mappings for autocomplete. Creates `fieldName._2gram`, `fieldName._3gram`, and `fieldName._index_prefix` mappings. - `substring` - Infix ("contains") matching for identifiers, SKUs, paths, and code. Creates `fieldName._substring`, which indexes every suffix (2 to 32 bytes) of each lowercased token and of each adjacent token pair joined without a separator, so `rag3-weaver`, `rag3_weaver`, and `rag3weaver` all match a `match` or `prefix` query for `g3we` on `fieldName._substring`. Queries are lowercased, adjacent query tokens are joined the same way, and a query of three or more tokens requires every adjacent pair. Single-character queries never match. Expect the companion to cost several times the size of the text it indexes; opt in per field. - `link` - URL/link field (keyword analyzer). ### Numeric and Boolean Types - `numeric` - Numbers (integers and floats). Use for counts, prices, scores. - `boolean` - True/false values. ### Date/Time Types - `datetime` - Timestamp fields. Use for created/updated dates, events. ### Geospatial Types - `geopoint` - Latitude/longitude point. Use for locations, coordinates. - `geoshape` - Complex geographic shape. Use for boundaries, regions. ### Special Types - `embedding` - Vector embeddings (not indexed in the full-text index). Use for similarity search. - `blob` - Binary data (not indexed). Use for images, files, binary content. ## Type Inference If `x-antfly-types` is not specified, types are inferred from JSON Schema `type`: - `"type": "string"` → `["text"]` - `"type": "number"` or `"integer"` → `["numeric"]` - `"type": "boolean"` → `["boolean"]` ## Automatic Fields Antfly automatically adds these fields to all document schemas: - **`_timestamp`**: Datetime field for document timestamps - **`_summaries`**: Object field (map of index names to summary text) for AI-generated summaries ## Field Naming Conventions When multiple types are specified, Antfly creates additional field mappings with suffixes: - **Primary field** (`text` or `html`): Uses original field name - **Keyword variant**: `fieldName.keyword` - **Search-as-you-type**: `fieldName._2gram`, `fieldName._3gram`, and `fieldName._index_prefix` - **Substring**: `fieldName._substring` Example: `"x-antfly-types": ["text", "keyword", "search_as_you_type"]` creates: - `title` (text analyzer) - `title.keyword` (keyword analyzer) - `title._2gram` (2-token shingle analyzer) - `title._3gram` (3-token shingle analyzer) - `title._index_prefix` (edge n-gram prefix analyzer) ## Best Practices - Use `text` for searchable content, `keyword` for exact matching - Combine types for flexible querying: `["text", "keyword"]` enables both full-text and exact search - Add `search_as_you_type` for autocomplete functionality - Use `html` type for HTML content to strip tags during indexing - Specify `x-antfly-include-in-all` for important searchable fields ## Performance Considerations - `text` and `html` fields have higher indexing cost due to text analysis - `keyword` fields are faster to index but don't support partial matches - `search_as_you_type` adds edge n-gram indexing overhead - `embedding` and `blob` fields are automatically excluded from text indexing - Multiple types per field increase index size and indexing time ## Document TTL (Time-To-Live) Antfly supports automatic expiration and deletion of documents after a specified duration. Documents are automatically removed by a background cleanup job running on the Raft leader. ### Basic Configuration Configure TTL when creating a table (`POST /db/v1/tables/{tableName}`) with a `ttl` policy under `schema`. The table name is part of the URL: ```json { "schema": { "ttl": {"duration": "24h"}, "document_schemas": { "session": { "schema": { "type": "object", "properties": { "user_id": {"type": "string"}, "data": {"type": "object"} } } } } } } ``` **How it works:** - Documents expire after the specified duration from their timestamp - Uses `_timestamp` field by default (automatically added at insertion) - Background cleanup runs every 30 seconds on the Raft leader - Expired documents are filtered from queries immediately (before cleanup) - Deletions are batched (1000 documents at a time) and go through Raft consensus ### Custom TTL Reference Field Use a custom timestamp field instead of `_timestamp`: ```json { "schema": { "ttl": { "duration": "7d", "field": "created_at" }, "document_schemas": { "event": { "schema": { "type": "object", "properties": { "created_at": {"type": "string", "format": "date-time"}, "event_type": {"type": "string"} }, "required": ["created_at"] } } } } } ``` **Requirements:** - Custom TTL field must be present in all documents - Must be in RFC3339 format (e.g., `2025-01-01T12:00:00Z`) - Documents without the field will fail validation ### Duration Format TTL durations use Antfly's integer-component duration format. Supported units are `ns`, `us`, `ms`, `s`, `m`, `h`, and `d`: - `30s` - 30 seconds - `5m` - 5 minutes - `24h` - 24 hours - `7d` - 7 days (treated as 168h) - `168h` - 1 week ### Use Cases **Session Management:** ```json { "schema": {"ttl": {"duration": "1h", "field": "last_accessed"}} } ``` Sessions expire 1 hour after `last_accessed`. Update the timestamp on each access to extend the session. **Temporary Caching:** ```json { "schema": {"ttl": {"duration": "24h"}} } ``` Cache entries expire 24 hours after insertion. **Log Rotation:** ```json { "schema": {"ttl": {"duration": "30d"}} } ``` Logs are automatically deleted after 30 days. ### Performance Characteristics **Optimized Storage:** - TTL timestamps stored separately (`:t` suffix keys) for O(1) lookups - No JSON deserialization needed during cleanup scans - ~100-1000x faster than scanning full document bodies - Minimal storage overhead (~30 bytes per document) **Query Filtering:** - Single key lookup to check expiration (~microseconds) - No impact on query latency - Scales to millions of documents **Cleanup Behavior:** - Runs every 30 seconds (configurable) - Leader-only operation (prevents duplicate work) - 5-second grace period ensures writes are fully replicated - Batched deletions (1000 docs) prevent overwhelming the system ### Monitoring TTL operations are logged with cleanup metrics: ``` INFO Starting TTL cleanup job ttl_duration=24h cleanup_interval=30s INFO Cleaned up expired documents count=42 duration=245ms total_expired=1337 ``` ### Modifying TTL Configuration **Adding TTL to existing table:** - Update the schema with a `ttl` policy - Applies retroactively to all documents - Documents already expired are marked for immediate deletion **Removing TTL:** - Set `ttl` to `null` - All expiration processing stops - Previously expired documents remain **Changing duration:** - Update `ttl.duration` - New duration applies immediately to all documents - Expiration recalculated using existing timestamps ### Limitations - **Clock synchronization required**: Use NTP to sync clocks across cluster nodes - **Cleanup latency**: Expired documents deleted within ~30 seconds (cleanup interval) - **Table-level configuration**: TTL applies to all documents in the table - **Timestamp format**: Must be RFC3339 or RFC3339Nano

## Operations (44)

| Method | Path | Summary |
|---|---|---|
| GET | `/db/v1/tables/{tableName}/lake/catalog` | getLakeCatalog |
| POST | `/db/v1/tables/{tableName}/lake/catalog` | initializeLakeCatalog |
| POST | `/db/v1/tables/{tableName}/lake/changes` | ingestLakeChanges |
| POST | `/db/v1/tables/{tableName}/lake/maintenance` | Maintain a writable Iceberg table |
| POST | `/db/v1/tables/{tableName}/lake/commits` | commitLakeCatalog |
| GET | `/db/v1/tables/{tableName}/lake/commits/{commitId}` | getLakeCommitOutcome |
| GET | `/db/v1/tables` | List all tables |
| POST | `/db/v1/tables/{tableName}` | Create a new table |
| DELETE | `/db/v1/tables/{tableName}` | Drop a table |
| GET | `/db/v1/tables/{tableName}` | Get table details |
| POST | `/db/v1/tables/{tableName}/destination-authorization` | Adopt stored write destinations with the current credential |
| PUT | `/db/v1/tables/{tableName}/schema` | Replace a table's schema |
| PATCH | `/db/v1/tables/{tableName}/schema` | Patch a table's schema |
| GET | `/db/v1/sources` | List saved query sources |
| GET | `/db/v1/sources/{sourceName}` | Get saved query source |
| POST | `/db/v1/sources/{sourceName}` | Create saved query source |
| DELETE | `/db/v1/sources/{sourceName}` | Drop saved query source |
| GET | `/db/v1/tablespaces` | List tablespaces |
| GET | `/db/v1/tablespaces/{tablespaceName}` | Get tablespace |
| POST | `/db/v1/tablespaces/{tablespaceName}` | Create tablespace |
| DELETE | `/db/v1/tablespaces/{tablespaceName}` | Drop tablespace |
| GET | `/db/v1/databases` | List databases |
| GET | `/db/v1/databases/{databaseName}` | Get database |
| POST | `/db/v1/databases/{databaseName}` | Create database |
| DELETE | `/db/v1/databases/{databaseName}` | Drop database |
| PUT | `/db/v1/databases/{databaseName}/tablespace` | Set database tablespace |
| DELETE | `/db/v1/databases/{databaseName}/tablespace` | Clear database tablespace |
| GET | `/db/v1/databases/{databaseName}/namespaces` | List namespaces |
| POST | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}` | Create namespace |
| DELETE | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}` | Drop namespace |
| PUT | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tablespace` | Set namespace tablespace |
| DELETE | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tablespace` | Clear namespace tablespace |
| GET | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables` | List tables in namespace |
| GET | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}` | Get namespace table details |
| POST | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}` | Create namespace table |
| DELETE | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}` | Drop namespace table |
| PUT | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/schema` | Replace a table's schema |
| PATCH | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/schema` | Patch a table's schema |
| POST | `/db/v1/databases/{databaseName}/rename` | Rename catalog resource |
| POST | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/rename` | Rename catalog resource |
| POST | `/db/v1/tablespaces/{tablespaceName}/rename` | Rename catalog resource |
| POST | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rename` | Rename catalog resource |
| PUT | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/tablespace` | Set namespace tablespace |
| DELETE | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/tablespace` | Clear namespace tablespace |

## Machine-readable artifacts (7)

- **OpenAPI** — https://artifacts.apis.io/antfly/openapi/antfly-table-management-api-openapi.yml
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-recall-result-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-inspection-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-record-page-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-record-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-relationship-proposal-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-inference-generate-request-schema.json

## Other Antfly APIs (12)

- [Antfly AI API](https://apis.io/apis/antfly/antfly-ai-api/)
- [Antfly Cluster Management API](https://apis.io/apis/antfly/antfly-cluster-management-api/)
- [Antfly Data Operations API](https://apis.io/apis/antfly/antfly-data-operations-api/)
- [Antfly Documents API](https://apis.io/apis/antfly/antfly-documents-api/)
- [Antfly Index Management API](https://apis.io/apis/antfly/antfly-index-management-api/)
- [Antfly Inference API](https://apis.io/apis/antfly/antfly-inference-api/)
- [Antfly Installed API](https://apis.io/apis/antfly/antfly-installed-api/)
- [Antfly Memory API](https://apis.io/apis/antfly/antfly-memory-api/)
- [Antfly Ml API](https://apis.io/apis/antfly/antfly-ml-api/)
- [Antfly Models API](https://apis.io/apis/antfly/antfly-models-api/)
- [Antfly Packages API](https://apis.io/apis/antfly/antfly-packages-api/)
- [Antfly Permission API](https://apis.io/apis/antfly/antfly-permission-api/)

## Tags

table_management

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/antfly/antfly-table-management-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/antfly/.