Data Operations#

Perform data operations including batch inserts/deletes, linear merge sync, backup/restore, and individual key lookups.

Batch Operations#

Efficiently insert or delete multiple documents in a single request. The batch endpoint accepts both inserts (map of key-value pairs) and deletes (array of keys).

Distributed Transactions#

Antfly provides atomic cross-shard write transactions using a coordinator-based 2-phase commit (2PC) protocol. When a batch operation spans multiple shards, Antfly automatically executes it as a distributed transaction.

How it works:

Metadata server allocates HLC timestamp and selects coordinator shard
Coordinator writes transaction record, participants write intents
After all intents succeed, coordinator commits transaction
Participants are notified asynchronously to resolve intents
Recovery loop ensures notifications complete even after coordinator failure

Features:

Automatic: No special API required - just use the batch endpoint
Atomic: All writes across all shards commit or abort together
Recoverable: Coordinator failures are handled via recovery loops
Efficient: ~20ms latency for cross-shard transactions

Performance:

Single-shard batches: < 5ms latency
Cross-shard transactions: ~20ms latency
Intent resolution: < 30 seconds worst-case (via recovery loop)

Guarantees:

All writes succeed or all fail (atomicity)
Coordinator failure is recoverable (new leader resumes notifications)
Idempotent resolution (duplicate notifications are safe)

Use Cases:

Updating related records across shards (e.g., user profile + preferences)
Multi-table inserts that must succeed together
Bulk imports requiring all-or-nothing semantics

Linear Merge (Data Sync)#

Synchronize and keep Antfly in sync with external data sources like Shopify, Postgres, S3, or any sorted record source. Also known as: data synchronization, database sync, incremental sync, e-commerce sync.

Both source and Antfly must be sorted by the same key. Performs three-way merge: inserts new records, updates changed records, deletes records absent from source.

How it works:

Query external source with pagination (sorted by key)
Send sorted page to linear merge endpoint
Antfly merges: upserts present records, deletes Antfly records absent from page
Repeat for next page - no sync state required between pages

Use Cases:

Postgres/MySQL: SELECT * FROM products ORDER BY id LIMIT 1000 OFFSET 0
- Sync production DB to Antfly for hybrid search
- Run periodically (hourly/daily) to stay in sync
Shopify API: GET /admin/api/2024-01/products.json?order=id&limit=250
- Sync e-commerce catalog with cursor pagination
- Antfly becomes searchable product index
S3 Data Lake: Sorted JSON files (data/0001.json, data/0002.json, ...)
- Batch import from data warehouse exports
- Process files in order, send contents page by page
Databricks: SELECT * FROM delta_table ORDER BY key LIMIT 10000
- Sync data warehouse tables to Antfly
- Enable low-latency search over warehouse data

Benefits:

Stateless: No cursors or checkpoints - restart from any page
Idempotent: Safe to re-run if interrupted
Efficient: Stream comparison, no random access needed

WARNING: Not safe for concurrent merges with overlapping ranges. Single-client sync API only.

Backup and Restore#

Create backups to various storage backends:

file:///path/to/backup - Local filesystem
s3://bucket/path - Amazon S3

Restore operations rebuild tables from backup snapshots.

Key Lookups#

Direct key-value lookups for retrieving individual documents by their unique key.

Cross-table batch operations#

POST/batch

Perform batch inserts, deletes, and transforms across multiple tables in a single atomic transaction.

All operations across all tables are committed atomically using distributed 2-phase commit (2PC). Either all operations succeed, or none do.

Use cases:

Transfer records between tables (insert in one, delete from another)
Maintain referential integrity across tables
Atomic multi-table updates

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/batch',
    headers=headers,
    json={
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/batch", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "tables": {}
}

{
  "status": "committed",
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Commit an OCC transaction#

POST/transactions/commit

Commit a stateless OCC (Optimistic Concurrency Control) transaction.

Workflow:

Read documents using regular lookup endpoints, capturing the X-Antfly-Version response header for each read
Compute writes locally based on the read values
Submit this commit request with the read set (keys + versions) and the write set (batch operations per table)

The server validates that all read versions still match current state. If any version has changed, the transaction is aborted with a 409 Conflict response containing details about which key conflicted.

If all versions match, writes are executed atomically via 2PC.

Stateless clients manage their own read set. For server-managed read-modify-write workflows, use the transaction session endpoints.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/commit" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/commit',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/commit", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

List transaction sessions#

GET/transactions

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/transactions" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/transactions', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/transactions", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "session_count": 0,
  "lease_held_count": 0,
  "lease_expired_count": 0,
  "sessions": [
    {
      "transaction_id": "string",
      "owner_node_id": 0,
      "begin_timestamp": 0,
      "last_touched_timestamp": 0,
      "lease_expires_at": 0,
      "lease_state": "string",
      "sync_level": "string",
      "disposition": "active",
      "staged_table_count": 0,
      "staged_read_count": 0,
      "staged_write_count": 0,
      "staged_delete_count": 0,
      "read_snapshot_count": 0,
      "savepoint_count": 0,
      "savepoint_limit": 0,
      "remaining_savepoints": 0,
      "durable": true
    }
  ]
}

Clean up expired transaction sessions#

POST/transactions/cleanup

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`cutoff_ns`	string	query	No

Code Examples#

curl -X POST "/db/v1/transactions/cleanup?cutoff_ns=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/cleanup?cutoff_ns=value', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/cleanup?cutoff_ns=value', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/cleanup?cutoff_ns=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/cleanup?cutoff_ns=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "removed": 0,
  "cutoff_ns": 0
}

Begin a transaction session#

POST/transactions/begin

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/begin" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/begin', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/begin', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/begin',
    headers=headers,
    json={
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/begin", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "transaction_id": "string",
  "begin_timestamp": 0,
  "sync_level": "string"
}

Get transaction session details#

GET/transactions/{transaction_id}

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X GET "/db/v1/transactions/{transaction_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/transactions/{transaction_id}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/transactions/{transaction_id}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "transaction_id": "string",
  "owner_node_id": 0,
  "begin_timestamp": 0,
  "last_touched_timestamp": 0,
  "lease_expires_at": 0,
  "lease_state": "string",
  "sync_level": "string",
  "disposition": "active",
  "staged_table_count": 0,
  "staged_read_count": 0,
  "staged_write_count": 0,
  "staged_delete_count": 0,
  "read_snapshot_count": 0,
  "savepoint_count": 0,
  "savepoint_limit": 0,
  "remaining_savepoints": 0,
  "durable": true
}

