CLcloudglue
Query

Run a structured query

Changed on

Run a synchronous read-only SQL query over the structured data extracted from one or more collections. Queries execute against three virtual tables — files, entities, and segment_entities — built from each file's most recent completed extraction.

Each query costs 2 credits. Results are returned inline and stored, so completed runs can be re-fetched via GET /query/{id}. Use GET /query/schema to discover the queryable tables and per-collection fields.

post/query

Request

  • Base URL
    https://api.cloudglue.dev/v1
  • Auth
    HTTP bearer

Request body

collectionsstring[] required

Collection IDs to query over. All collections must belong to your account; face-analysis collections are not supported.

sqlstring

A single read-only SQL SELECT statement over the virtual tables (files, entities, segment_entities). Exactly one of sql or query must be provided.

querystring

A natural-language question to run instead of sql. Cloudglue compiles it to SQL against the same virtual schema, runs it, and returns the compiled statement in the response's sql field. Exactly one of sql or query must be provided. Costs 4 credits (refunded if compilation fails); returns 422 if it cannot be compiled.

format'json' | 'csv' | 'jsonl'

Result format. 'json' returns rows inline (synchronous). 'csv' and 'jsonl' are for background exports only and require background: true.

max_rowsinteger

Maximum number of result rows to return inline. Results with more rows are truncated (truncated: true). Does not apply to background exports, which stream the full result.

backgroundboolean

When true, run the query as a background export: the full result streams to a gzipped csv/jsonl file and the response returns immediately with status 'in_progress' and an id to poll. Requires format 'csv' or 'jsonl'. Reserves 4 credits, reconciled to +1 per 100MB of compressed output. Cannot be combined with dry_run.

dry_runboolean

When true, validate (and, for a natural-language query, compile) the statement and return the effective SQL plus its output column schema without executing it over any data. No rows are produced and it is billed at a reduced rate. Cannot be combined with background.

Response

Query executed successfully

idstring uuid

Query result ID

object'query_result'

Object type identifier

status'completed' | 'failed' | 'in_progress' | 'cancelled'

Current status of the query. Synchronous queries return 'completed' or 'failed'.

created_atnumber

Unix timestamp of when the query was created

collectionsstring[]

Collection IDs the query ran over

sqlstring nullable

The effective SQL that was executed (echoes the request's sql)

rowsobject[] nullable

Result rows as objects keyed by column name

row_countinteger

Number of rows returned

truncatedboolean

Whether the result was truncated by max_rows or the stored-result size cap

dry_runboolean

True when the query was only validated/compiled (dry_run request): columns holds the output schema and rows is null.

format'json' | 'csv' | 'jsonl' nullable

The result format ('csv'/'jsonl' for background exports)

download_urlstring nullable

Signed URL to download a completed background export. Valid for 24 hours and not refreshed on read (re-run the export if it expires); null for synchronous runs and until a background export completes

download_expires_atnumber nullable

Unix timestamp (ms) when download_url expires

output_bytesinteger nullable

Compressed size of a completed background export, in bytes

Changes

  • 23d3f240819fRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • a7a390d80571Revision changes
    • info

      endpoint added