Query tables

query_tables answers one natural-language question over uploaded workbooks.

Python
TypeScript
curl

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    answer = client.tools.query_tables(
        workspace_id,
        paths=["books/ledger.xlsx", "books/trial-balance.xlsx"],
        query="Which accounts increased more than 10 percent?",
    )
    print(answer.answer)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const answer = await client.tools.queryTables(workspaceId, {
  paths: ["books/ledger.xlsx", "books/trial-balance.xlsx"],
  query: "Which accounts increased more than 10 percent?",
});
console.log(answer.answer);

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/query-tables" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":[{"path":"books/ledger.xlsx"}],"query":"Which accounts increased more than 10 percent?"}'

Table QA continues after an HTTP disconnect. Current Python and TypeScript SDKs submit a durable job and poll it internally; the methods above still return QueryTablesResponse. They also accept direct answers from older servers. Older SDKs and CLIs keep the original synchronous response contract. An older client’s own HTTP timeout can still expire, but it no longer cancels the accepted work. For direct HTTP integrations, send Prefer: respond-async with a stable Idempotency-Key. The response is a Job (202 while pending, 200 when terminal), with a Location header pointing to GET /v1/jobs/{job_id}. Poll that URL for the stored result. Retry a lost submission response using the same key and body to recover the same job. Omit Prefer to wait for the original answer response. Explicit cancellation uses POST /v1/jobs/{job_id}/cancel; stopping a request or SDK poll does not cancel execution. Workbooks must be ingested first so parquet tables exist. The response keeps the full result in scratch storage and returns the answer, citations, unavailable sources, and a bounded preview. Pass output_schema, a JSON Schema (or, in Python, a Pydantic model class), to get the answer as JSON. Both the SQL engine and the QA agent are checked against it and corrected on a miss. On success answer is the JSON text and structured_answer the parsed value. A field the source does not state comes back null, whatever type the schema gives it. If the answer still misses, the call still succeeds and structured_answer is null. The schema root must be an object, and pattern / patternProperties, a recursive $ref and unevaluatedProperties / unevaluatedItems are refused.

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    response = client.tools.query_tables(
        workspace_id,
        paths=["finance/trial_balance.xlsx"],
        query="What is the total of the cash accounts?",
        output_schema={
            "type": "object",
            "required": ["total"],
            "properties": {"total": {"type": "number"}},
        },
    )
    print(response.structured_answer)

Use qa-file for PDFs and other documents, or for a question about a single file.

Getting started

Guides

Agents

Concepts

Troubleshooting