Stage a transaction commit request#

POST/transactions/{transaction_id}/stage

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/stage" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/stage', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/stage', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/stage',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/stage", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Stage a transaction read version#

POST/transactions/{transaction_id}/read

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string",
    "version": "string"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/read" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string",
    "version": "string"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/read', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "version": "string"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/read', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "version": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/read',
    headers=headers,
    json={
        "table": "string",
        "key": "string",
        "version": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string",
    "version": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/read", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "snapshot": {
    "table": "string",
    "key": "string",
    "version": "string",
    "document": null
  }
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Stage a transaction write#

POST/transactions/{transaction_id}/write

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string",
    "document": {}
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/write" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string",
    "document": {}
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/write', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "document": {}
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/write', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "document": {}
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/write',
    headers=headers,
    json={
        "table": "string",
        "key": "string",
        "document": {}
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string",
    "document": {}
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/write", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Stage a transaction delete#

POST/transactions/{transaction_id}/delete

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/delete" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/delete', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/delete', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/delete',
    headers=headers,
    json={
        "table": "string",
        "key": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/delete", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Create a transaction savepoint#

POST/transactions/{transaction_id}/savepoints

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/savepoints" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/savepoints', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/savepoints', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/savepoints', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/savepoints", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "savepoint_id": 0
}

Roll back a transaction session to a savepoint#

POST/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes
`savepoint_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "savepoint_id": 0
}

Commit a transaction session#

POST/transactions/{transaction_id}/commit

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/commit" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/commit',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/commit", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "reason": "unique_constraint_violation",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Abort a transaction session#

POST/transactions/{transaction_id}/abort

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/abort" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/abort', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/abort', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/abort', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/abort", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Open a durable idle HTTP SQL connection#

POST/sql/connections

Creates a principal- and API-node-owned connection with a one-hour idle-use deadline. Active or uncertain transactions retain their exact connection binding until completion or reconciliation; expiry is not an abort decision. Send connection_id with later SQL and prepared requests. This ID is not a transaction session_id. DISCARD ALL resets only this connection's setting overlay and prepared resources, and refuses active or uncertain transactions. Do not automatically replay ambiguous create responses.

Security#

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "database": "string",
    "namespace": "string"
}

Code Examples#

curl -X POST "/db/v1/sql/connections" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "database": "string",
    "namespace": "string"
}'

const response = await fetch('/db/v1/sql/connections', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "database": "string",
        "namespace": "string"
    })
});

const data = await response.json();

fetch('/db/v1/sql/connections', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "database": "string",
        "namespace": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/sql/connections',
    headers=headers,
    json={
        "database": "string",
        "namespace": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "database": "string",
    "namespace": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/sql/connections", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "connection_id": "string",
  "owner_node_id": "string",
  "expires_at_ms": 0,
  "database": "string",
  "namespace": "string"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Close an idle SQL connection and its prepared resources#

DELETE/sql/connections/{connection_id}

Refuses an active, beginning or uncertain transaction; route to owner_node_id.

Security#

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/sql/connections/{connection_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/sql/connections/{connection_id}', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/sql/connections/{connection_id}', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.delete('/db/v1/sql/connections/{connection_id}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "/db/v1/sql/connections/{connection_id}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Create a durable prepared SQL resource#

POST/sql/prepared

Binds SELECT, INSERT, UPDATE or DELETE without executing it. The immutable resource belongs to the authenticated principal and API node, expires after one hour, and survives transaction COMMIT and owner restart with the same durable store and node identity. A session-bound resource is executable only while its attached session remains active. Owner failover is not automatic; execute and close must reach owner_node_id. Each durable store admits at most 128 resources and 4 MiB of serialized prepared state. Expired resources are reclaimed atomically during subsequent creation or close. Execution authenticates and authorizes again and rejects changed catalog identities or schemas. When session_id is supplied, preparation uses the attached session's authenticated database, namespace and setting overlay under its execution lease. The resource is bound to that session; execution re-reads current values but rejects a changed setting catalog. A native durable session store is required.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "statement": "string",
    "database": "string",
    "namespace": "string",
    "session_id": "string",
    "connection_id": "string"
}

Code Examples#

curl -X POST "/db/v1/sql/prepared" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "statement": "string",
    "database": "string",
    "namespace": "string",
    "session_id": "string",
    "connection_id": "string"
}'

const response = await fetch('/db/v1/sql/prepared', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "statement": "string",
        "database": "string",
        "namespace": "string",
        "session_id": "string",
        "connection_id": "string"
    })
});

const data = await response.json();

fetch('/db/v1/sql/prepared', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "statement": "string",
        "database": "string",
        "namespace": "string",
        "session_id": "string",
        "connection_id": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/sql/prepared',
    headers=headers,
    json={
        "statement": "string",
        "database": "string",
        "namespace": "string",
        "session_id": "string",
        "connection_id": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "statement": "string",
    "database": "string",
    "namespace": "string",
    "session_id": "string",
    "connection_id": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/sql/prepared", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "prepared_id": "string",
  "expires_at_ms": 0,
  "owner_node_id": "string",
  "parameter_types": [
    "string"
  ],
  "parameter_descriptors": [
    {
      "type": "string",
      "element_type": "text",
      "nullable": true
    }
  ],
  "columns": [
    {
      "name": "string",
      "type": "string",
      "element_type": "text",
      "numeric_modifier": {
        "precision": 1,
        "scale": -1000
      }
    }
  ]
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Execute a durable prepared SQL resource#

POST/sql/prepared/{prepared_id}/execute

Uses the stored statement, namespace and immutable binding identities. Resource admission linearizes when its durable record is loaded; a later close or expiry does not cancel that already admitted execution. Mutation outcomes must be reconciled rather than replayed after ambiguous errors.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "parameters": [
        null
    ],
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}

Code Examples#

curl -X POST "/db/v1/sql/prepared/{prepared_id}/execute" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "parameters": [
        null
    ],
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}'

const response = await fetch('/db/v1/sql/prepared/{prepared_id}/execute', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "parameters": [
            null
        ],
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    })
});

const data = await response.json();

fetch('/db/v1/sql/prepared/{prepared_id}/execute', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "parameters": [
            null
        ],
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/sql/prepared/{prepared_id}/execute',
    headers=headers,
    json={
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "parameters": [
            null
        ],
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "parameters": [
        null
    ],
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/sql/prepared/{prepared_id}/execute", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "columns": [
    {
      "name": "string",
      "type": "string",
      "element_type": "text",
      "numeric_modifier": {
        "precision": 1,
        "scale": -1000
      }
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "rows_affected": 0,
  "sql_nulls": [
    [
      true
    ]
  ],
  "command_tag": "string",
  "mutation_outcome": "committed",
  "ddl_receipt": {
    "database": "string",
    "namespace": "string",
    "table": "string",
    "table_id": "string",
    "schema_version": 0,
    "state": "ready",
    "diagnostic": "string",
    "restore_job_id": "string",
    "idempotency_key": "string"
  },
  "transaction_id": "string",
  "session_id": "string",
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Release a durable prepared SQL resource#

DELETE/sql/prepared/{prepared_id}

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`X-Antfly-SQL-Connection-Id`	string	header	No	Required to close a connection-bound prepared resource.

Code Examples#

curl -X DELETE "/db/v1/sql/prepared/{prepared_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/sql/prepared/{prepared_id}', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/sql/prepared/{prepared_id}', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.delete('/db/v1/sql/prepared/{prepared_id}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "/db/v1/sql/prepared/{prepared_id}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Execute a SQL statement#

POST/sql

Executes the bounded relational SELECT, INSERT, UPDATE, and DELETE subset through the current catalog and native row execution contracts. Parameters are bound separately from statement text. Document, graph, and lake SQL sources, DDL, and SQL sessions are not yet supported. Reads inherit native owner-local consistency, not a global SQL transaction snapshot. Statements requiring a retained multi-page statement snapshot fail when that capability is unavailable. Unsupported statement shapes fail explicitly; the server never silently substitutes a different query or truncates the result.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "statement": "string",
    "parameters": [
        null
    ],
    "database": "string",
    "namespace": "string",
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}

Code Examples#

curl -X POST "/db/v1/sql" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "statement": "string",
    "parameters": [
        null
    ],
    "database": "string",
    "namespace": "string",
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}'

const response = await fetch('/db/v1/sql', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "statement": "string",
        "parameters": [
            null
        ],
        "database": "string",
        "namespace": "string",
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    })
});

const data = await response.json();

fetch('/db/v1/sql', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "statement": "string",
        "parameters": [
            null
        ],
        "database": "string",
        "namespace": "string",
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/sql',
    headers=headers,
    json={
        "read_requirements": {
            "visibility": "accepted",
            "after_write": {
                "table_id": 0,
                "object_generation": 0,
                "wal_lsn": 0
            },
            "wait_ms": 0
        },
        "statement": "string",
        "parameters": [
            null
        ],
        "database": "string",
        "namespace": "string",
        "limit": 1,
        "session_id": "string",
        "connection_id": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_requirements": {
        "visibility": "accepted",
        "after_write": {
            "table_id": 0,
            "object_generation": 0,
            "wal_lsn": 0
        },
        "wait_ms": 0
    },
    "statement": "string",
    "parameters": [
        null
    ],
    "database": "string",
    "namespace": "string",
    "limit": 1,
    "session_id": "string",
    "connection_id": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/sql", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "columns": [
    {
      "name": "string",
      "type": "string",
      "element_type": "text",
      "numeric_modifier": {
        "precision": 1,
        "scale": -1000
      }
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "rows_affected": 0,
  "sql_nulls": [
    [
      true
    ]
  ],
  "command_tag": "string",
  "mutation_outcome": "committed",
  "ddl_receipt": {
    "database": "string",
    "namespace": "string",
    "table": "string",
    "table_id": "string",
    "schema_version": 0,
    "state": "ready",
    "diagnostic": "string",
    "restore_job_id": "string",
    "idempotency_key": "string"
  },
  "transaction_id": "string",
  "session_id": "string",
  "transaction_status": "idle"
}

{
  "columns": [
    {
      "name": "string",
      "type": "string",
      "element_type": "text",
      "numeric_modifier": {
        "precision": 1,
        "scale": -1000
      }
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "rows_affected": 0,
  "sql_nulls": [
    [
      true
    ]
  ],
  "command_tag": "string",
  "mutation_outcome": "committed",
  "ddl_receipt": {
    "database": "string",
    "namespace": "string",
    "table": "string",
    "table_id": "string",
    "schema_version": 0,
    "state": "ready",
    "diagnostic": "string",
    "restore_job_id": "string",
    "idempotency_key": "string"
  },
  "transaction_id": "string",
  "session_id": "string",
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

{
  "code": "string",
  "message": "string",
  "column_name": "string",
  "position": 1,
  "transaction_id": "string",
  "retryable": true,
  "transaction_status": "idle"
}

Read distributed UNIQUE, foreign-key, and CHECK validation coverage#

GET/tables/{tableName}/constraints/status

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}/constraints/status" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/constraints/status', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/constraints/status', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/constraints/status', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/constraints/status", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "schema_version": 0,
  "coverage_kind": "unique_foreign_key_and_check",
  "state": "enforced",
  "ranges": [
    {
      "group_id": "string",
      "state": "enforced",
      "phase": "unique",
      "rows_scanned": "string",
      "owner": "string",
      "failure": "string"
    }
  ],
  "retirement": {
    "id": "string",
    "phase": "fencing",
    "drop": true,
    "target_schema_version": 0,
    "failure": "string"
  }
}

Repair version-conditional rows after failed or diagnosed constraint activation#

POST/tables/{tableName}/constraints/repair

Requires table administrator permission. Each affected target range must have failed UNIQUE/FK/CHECK activation or a validating MATCH PARTIAL missing-parent diagnostic. Replacement values still satisfy all constraints, and referential actions require write permission on every affected table. Existing dependencies remain protected. Repairs do not mark historical coverage valid. Invoke constraint retry after repairing failed activation; validating diagnostics resume validation automatically.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/constraints/repair" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/tables/{tableName}/constraints/repair', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/constraints/repair', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/constraints/repair',
    headers=headers,
    json={
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/constraints/repair", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

Restart failed UNIQUE/FK/CHECK validation after administrative repair#

POST/tables/{tableName}/constraints/retry

Requires table administrator permission. Resets each failed owner using an exact checkpoint precondition. Owners already validating or enforced are unchanged. Retrying after partial progress is safe. Inspect the constraint status endpoint for coverage and diagnostics. When a retirement job is active, clears its paused diagnostic and resumes that job instead of restarting activation. Retirement remains fenced and retains all prior drain progress.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/constraints/retry" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0
}'

const response = await fetch('/db/v1/tables/{tableName}/constraints/retry', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/constraints/retry', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/constraints/retry',
    headers=headers,
    json={
        "schema_version": 0
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/constraints/retry", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "accepted"
}

Retire unique and foreign-key definitions safely#

POST/tables/{tableName}/constraints/retire

Requires table administrator permission. Starts a durable, bounded all-owner drain. Poll constraints/status for progress. A target schema is published automatically after the drain. With drop=true the table remains fenced at ready_to_drop until an administrator explicitly deletes it with the existing table deletion endpoint.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/constraints/retire" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}'

const response = await fetch('/db/v1/tables/{tableName}/constraints/retire', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/constraints/retire', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/constraints/retire',
    headers=headers,
    json={
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/constraints/retire", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "accepted"
}

Query projected typed relational rows#

POST/tables/{tableName}/rows/query

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/rows/query" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}'

const response = await fetch('/db/v1/tables/{tableName}/rows/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/rows/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/rows/query',
    headers=headers,
    json={
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/rows/query", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

No response body

Atomically replace or delete version-conditional typed rows#

POST/tables/{tableName}/rows/mutate

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/rows/mutate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/tables/{tableName}/rows/mutate', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/rows/mutate', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/rows/mutate',
    headers=headers,
    json={
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/rows/mutate", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

Perform batch inserts and deletes on a table#

POST/tables/{tableName}/batch

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}'

const response = await fetch('/db/v1/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/batch',
    headers=headers,
    json={
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/batch", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

Synchronize data from external sources (Shopify, Postgres, S3) using a linear merge#

POST/tables/{tableName}/merge

Both source and destination must be sorted by the same key. Performs three-way merge:

Inserts new records from source
Updates changed records
Deletes Antfly records absent from source page

Stateless & Idempotent: No sync state between pages. Safe to restart from any page if interrupted.

Use Cases: Sync production databases, e-commerce APIs (Shopify, WooCommerce), data lake exports, or warehouse tables to Antfly for low-latency hybrid search.

WARNING: Not safe for concurrent merges with overlapping ranges. Single-client sync API only.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/merge" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/tables/{tableName}/merge', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/merge', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/merge',
    headers=headers,
    json={
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/merge", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "success",
  "upserted": 0,
  "skipped": 0,
  "deleted": 0,
  "deleted_ids": [
    "string"
  ],
  "failed": [
    {
      "id": "string",
      "operation": "upsert",
      "error": "string"
    }
  ],
  "next_cursor": "string",
  "key_range": {
    "from": "string",
    "to": "string"
  },
  "keys_scanned": 0,
  "message": "string",
  "took": 0
}

Backup a table#

POST/tables/{tableName}/backup

Backup IDs are immutable. Reusing an already published ID returns 409 without changing the existing backup.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/backup" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}'

const response = await fetch('/db/v1/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/backup',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/backup", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "backup": "successful"
}

Restore a table from backup#

POST/tables/{tableName}/restore

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`Idempotency-Key`	string	header	No	Stable key used to safely retry creation of this restore job. Keys are scoped to the authenticated principal and table. Requests without this header create a new job and return its generated key. Reuse that key after an unknown admission outcome; supply a key initially to recover from losing the entire response.

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/restore" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}'

const response = await fetch('/db/v1/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/restore',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/restore", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": "string",
  "idempotency_key": "string",
  "attempt_id": 0,
  "scope": "table",
  "table_name": "string",
  "backup_id": "string",
  "phase": "queued",
  "cancel_requested": true,
  "durability_pending_table_count": 0,
  "published_table_count": 0,
  "completed_table_count": 0,
  "total_table_count": 0,
  "result": {
    "restore": "triggered",
    "durability": "pending",
    "status": "completed",
    "triggered_table_count": 0,
    "committed_table_count": 0,
    "durability_pending_table_count": 0,
    "skipped_table_count": 0,
    "failed_table_count": 0,
    "failure_details": [
      {
        "table_name": "string",
        "error": "string",
        "table_name_truncated": true
      }
    ],
    "failure_details_truncated": true
  },
  "error": "string",
  "created_at_ms": 0,
  "updated_at_ms": 0,
  "expires_at_ms": 0
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Scan documents in a table within a key range#

POST/tables/{tableName}/documents

Scans keys in a table within an optional key range and returns them as newline-delimited JSON (NDJSON). Each line contains a JSON object with the _id document identifier and optionally projected document fields. This is useful for iterating through all keys in a table or a subset of keys within a range.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "equals": "string",
        "field": "string",
        "case_sensitive": true,
        "boost": 0
    },
    "limit": 100
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/documents" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "equals": "string",
        "field": "string",
        "case_sensitive": true,
        "boost": 0
    },
    "limit": 100
}'

const response = await fetch('/db/v1/tables/{tableName}/documents', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "equals": "string",
            "field": "string",
            "case_sensitive": true,
            "boost": 0
        },
        "limit": 100
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "equals": "string",
            "field": "string",
            "case_sensitive": true,
            "boost": 0
        },
        "limit": 100
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/documents',
    headers=headers,
    json={
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "equals": "string",
            "field": "string",
            "case_sensitive": true,
            "boost": 0
        },
        "limit": 100
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "equals": "string",
        "field": "string",
        "case_sensitive": true,
        "boost": 0
    },
    "limit": 100
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/documents", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

No response body

Retrieve a document by key#

GET/tables/{tableName}/documents/{key}

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`fields`	string	query	No	Comma-separated list of fields to include in the response.
If not specified, returns the full document. Supports:

Simple fields: "title,author"
Nested paths: "user.address.city"
Wildcards: "_chunks.*"
Exclusions: "-_chunks.*._embedding"
Special fields: "_embeddings,_summaries,_chunks" | | consistency | string | query | No | Read consistency for the lookup. The default read_index routes to the primary for linearizable reads. stale allows a hot standby to serve the lookup at its safe-read LSN. Owned object document tables support only explicit stale reads of published generations. The default read_index and leader_lease are rejected with HTTP 400. Use sync_level=full_index on writes to wait for publication before a stale lookup. |

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

List derived document artifact manifests#

GET/tables/{tableName}/documents/{key}/artifacts

Returns the derived document artifact manifests currently available for a source document. This lets clients discover artifact names before inspecting a single manifest or triggering reprocessing.

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`detail`	string	query	No	Response detail level. `summary` returns typed manifest fields only.
`raw` also includes opaque manifest/state JSON and requires table
admin permission when authentication is enabled.

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "document_id": "string",
  "artifacts": [
    {
      "document_id": "string",
      "artifact_name": "document_units_v1",
      "artifact_id": "string",
      "manifest_version": 0,
      "generation": 0,
      "source_url": "string",
      "source_fingerprint": "string",
      "content_type": "string",
      "route_type": "pdf",
      "unsupported_reason": "string",
      "unit_count": 0,
      "chunk_count": 0,
      "ocr_attempted_count": 0,
      "ocr_selected_count": 0,
      "ocr_retained_embedded_count": 0,
      "ocr_failed_count": 0,
      "ocr_failed_page_numbers": [
        0
      ],
      "ocr_failed_pages_truncated": true,
      "child_ranges": [
        {
          "range_id": "string",
          "range_kind": "string",
          "artifact_name": "string",
          "split_boundary": "string",
          "placement": "string",
          "owner_group_id": 0,
          "placement_generation": 0,
          "route_status": "string",
          "split_eligible": true,
          "start_key": "string",
          "end_key_exclusive": "string",
          "last_key": "string",
          "child_count": 0,
          "text_bytes": 0
        }
      ],
      "child_range_count": 0,
      "merge_status": "string",
      "merge_from_generation": 0,
      "merge_to_generation": 0,
      "merge_operation_granularity": "string",
      "merge_operation_count": 0,
      "last_error_code": "string",
      "last_error_message": "string",
      "manifest_json": "string",
      "state_json": "string"
    }
  ]
}

List table repair issues#

POST/tables/{tableName}/repair/issues

Lists durable repair debt for a table. This operator-facing endpoint returns exact document keys, artifact keys, index names, and repair errors, and therefore requires table admin permission when authentication is enabled. Request filters are supplied in the JSON body. This release supports target=artifact for durable artifact queue entries and target=index for index repair candidates.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/issues" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/issues', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/issues', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/issues',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/issues", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "table": "string",
  "target": "artifact",
  "limit": 0,
  "scanned": 0,
  "groups_scanned": 0,
  "has_more": true,
  "next_cursor": "string",
  "issues": [
    {
      "artifact_kind": "embedding",
      "index_name": "string",
      "doc_key": "string",
      "parent_doc_key": "string",
      "unit_id": "string",
      "index_source_artifact_name": "string",
      "source_artifact_name": "string",
      "artifact_name": "string",
      "artifact_key": "string",
      "chunk_id": 0,
      "repairable": true,
      "unsupported_reason": "string",
      "sequence": 0,
      "reason": "missing_artifact",
      "generation_attempts": 0,
      "generation_error": "string",
      "attempts": 0,
      "first_seen_ns": 0,
      "last_seen_ns": 0,
      "last_error": "string"
    }
  ]
}

Create or resume a table storage migration job#

POST/tables/{tableName}/storage/migrations

Table-admin operation for local single-shard standalone tables. Target vector_store changes primary_lsm source ownership without changing models, dimensions, artifacts or logical indexes. Retry creation with the same job_id, target and budgets. The job is advanced explicitly through its job endpoint; the server does not schedule an unattended migration loop. Offline migration uses antfly storage migrate against a stopped server.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "job_id": "string",
    "target": "vector_store",
    "budget": {
        "batch_bytes": 4096,
        "batch_rows": 1,
        "temporary_bytes": 0,
        "disk_reserve_bytes": 0
    }
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/storage/migrations" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "job_id": "string",
    "target": "vector_store",
    "budget": {
        "batch_bytes": 4096,
        "batch_rows": 1,
        "temporary_bytes": 0,
        "disk_reserve_bytes": 0
    }
}'

const response = await fetch('/db/v1/tables/{tableName}/storage/migrations', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "job_id": "string",
        "target": "vector_store",
        "budget": {
            "batch_bytes": 4096,
            "batch_rows": 1,
            "temporary_bytes": 0,
            "disk_reserve_bytes": 0
        }
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/storage/migrations', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "job_id": "string",
        "target": "vector_store",
        "budget": {
            "batch_bytes": 4096,
            "batch_rows": 1,
            "temporary_bytes": 0,
            "disk_reserve_bytes": 0
        }
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/storage/migrations',
    headers=headers,
    json={
        "job_id": "string",
        "target": "vector_store",
        "budget": {
            "batch_bytes": 4096,
            "batch_rows": 1,
            "temporary_bytes": 0,
            "disk_reserve_bytes": 0
        }
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "job_id": "string",
    "target": "vector_store",
    "budget": {
        "batch_bytes": 4096,
        "batch_rows": 1,
        "temporary_bytes": 0,
        "disk_reserve_bytes": 0
    }
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/storage/migrations", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

Read a table storage migration receipt#

GET/tables/{tableName}/storage/migrations/{jobId}

Table-admin observation only. Does not admit, advance, or publish a job. A phase of admitted means catalog admission is durable but DB preparation has not begun; retry creation or send a job action to recover it. The receipt is retained until a later migration replaces it; this endpoint is not a permanent job history.

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}/storage/migrations/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/storage/migrations/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/storage/migrations/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/storage/migrations/{jobId}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/storage/migrations/{jobId}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

Advance, publish or cancel a table storage migration job#

POST/tables/{tableName}/storage/migrations/{jobId}

Uses the job's durable configuration and budgets. Each step commits bounded progress. Publish is accepted only at ready; complete additionally certifies reference-only primary artifacts and native ANN serving. Cancellation is allowed only before publication. Repeating an action after an ambiguous response resumes the durable job.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "action": "step"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/storage/migrations/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "action": "step"
}'

const response = await fetch('/db/v1/tables/{tableName}/storage/migrations/{jobId}', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "action": "step"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/storage/migrations/{jobId}', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "action": "step"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/storage/migrations/{jobId}',
    headers=headers,
    json={
        "action": "step"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "action": "step"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/storage/migrations/{jobId}", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

Run a bounded table repair pass#

POST/tables/{tableName}/repair/run

Synchronously attempts to repair queued table issues. target=artifact reprocesses supported artifact kinds and replays derived state; it is bounded by limit and returns an opaque continuation cursor when another artifact repair page is available. target=index repairs one named index by building a shadow replacement, catching it up to the current derived replay sequence, and atomically swapping it into service; healthy indexes are skipped unless force=true is supplied, and any positive limit permits that single named index repair. The response reports unresolved debt separately, and the endpoint requires table admin permission when authentication is enabled.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/run" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/run', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/run', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/run',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/run", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "table": "string",
  "target": "artifact",
  "limit": 0,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  }
}

Start a durable table repair job#

POST/tables/{tableName}/repair/jobs

Creates a durable table repair job for large or long-running repair work. The job stores progress and accumulated counters across bounded advance calls. Use this endpoint instead of synchronous runTableRepair when repairing large indexes or when clients need retryable progress.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/jobs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/jobs',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Start a durable index control job#

POST/tables/{tableName}/repair/control-jobs

Applies pause, resume, or attempt cancellation across all table groups. Traversal is durable and server-owned. The resulting repair job can be inspected or cancelled with the regular repair job endpoints. Cancelling a control job stops remaining passes without undoing applied controls. This distinct endpoint prevents older servers from interpreting a control request as ordinary repair work.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "index": "string",
    "control": "pause_automatic",
    "repair_id": "string",
    "cursor": "string",
    "limit": 1,
    "advance": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/control-jobs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "index": "string",
    "control": "pause_automatic",
    "repair_id": "string",
    "cursor": "string",
    "limit": 1,
    "advance": true
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/control-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "control": "pause_automatic",
        "repair_id": "string",
        "cursor": "string",
        "limit": 1,
        "advance": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/control-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "control": "pause_automatic",
        "repair_id": "string",
        "cursor": "string",
        "limit": 1,
        "advance": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/control-jobs',
    headers=headers,
    json={
        "index": "string",
        "control": "pause_automatic",
        "repair_id": "string",
        "cursor": "string",
        "limit": 1,
        "advance": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "index": "string",
    "control": "pause_automatic",
    "repair_id": "string",
    "cursor": "string",
    "limit": 1,
    "advance": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/control-jobs", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Get a table repair job#

GET/tables/{tableName}/repair/jobs/{jobId}

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}/repair/jobs/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/repair/jobs/{jobId}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/repair/jobs/{jobId}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Advance a table repair job#

POST/tables/{tableName}/repair/jobs/{jobId}/advance

Runs at most one bounded repair pass for the job. Concurrent advances use the job lease and return the current running state.

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}/repair/jobs/{jobId}/advance" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Cancel a table repair job#

POST/tables/{tableName}/repair/jobs/{jobId}/cancel

Requests cancellation at a bounded repair boundary. For a named-index job, the server also traverses the table in bounded passes, durably pauses matching automatic repair, and asks an active owner to yield. The job remains nonterminal until that traversal completes, so a cancelled response means detached reconstruction will not restart without an explicit resume action. If the API process restarts during the traversal, server maintenance resumes it automatically; clients do not need to advance or repeat the cancellation request.

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}/repair/jobs/{jobId}/cancel" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "control": "pause_automatic",
  "repair_id": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "next_retry_at_millis": 0,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Reprocess a derived artifact across a table range#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess

Runs a bounded operational repair pass for any asset or embedding producer across source rows in key order. Use next_key from the response as the next request's from_key for simple single-cursor continuation. Distributed repair controllers should persist shard_cursors from the response and pass them back on the next request to resume each shard independently when scanning large sharded tables.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}'

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess',
    headers=headers,
    json={
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "reprocess": "triggered",
  "reprocess_status": "in_progress",
  "artifact_name": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "limit": 0,
  "next_key": "string",
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ]
}

Create a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs

Creates a durable user-facing repair job for a derived document asset or embedding artifact. The job advances through the same bounded per-shard repair primitive used by /reprocess, and stores returned continuation cursors so hosted controllers can resume large sharded table repairs without collapsing progress into a single global key cursor.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}'

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs',
    headers=headers,
    json={
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Get derived document artifact reprocess job status#

GET/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}

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/{artifactName}/reprocess-jobs/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Advance a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance

Runs one bounded repair pass and persists the resulting job state.

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}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Cancel a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel

Cancels a queued document artifact reprocess job. If a reprocess pass is already running, the response returns the current running state; cancellation is applied only at pass boundaries so the API never reports a committed in-flight pass as cancelled.

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}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Inspect a derived document artifact manifest#

GET/tables/{tableName}/documents/{key}/artifacts/{artifactName}

Returns manifest and processing state for a derived document artifact, such as the document-unit hierarchy extracted from a PDF, HTML page, or text field. The route is shard-aware; hosted deployments route the request to the data group that owns the source document key.

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`detail`	string	query	No	Response detail level. `summary` returns typed manifest fields only.
`raw` also includes opaque manifest/state JSON and requires table
admin permission when authentication is enabled.

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "document_id": "string",
  "artifact_name": "document_units_v1",
  "artifact_id": "string",
  "manifest_version": 0,
  "generation": 0,
  "source_url": "string",
  "source_fingerprint": "string",
  "content_type": "string",
  "route_type": "pdf",
  "unsupported_reason": "string",
  "unit_count": 0,
  "chunk_count": 0,
  "ocr_attempted_count": 0,
  "ocr_selected_count": 0,
  "ocr_retained_embedded_count": 0,
  "ocr_failed_count": 0,
  "ocr_failed_page_numbers": [
    0
  ],
  "ocr_failed_pages_truncated": true,
  "child_ranges": [
    {
      "range_id": "string",
      "range_kind": "string",
      "artifact_name": "string",
      "split_boundary": "string",
      "placement": "string",
      "owner_group_id": 0,
      "placement_generation": 0,
      "route_status": "string",
      "split_eligible": true,
      "start_key": "string",
      "end_key_exclusive": "string",
      "last_key": "string",
      "child_count": 0,
      "text_bytes": 0
    }
  ],
  "child_range_count": 0,
  "merge_status": "string",
  "merge_from_generation": 0,
  "merge_to_generation": 0,
  "merge_operation_granularity": "string",
  "merge_operation_count": 0,
  "last_error_code": "string",
  "last_error_message": "string",
  "manifest_json": "string",
  "state_json": "string"
}

Reprocess a derived artifact#

POST/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess

Invalidates the current artifact state and requests the producer to rebuild the derived asset for the source document. Copy, generator, reader, transcriber, extractor, and document-extraction producers are all supported, as are dense and sparse embedding producers. Embedding reprocessing regenerates vectors even when the source chunks are unchanged. Embedding requests are committed durably and queued for supervised inference. Acceptance does not wait for inference; inspect index coverage and repair issues for the eventual outcome.

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}/documents/{key}/artifacts/{artifactName}/reprocess" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "reprocess": "triggered"
}

Perform batch inserts and deletes on an explicit namespace table#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch

Performs batch writes through an explicit database and namespace route. While storage APIs are still bare-table-name based, the server fails closed when the resolved catalog table does not map to a unique physical table name.

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch',
    headers=headers,
    json={
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/batch", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

Backup an explicit namespace table#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/backup", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "backup": "successful"
}

Restore an explicit namespace table from backup#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`Idempotency-Key`	string	header	No	Stable key used to safely retry creation of this restore job. Keys are scoped to the authenticated principal and table. Requests without this header create a new job.

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/restore", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": "string",
  "idempotency_key": "string",
  "attempt_id": 0,
  "scope": "table",
  "table_name": "string",
  "backup_id": "string",
  "phase": "queued",
  "cancel_requested": true,
  "durability_pending_table_count": 0,
  "published_table_count": 0,
  "completed_table_count": 0,
  "total_table_count": 0,
  "result": {
    "restore": "triggered",
    "durability": "pending",
    "status": "completed",
    "triggered_table_count": 0,
    "committed_table_count": 0,
    "durability_pending_table_count": 0,
    "skipped_table_count": 0,
    "failed_table_count": 0,
    "failure_details": [
      {
        "table_name": "string",
        "error": "string",
        "table_name_truncated": true
      }
    ],
    "failure_details_truncated": true
  },
  "error": "string",
  "created_at_ms": 0,
  "updated_at_ms": 0,
  "expires_at_ms": 0
}

Retrieve a document by key from an explicit namespace table#

GET/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}

Retrieves a document through an explicit database and namespace route. While storage APIs are still bare-table-name based, the server fails closed when the resolved catalog table does not map to a unique physical table name.

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

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`fields`	string	query	No	Comma-separated list of fields to include in the response.
`consistency`	string	query	No	Read consistency; defaults to read_index.

Code Examples#

curl -X GET "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}?fields=value&consistency=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}?fields=value&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}?fields=value&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}?fields=value&consistency=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/documents/{key}?fields=value&consistency=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

Read distributed UNIQUE, foreign-key, and CHECK validation coverage#

GET/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/status

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}/constraints/status" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/status', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/status', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/status', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/status", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "schema_version": 0,
  "coverage_kind": "unique_foreign_key_and_check",
  "state": "enforced",
  "ranges": [
    {
      "group_id": "string",
      "state": "enforced",
      "phase": "unique",
      "rows_scanned": "string",
      "owner": "string",
      "failure": "string"
    }
  ],
  "retirement": {
    "id": "string",
    "phase": "fencing",
    "drop": true,
    "target_schema_version": 0,
    "failure": "string"
  }
}

Repair version-conditional rows after failed or diagnosed constraint activation#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair',
    headers=headers,
    json={
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/repair", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

Restart failed UNIQUE/FK/CHECK validation after administrative repair#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry',
    headers=headers,
    json={
        "schema_version": 0
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retry", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "accepted"
}

Retire unique and foreign-key definitions safely#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire',
    headers=headers,
    json={
        "schema_version": 0,
        "target_schema": {
            "version": 0,
            "storage_mode": "document",
            "base_source": {
                "kind": "external",
                "table_id": "string",
                "format": "parquet",
                "uri": "string",
                "row_identity_version": 1,
                "schema_fingerprint": "string",
                "write_policy": "read_only",
                "object_mutability": "mutable",
                "credentials": {
                    "ref": "string",
                    "scope": "string"
                },
                "snapshot": {
                    "mode": "current",
                    "id": "string",
                    "digest": "string"
                },
                "catalog": {
                    "type": "managed",
                    "connection": "string",
                    "uri": "string",
                    "namespace": [
                        "string"
                    ],
                    "name": "string",
                    "warehouse": "string"
                }
            },
            "column_defaults": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "generated_columns": [
                {
                    "column": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "checks": [
                {
                    "name": "string",
                    "column": "string",
                    "op": "is_null",
                    "value": null,
                    "collation": "string",
                    "expression": {
                        "op": "literal",
                        "type": "string",
                        "sql_type": "text",
                        "numeric_modifier": {
                            "precision": 1,
                            "scale": -1000
                        },
                        "value": null,
                        "column": "string",
                        "collation": "string",
                        "args": [
                            "..."
                        ]
                    }
                }
            ],
            "unique_constraints": [
                {
                    "name": "string",
                    "origin": "constraint",
                    "primary": true,
                    "columns": [
                        "string"
                    ],
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ],
                    "nulls_not_distinct": true,
                    "deferrable": true,
                    "timing": "immediate"
                }
            ],
            "foreign_keys": [
                {
                    "name": "string",
                    "child_columns": [
                        "string"
                    ],
                    "parent_table": "string",
                    "parent_columns": [
                        "string"
                    ],
                    "on_delete": "restrict",
                    "on_update": "restrict",
                    "timing": "immediate",
                    "match": "simple",
                    "deferrable": true
                }
            ],
            "relational_indexes": [
                {
                    "description": "string",
                    "name": "string",
                    "keys": [
                        {
                            "column": "string",
                            "expression": {
                                "op": "literal",
                                "type": "string",
                                "sql_type": "text",
                                "numeric_modifier": {
                                    "precision": 1,
                                    "scale": -1000
                                },
                                "value": null,
                                "column": "string",
                                "collation": "string",
                                "args": [
                                    "..."
                                ]
                            },
                            "result_type": "string",
                            "collation": "string",
                            "direction": "asc",
                            "nulls": "default"
                        }
                    ],
                    "include_columns": [
                        "string"
                    ],
                    "where": [
                        {
                            "column": "string",
                            "op": "is_null",
                            "value": null,
                            "collation": "string"
                        }
                    ]
                }
            ],
            "default_type": "string",
            "enforce_types": true,
            "document_schemas": {},
            "ttl": {
                "duration": "string",
                "field": "string"
            },
            "ttl_field": "string",
            "ttl_duration": "string",
            "dynamic_templates": [
                {
                    "name": "string",
                    "match": "string",
                    "unmatch": "string",
                    "path_match": "string",
                    "path_unmatch": "string",
                    "match_mapping_type": "string",
                    "mapping": {
                        "type": "text",
                        "analyzer": "string",
                        "index": true,
                        "store": true,
                        "include_in_all": true,
                        "sortable": true,
                        "missing_null_policy": "missing_rejected"
                    }
                }
            ]
        },
        "drop": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "target_schema": {
        "version": 0,
        "storage_mode": "document",
        "base_source": {
            "kind": "external",
            "table_id": "string",
            "format": "parquet",
            "uri": "string",
            "row_identity_version": 1,
            "schema_fingerprint": "string",
            "write_policy": "read_only",
            "object_mutability": "mutable",
            "credentials": {
                "ref": "string",
                "scope": "string"
            },
            "snapshot": {
                "mode": "current",
                "id": "string",
                "digest": "string"
            },
            "catalog": {
                "type": "managed",
                "connection": "string",
                "uri": "string",
                "namespace": [
                    "string"
                ],
                "name": "string",
                "warehouse": "string"
            }
        },
        "column_defaults": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "generated_columns": [
            {
                "column": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "checks": [
            {
                "name": "string",
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string",
                "expression": {
                    "op": "literal",
                    "type": "string",
                    "sql_type": "text",
                    "numeric_modifier": {
                        "precision": 1,
                        "scale": -1000
                    },
                    "value": null,
                    "column": "string",
                    "collation": "string",
                    "args": [
                        "..."
                    ]
                }
            }
        ],
        "unique_constraints": [
            {
                "name": "string",
                "origin": "constraint",
                "primary": true,
                "columns": [
                    "string"
                ],
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ],
                "nulls_not_distinct": true,
                "deferrable": true,
                "timing": "immediate"
            }
        ],
        "foreign_keys": [
            {
                "name": "string",
                "child_columns": [
                    "string"
                ],
                "parent_table": "string",
                "parent_columns": [
                    "string"
                ],
                "on_delete": "restrict",
                "on_update": "restrict",
                "timing": "immediate",
                "match": "simple",
                "deferrable": true
            }
        ],
        "relational_indexes": [
            {
                "description": "string",
                "name": "string",
                "keys": [
                    {
                        "column": "string",
                        "expression": {
                            "op": "literal",
                            "type": "string",
                            "sql_type": "text",
                            "numeric_modifier": {
                                "precision": 1,
                                "scale": -1000
                            },
                            "value": null,
                            "column": "string",
                            "collation": "string",
                            "args": [
                                "..."
                            ]
                        },
                        "result_type": "string",
                        "collation": "string",
                        "direction": "asc",
                        "nulls": "default"
                    }
                ],
                "include_columns": [
                    "string"
                ],
                "where": [
                    {
                        "column": "string",
                        "op": "is_null",
                        "value": null,
                        "collation": "string"
                    }
                ]
            }
        ],
        "default_type": "string",
        "enforce_types": true,
        "document_schemas": {},
        "ttl": {
            "duration": "string",
            "field": "string"
        },
        "ttl_field": "string",
        "ttl_duration": "string",
        "dynamic_templates": [
            {
                "name": "string",
                "match": "string",
                "unmatch": "string",
                "path_match": "string",
                "path_unmatch": "string",
                "match_mapping_type": "string",
                "mapping": {
                    "type": "text",
                    "analyzer": "string",
                    "index": true,
                    "store": true,
                    "include_in_all": true,
                    "sortable": true,
                    "missing_null_policy": "missing_rejected"
                }
            }
        ]
    },
    "drop": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/constraints/retire", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "accepted"
}

Query projected typed relational rows#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query',
    headers=headers,
    json={
        "index": "string",
        "after": "string",
        "lower": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "upper": {
            "values": [
                null
            ],
            "inclusive": true
        },
        "fields": [
            "string"
        ],
        "conditions": [
            {
                "column": "string",
                "op": "is_null",
                "value": null,
                "collation": "string"
            }
        ],
        "from": "string",
        "to": "string",
        "limit": 1,
        "schema_version": 0
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "index": "string",
    "after": "string",
    "lower": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "upper": {
        "values": [
            null
        ],
        "inclusive": true
    },
    "fields": [
        "string"
    ],
    "conditions": [
        {
            "column": "string",
            "op": "is_null",
            "value": null,
            "collation": "string"
        }
    ],
    "from": "string",
    "to": "string",
    "limit": 1,
    "schema_version": 0
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/query", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

No response body

Atomically replace or delete version-conditional typed rows#

POST/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate

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

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate',
    headers=headers,
    json={
        "schema_version": 0,
        "mutations": [
            {
                "key": "string",
                "expected_version": "string",
                "row": {},
                "json_null_fields": [
                    "string"
                ]
            }
        ],
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "schema_version": 0,
    "mutations": [
        {
            "key": "string",
            "expected_version": "string",
            "row": {},
            "json_null_fields": [
                "string"
            ]
        }
    ],
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/rows/mutate", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0,
  "failure": {
    "code": "string",
    "message": "string",
    "reason": "string",
    "retryable": true
  }
}