Run a query (I/O API)

This endpoint runs a query across multiple entries in a bucket. Use the returned query ID with the I/O API read endpoint (GET /api/v1/io/:bucket_name/read).

POST

/api/v1/io/:bucket_name/q

Run a query across entries in a bucket

JSON request body

The request body is the same query model as the Entry API, with an additional entries field to select multiple entries:

{
  // Required. Possible values: "QUERY", "REMOVE".
  query_type: 'string';

  // Optional. Entry patterns to query or delete records from.
  entries?: 'string[]';

  // Optional. The start UNIX timestamp of the query in microseconds.
  start?: 'integer';

  // Optional. The end UNIX timestamp of the query in microseconds.
  stop?: 'integer';

  // Optional. A conditional query to filter records.
  when?: 'object';

  // Optional. Extension configuration.
  ext?: 'object';

  // Optional. TTL (Time To Live) in seconds for the query.
  ttl?: 'integer';

  // Optional. If true, the query will remain open for continuous data retrieval.
  continuous?: 'boolean';

  // Optional. Return only metadata without record bodies.
  only_metadata?: 'boolean';
}

info

For query_type: "REMOVE", define at least one query parameter (for example entries, start/stop, or when). An empty remove query is rejected.

Entry filtering

• If entries is omitted, the query applies to all entries in the bucket.
• If entries contains only exclusions, the query first selects all entries and then removes the excluded matches.
• Include patterns are resolved first. Patterns prefixed with ! exclude matching entries after includes are resolved.
• Exact names continue to work unchanged.
• * matches any characters inside one path segment. For example, /a/*/b matches /a/x/b but not /a/x/d/b.
• ** matches recursively across path segments. For example, /a/**/b matches both /a/x/b and /a/x/d/b.
• For flat names, a trailing * matches names that start with the same prefix, so cam-* matches cam-1 and cam-left.

For example, this query includes every entry below /a that ends with /b, excludes the private subtree, and also includes flat camera entries:

{
  "query_type": "QUERY",
  "entries": ["/a/**/b", "!/a/private/**", "cam-*"]
}

Responses

If the query type is QUERY, the API returns a JSON object with the query ID:

{
  id: "integer";
}

If the query type is REMOVE, the API returns a JSON object with the number of removed records:

{
  removed_records: "integer";
}