Antfly · Schema
StatefulQueryRequest
Stateful Antfly query request. Canonical clients use graph_queries; deprecated graph_searches is retained only at the stateful public transport boundary for the v0.2 transition window.
Artificial IntelligenceSearchRetrievalVectorsHybrid
Properties
| Name | Type | Description |
|---|---|---|
| execution | object | |
| read_requirements | object | |
| remote_snapshot | string | Opaque retained snapshot token returned by an ordered native or external-table query. Echo with search_after or search_before. Native and lake cuts expire within the configured retention period (defau |
| evaluate | object | |
| table_target | object | |
| table | string | Literal table name in default.public. Global queries require exactly one of table or table_target. |
| query | object | Canonical public query AST. Prefer this field for new clients. Boolean clauses are normalized before planning: - `bool.must` is scoring query input. - `bool.filter` is non-scoring query input. - `bool |
| full_text_search | object | Antfly query for full-text search. Supports all Antfly query types. See specs/openapi/antfly/query.yaml for complete type definitions. Examples: - Simple: `{"query": "computer"}` - Field-specific: `{" |
| full_text_index | string | Full-text index used by `full_text_search` and by scoring text clauses in `query`. Use this to query a named document- or artifact-backed full-text index. The selected index must exist and have type ` |
| semantic_search | string | Natural language query for vector similarity search. Results are ranked by semantic similarity to the query and can be combined with full_text_search using Reciprocal Rank Fusion (RRF). The semantic_s |
| embedding_template | string | Optional Handlebars template for multimodal embedding of the semantic_search query. The template has access to `this` which contains the semantic_search string value. UTF-8 template input is limited t |
| indexes | array | Embedding index names selected for `semantic_search` or explicit `embeddings`. Dense and sparse indexes are supported when the corresponding query representation is supplied. Provisioned deployments r |
| filter_prefix | string | Filter results by key prefix. Only returns documents whose keys start with this string. Applied before scoring to improve performance. Common use cases: - Multi-tenant filtering: `"tenant:acme:"` - Us |
| filter_query | object | Antfly query applied as an AND condition. Documents must match both the main query and this filter. Applied before scoring for better performance. See specs/openapi/antfly/query.yaml for complete type |
| exclusion_query | object | Antfly query applied as a NOT condition. Documents matching this query are excluded from results. Applied before scoring. See specs/openapi/antfly/query.yaml for complete type definitions. Use for: - |
| aggregations | object | Aggregation requests for computing metrics and bucketing results. Each key is a user-defined name for the aggregation, and the value specifies the aggregation configuration. When `hierarchy.group_by` |
| embeddings | object | Pre-computed embeddings to use for semantic searches instead of embedding the semantic_search string. The keys are the index names. Values can be either: - **Dense (array)**: an array of floats, e.g. |
| search_effort | number | Controls the vector search recall/latency tradeoff for semantic searches. - `0.0` = fastest, lowest recall - `0.5` = balanced default - `1.0` = highest recall When omitted, Antfly uses the balanced de |
| select | object | Pure named output expressions evaluated after final filtering, ranking and pagination; returned in _computed. Compatible with fields, which selects stored _source. Uses the SQL scalar engine and lazy |
| params | object | Request-local values bound by select expressions through param. Parameters are data, never executable expressions or read grants. The serialized parameter object is limited to 1 MiB and 1024 named par |
| fields | array | List of fields to include in the results. If not specified, all fields are returned. Use to reduce response size and improve performance. This field is required when hierarchy.group_by is present so a |
| hierarchy | object | |
| highlight | object | |
| limit | integer | Maximum number of top-level results to return. For semantic_search, this is the topk parameter. This does not limit nested matches attached through hierarchy.group_by.matches; use hierarchy.group_by.m |
| offset | integer | Number of results to skip for pagination. Supported for text-backed, match_all, and filter-only requests. Approximate semantic requests do not support offset on their own. Semantic and hybrid requests |
| timeout_ms | integer | Optional query execution deadline in milliseconds. The server applies this as a cooperative deadline across query planning, search execution, aggregation reruns, sorting, and response post-processing. |
| order_by | array | Sort order for results. Array of sort fields with direction. Antfly appends `_id` ascending as a stable tie-breaker when it is omitted. Hierarchy child traversal requires `_hierarchy.position` ascendi |
| search_after | array | Cursor for forward pagination. Pass the `_sort` values from the last hit of the previous page exactly, including the appended `_id` tie-breaker. Values preserve their JSON types; for example numbers r |
| search_before | array | Cursor for backward pagination. Pass the `_sort` values from the first hit of the current page exactly, including the appended `_id` tie-breaker. Values preserve their JSON types; for example numbers |
| distance_under | number | Maximum distance threshold for semantic similarity search. Results with distance greater than this value are excluded. Lower distances indicate higher similarity. Useful for filtering out low-confiden |
| distance_over | number | Minimum distance threshold for semantic similarity search. Results with distance less than this value are excluded. Useful for excluding near-exact duplicates or finding dissimilar documents. |
| merge_config | object | Configuration for merging full-text and semantic search results. Only applies when both `full_text_search` and `semantic_search` are specified. |
| count | boolean | If true, returns only the total count of matching documents without retrieving the actual documents. Useful for pagination and displaying result counts. Count-only requests do not return an ordered re |
| profile | boolean | If true, includes detailed execution profiling in the response. Adds a `profile` object with per-phase timing breakdowns, shard statistics, join metadata, reranker stats, and merge details. Has minor |
| reranker | object | Optional reranker configuration to improve result relevance. Rerankers use cross-encoder models that score query-document pairs directly, providing more accurate relevance scores than embedding simila |
| graph_metric | object | Direct top-k read from a published graph metric generation. Results are returned in graph_metric_results under the requested name or the metric name when no explicit name is supplied. Supplying seed_n |
| graph_metric_rerank | object | Blend a published graph metric feature into ordinary search hit scores. Requests may require either any published generation or a generation that is fresh with respect to graph writes. Supplying seed_ |
| analyses | object | |
| graph_queries | object | Declarative graph matching, traversal, and path queries. A nested node `filter` is a typed, non-scoring stored-document predicate. It shares familiar scalar syntax with document queries but deliberate |
| document_renderer | string | Not supported on queries, which do not generate text; requests that set it are rejected. Set `document_renderer` on a retrieval agent request to control how documents appear in the generation prompt. |
| pruner | object | Optional result pruning configuration to filter low-relevance results. Pruning helps detect "elbows" in score distributions and removes results that are significantly worse than top matches. It runs o |
| join | object | Cross-table join configuration for combining results from multiple tables. Joins allow you to enrich query results with data from related tables, similar to SQL JOINs but optimized for distributed exe |
| foreign_sources | object | Map of table name to foreign data source configuration for query-time federated access. When a table name referenced in this query (or in a join's `right_table`) appears as a key here, the query is ro |
| graph_searches | object | Deprecated compatibility alias for the v0.2 graph query contract. Use `graph_queries`; requests containing both fields are rejected. Legacy operation names remain opaque and byte-for-byte compatible; |
| expand_strategy | string | Deprecated compatibility behavior for `graph_searches`. Canonical `graph_queries` return independently typed, potentially table-qualified identities and cannot be combined with this field. Strategy fo |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/antfly/json-schema/antfly-stateful-query-request-schema.json",
"title": "StatefulQueryRequest",
"description": "Stateful Antfly query request. Canonical clients use graph_queries; deprecated graph_searches is retained only at the stateful public transport boundary for the v0.2 transition window.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/antfly-query-operations-api-openapi.yml#/components/schemas/StatefulQueryRequest",
"allOf": [
{
"$ref": "#/$defs/QueryRequest"
},
{
"type": "object",
"not": {
"anyOf": [
{
"description": "Use graph_queries or deprecated graph_searches, never both.",
"required": [
"graph_queries",
"graph_searches"
]
},
{
"description": "Canonical graph_queries return typed results and cannot use the legacy hit expansion adapter.",
"required": [
"graph_queries",
"expand_strategy"
]
},
{
"description": "Hierarchy child traversal cannot use the legacy graph hit expansion adapter.",
"allOf": [
{
"required": [
"hierarchy"
],
"properties": {
"hierarchy": {
"required": [
"children"
]
}
}
},
{
"anyOf": [
{
"required": [
"graph_searches"
]
},
{
"required": [
"expand_strategy"
]
}
]
}
]
}
]
},
"properties": {
"graph_searches": {
"deprecated": true,
"type": "object",
"maxProperties": 64,
"additionalProperties": {
"$ref": "#/$defs/LegacyGraphQuery"
},
"description": "Deprecated compatibility alias for the v0.2 graph query contract.\nUse `graph_queries`; requests containing both fields are rejected.\nLegacy operation names remain opaque and byte-for-byte compatible;\ncanonical GraphIdentifier rules apply only to `graph_queries`.\nThe request-wide limit of 64 operations also applies here to bound\nexecution work during the compatibility window.\n"
},
"expand_strategy": {
"deprecated": true,
"type": "string",
"enum": [
"union",
"intersection"
],
"description": "Deprecated compatibility behavior for `graph_searches`. Canonical\n`graph_queries` return independently typed, potentially table-qualified\nidentities and cannot be combined with this field.\n\nStrategy for merging legacy graph results with search results:\n- union: Include nodes from both search and graph results\n- intersection: Only include nodes appearing in both\n"
}
}
}
],
"$defs": {
"AggregationDateRange": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the date range bucket"
},
"from": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "Start date (ISO 8601 or relative like \"now-7d\")"
},
"to": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "End date (ISO 8601 or relative like \"now\")"
}
}
},
"AggregationRange": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the range bucket"
},
"from": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Lower bound (inclusive)"
},
"to": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Upper bound (exclusive)"
}
}
},
"AggregationRequest": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"$ref": "#/$defs/AggregationType"
},
"field": {
"type": "string",
"description": "Field to aggregate on. Required unless `fields` is supplied for a multi-field terms aggregation."
},
"mode": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/CardinalityMode"
}
],
"description": "Selection mode for a cardinality aggregation. `auto` (default) uses a materialized HyperLogLog sketch when one applies and is current, else falls back to an exact distinct scan. `exact` always scans. `approximate` requires a sketch and errors if none applies. Ignored for other types."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered field list for multi-field terms aggregations. Each bucket key is a JSON string containing the serialized value array in the same order; clients should parse bucket.key as JSON."
},
"size": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Maximum number of buckets to return (for bucketing aggregations)"
},
"ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/AggregationRange"
},
"description": "Ranges for range aggregations"
},
"date_ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/AggregationDateRange"
},
"description": "Date ranges for date_range aggregations"
},
"interval": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Fixed interval for histogram aggregations"
},
"calendar_interval": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/CalendarInterval"
}
],
"description": "Calendar-aware interval for date_histogram aggregations"
},
"origin": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "Origin for geohash_grid aggregation (format: \"lat,lon\")\nExample: \"37.7749,-122.4194\"\n"
},
"precision": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Geohash precision (1-12) for geohash_grid aggregations"
},
"distance_ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/DistanceRange"
},
"description": "Distance ranges for geo_distance aggregations"
},
"unit": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/DistanceUnit"
}
],
"description": "Distance unit for geo_distance aggregations"
},
"min_doc_count": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Minimum document count for a bucket to be included"
},
"background_filter": {
"$ref": "#/$defs/RawQuery",
"description": "Background filter for significant_terms aggregations"
},
"algorithm": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/SignificanceAlgorithm"
}
],
"description": "Significance algorithm for significant_terms aggregations"
},
"algebraic_join": {
"$ref": "#/$defs/AlgebraicAggregationJoin",
"description": "Algebraic join descriptor for bounded cross-table aggregation planning"
},
"sub_aggregations": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/AggregationRequest"
},
"description": "Nested sub-aggregations"
}
}
},
"AggregationType": {
"type": "string",
"enum": [
"sum",
"avg",
"min",
"max",
"count",
"sumsquares",
"stats",
"cardinality",
"terms",
"range",
"date_range",
"histogram",
"date_histogram",
"geohash_grid",
"geo_distance",
"significant_terms"
],
"description": "Type of aggregation to compute:\n- Metrics: sum, avg, min, max, count, sumsquares, stats, cardinality\n- Bucketing: terms, range, date_range, histogram, date_histogram\n- Geo: geohash_grid, geo_distance\n- Analytics: significant_terms\n"
},
"AlgebraicAggregationJoin": {
"type": "object",
"required": [
"name",
"group_side",
"measure_side"
],
"properties": {
"name": {
"type": "string",
"description": "Algebraic join materialization or capability name"
},
"kind": {
"type": "string",
"enum": [
"none",
"bucket",
"window",
"bucket_window"
],
"x-go-type-skip-optional-pointer": false,
"description": "Temporal join mode for the algebraic materialization"
},
"group_side": {
"type": "string",
"description": "Join side that supplies grouping bucket values"
},
"measure_side": {
"type": "string",
"description": "Join side that supplies metric values"
}
}
},
"Analyses": {
"x-go-type-skip-optional-pointer": false,
"type": "object",
"properties": {
"pca": {
"type": "boolean"
},
"tsne": {
"type": "boolean"
}
}
},
"AntflyRerankerConfig": {
"type": "object",
"description": "Configuration for the Antfly inference reranking provider.",
"properties": {
"provider": {
"type": "string",
"enum": [
"antfly"
]
},
"api_key": {
"type": "string",
"description": "Optional bearer API key for remote Antfly inference. Supports secret references and defaults to ANTFLY_INFERENCE_API_KEY. Embedded inference does not resolve or use outbound credentials."
},
"model": {
"type": "string",
"description": "Optional reranking model name. When omitted, Antfly inference selects a model from its reranker model directory. Set this explicitly when more than one local reranker is installed."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
}
},
"required": [
"provider"
]
},
"AutocompleteQuery": {
"type": "object",
"additionalProperties": false,
"description": "Analyzed bool-prefix search on a logical field. The planner selects\ndeclared search-as-you-type root, shingle and prefix representations.\nRequires a compatible representation; never silently becomes raw prefix search.\n",
"required": [
"autocomplete",
"field"
],
"properties": {
"autocomplete": {
"type": "string"
},
"field": {
"type": "string",
"minLength": 1
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"BoolFieldQuery": {
"type": "object",
"properties": {
"bool": {
"type": "boolean"
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"bool"
]
},
"BoolQuery": {
"type": "object",
"additionalProperties": false,
"required": [
"bool"
],
"description": "Canonical Boolean wrapper. Must clauses score; filter clauses constrain without scoring.",
"properties": {
"bool": {
"$ref": "#/$defs/BoolQueryBody"
}
}
},
"BoolQueryBody": {
"type": "object",
"additionalProperties": false,
"properties": {
"must": {
"$ref": "#/$defs/BoolQueryClause"
},
"should": {
"$ref": "#/$defs/BoolQueryClause"
},
"must_not": {
"$ref": "#/$defs/BoolQueryClause"
},
"filter": {
"$ref": "#/$defs/BoolQueryClause"
},
"minimum_should_match": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Minimum optional clauses required; omission follows the runtime's required-clause defaults."
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"BoolQueryClause": {
"oneOf": [
{
"$ref": "#/$defs/Query"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/Query"
}
}
]
},
"BooleanQuery": {
"type": "object",
"additionalProperties": false,
"properties": {
"must": {
"$ref": "#/$defs/ConjunctionQuery"
},
"should": {
"$ref": "#/$defs/DisjunctionQuery"
},
"must_not": {
"$ref": "#/$defs/DisjunctionQuery"
},
"filter": {
"$ref": "#/$defs/Query"
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"Boost": {
"type": [
"number",
"null"
],
"format": "double",
"description": "A floating-point number used to decrease or increase the relevance scores of a query.",
"default": 1.0
},
"CalendarInterval": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"description": "Calendar-aware interval for date_histogram aggregations"
},
"CardinalityMode": {
"type": "string",
"enum": [
"auto",
"exact",
"approximate"
],
"description": "Exact-vs-approximate selection for a cardinality aggregation:\n- auto: use a materialized HyperLogLog sketch when one applies and is\n current, else an exact distinct scan (default).\n- exact: always compute an exact distinct count.\n- approximate: require a matching sketch; error if none applies.\n"
},
"CatalogTableTarget": {
"type": "object",
"description": "An explicit native table target. Components are literal names; dots do not qualify a string table name.",
"properties": {
"database": {
"type": "string",
"default": "default"
},
"namespace": {
"type": "string",
"default": "public"
},
"table": {
"type": "string"
}
},
"required": [
"table"
],
"additionalProperties": false
},
"CloudflareRerankerConfig": {
"type": "object",
"description": "Cloudflare Workers AI reranking. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
"properties": {
"provider": {
"type": "string",
"enum": [
"cloudflare"
]
},
"account_id": {
"type": "string",
"minLength": 1
},
"gateway_id": {
"type": "string",
"minLength": 1,
"description": "Optional AI Gateway ID, sent through cf-aig-gateway-id."
},
"model": {
"type": "string",
"default": "@cf/baai/bge-reranker-base"
},
"api_key": {
"type": "string",
"writeOnly": true
},
"url": {
"type": "string",
"description": "Optional deployment-owned endpoint override."
}
},
"required": [
"provider",
"account_id",
"model"
]
},
"CohereRerankerConfig": {
"type": "object",
"description": "Configuration for the Cohere reranking provider.\n\nAPI key via `api_key` field or `COHERE_API_KEY` environment variable.\n\n**Example Models:** rerank-english-v3.0 (default), rerank-multilingual-v3.0\n\n**Docs:** https://docs.cohere.com/reference/rerank",
"properties": {
"provider": {
"type": "string",
"enum": [
"cohere"
]
},
"model": {
"type": "string",
"description": "The name of the Cohere reranking model to use.",
"default": "rerank-english-v3.0"
},
"api_key": {
"type": "string",
"description": "The Cohere API key. Can also be set via COHERE_API_KEY environment variable."
}
},
"required": [
"provider"
]
},
"ConjunctionQuery": {
"type": "object",
"properties": {
"conjuncts": {
"type": "array",
"items": {
"$ref": "#/$defs/Query"
}
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"conjuncts"
]
},
"ContainsQuery": {
"type": "object",
"additionalProperties": false,
"description": "Contiguous substring search on the original logical field value, including whitespace and punctuation.\nNo normalization is applied. Case-sensitive by default; case_sensitive=false\nuses Unicode simple case folding, not locale-specific or multi-character folding.\nMissing, null, and non-string values do not match. Arrays use any-element\nsemantics; a match never spans array elements. Indexes select conservative\ncandidates and original values are verified before counting and pagination.\n",
"required": [
"contains",
"field"
],
"properties": {
"contains": {
"type": "string"
},
"field": {
"type": "string",
"minLength": 1,
"description": "Logical source field path, not a companion index name."
},
"case_sensitive": {
"type": "boolean",
"default": true,
"x-go-type-skip-optional-pointer": false
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"DateRangeStringQuery": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "string",
"format": "date-time",
"x-go-type-skip-optional-pointer": false
},
"end": {
"type": "string",
"format": "date-time",
"x-go-type-skip-optional-pointer": false
},
"inclusive_start": {
"type": [
"boolean",
"null"
],
"x-go-type-skip-optional-pointer": false
},
"inclusive_end": {
"type": [
"boolean",
"null"
],
"x-go-type-skip-optional-pointer": false
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
},
"datetime_parser": {
"type": "string"
}
}
},
"DisjunctionQuery": {
"type": "object",
"properties": {
"disjuncts": {
"type": "array",
"items": {
"$ref": "#/$defs/Query"
}
},
"boost": {
"$ref": "#/$defs/Boost"
},
"min": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"x-go-type-skip-optional-pointer": false,
"description": "Minimum number of disjuncts that must match. Omit for conventional disjunction semantics; set to 0 to make a pure disjunction optional."
}
},
"required": [
"disjuncts"
]
},
"DistanceRange": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the distance range bucket"
},
"from": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Minimum distance (inclusive)"
},
"to": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Maximum distance (exclusive)"
}
}
},
"DistanceUnit": {
"type": "string",
"enum": [
"m",
"km",
"mi",
"ft",
"yd"
],
"description": "Distance unit for geo aggregations:\n- m: meters\n- km: kilometers\n- mi: miles\n- ft: feet\n- yd: yards\n"
},
"DocIdQuery": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
}
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"ids"
]
},
"EdgeDirection": {
"x-go-type-skip-optional-pointer": true,
"type": "string",
"enum": [
"out",
"in",
"both"
],
"default": "out",
"description": "Direction of edges to query:\n- out: Outgoing edges from the node\n- in: Incoming edges to the node\n- both: Both outgoing and incoming edges\n"
},
"Embedding": {
"oneOf": [
{
"type": "array",
"items": {
"type": "number",
"format": "float"
},
"description": "Dense embedding as an array of floats, e.g. `[0.1, 0.2, 0.3]`"
},
{
"type": "object",
"required": [
"indices",
"values"
],
"properties": {
"indices": {
"type": "array",
"items": {
"type": "integer",
"x-go-type": "uint32"
}
},
"values": {
"type": "array",
"items": {
"type": "number",
"format": "float"
}
}
},
"description": "Sparse embedding with `indices` and `values` arrays"
},
{
"type": "string",
"format": "byte",
"description": "Packed dense embedding as a base64-encoded string of raw little-endian float32 bytes.\nThis is ~4x more compact than the JSON array format. For example, a 3-dimensional\nvector `[1.0, 2.0, 3.0]` is encoded as base64(12 bytes of little-endian float32s).\n"
},
{
"type": "object",
"required": [
"packed_indices",
"packed_values"
],
"properties": {
"packed_indices": {
"type": "string",
"format": "byte",
"description": "Base64-encoded little-endian uint32 bytes for sparse indices"
},
"packed_values": {
"type": "string",
"format": "byte",
"description": "Base64-encoded little-endian float32 bytes for sparse values"
}
},
"description": "Packed sparse embedding with base64-encoded indices and values.\nSame semantics as the sparse object format but more compact on the wire.\n"
}
]
},
"EqualsQuery": {
"type": "object",
"additionalProperties": false,
"description": "Whole string equality on the original logical field value.\nNo normalization is applied. Case-sensitive by default; case_sensitive=false\nuses Unicode simple case folding, not locale-specific or multi-character folding.\nMissing, null, and non-string values do not match. Arrays use any-element\nsemantics; a match never spans array elements. Indexes select conservative\ncandidates and original values are verified before counting and pagination.\n",
"required": [
"equals",
"field"
],
"properties": {
"equals": {
"type": "string"
},
"field": {
"type": "string",
"minLength": 1,
"description": "Logical source field path, not a companion index name."
},
"case_sensitive": {
"type": "boolean",
"default": true,
"x-go-type-skip-optional-pointer": false
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"ForeignColumn": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name in the foreign table."
},
"type": {
"type": "string",
"description": "Column data type. Used for filter validation and type coercion.\nCommon types: text, integer, bigint, float, boolean, timestamp, uuid, jsonb.\n"
},
"nullable": {
"type": "boolean",
"description": "Whether the column allows NULL values.",
"default": false
}
}
},
"ForeignSource": {
"type": "object",
"required": [
"type",
"dsn",
"postgres_table"
],
"properties": {
"type": {
"type": "string",
"description": "Type of the foreign data source. Currently only \"postgres\" is supported.\n",
"enum": [
"postgres"
]
},
"dsn": {
"type": "string",
"description": "Data source name (connection string) for the foreign database.\nSupports `${secret:key_name}` references that resolve from the Antfly secret store\nor environment variables.\n"
},
"postgres_table": {
"type": "string",
"description": "Name of the table or view in the foreign PostgreSQL database to query.\n"
},
"columns": {
"type": "array",
"items": {
"$ref": "#/$defs/ForeignColumn"
},
"description": "Optional column definitions for the foreign table. If omitted, columns are\nauto-discovered from `information_schema.columns` on first query.\n"
}
}
},
"Fuzziness": {
"description": "The fuzziness of the query. Can be an integer or \"auto\".",
"anyOf": [
{
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 2
},
{
"type": "string",
"enum": [
"auto"
]
}
]
},
"FuzzyQuery": {
"type": "object",
"properties": {
"term": {
"type": "string"
},
"prefix_length": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 255
},
"fuzziness": {
"$ref": "#/$defs/Fuzziness"
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"term"
]
},
"GeoBoundingBoxQuery": {
"type": "object",
"description": "Geographic bounding box filter. The public query shape uses scalar latitude and longitude bounds to match structured filter_query.geo_bbox. Longitude ranges may cross the antimeridian by specifying a western/min longitude that is greater than the eastern/max longitude; for example, min_lon 179.5 and max_lon -179.5 matches points near +/-180 degrees longitude. Latitude bounds must be ordered with min_lat <= max_lat.\n",
"properties": {
"field": {
"type": "string",
"description": "Field or path containing geo_point values."
},
"min_lat": {
"type": "number",
"format": "double",
"minimum": -90,
"maximum": 90,
"description": "Southern latitude bound."
},
"min_lon": {
"type": "number",
"format": "double",
"minimum": -180,
"maximum": 180,
"description": "Western longitude bound. If greater than max_lon, the box crosses the antimeridian."
},
"max_lat": {
"type": "number",
"format": "double",
"minimum": -90,
"maximum": 90,
"description": "Northern latitude bound. Must be greater than or equal to min_lat."
},
"max_lon": {
"type": "number",
"format": "double",
"minimum": -180,
"maximum": 180,
"description": "Eastern longitude bound. May be less than min_lon for antimeridian-wrapped boxes."
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"field",
"min_lat",
"min_lon",
"max_lat",
"max_lon"
]
},
"GeoBoundingPolygonQuery": {
"type": "object",
"properties": {
"polygon_points": {
"type": "array",
"items": {
"$ref": "#/$defs/GeoPoint"
}
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"polygon_points"
]
},
"GeoDistanceQuery": {
"type": "object",
"properties": {
"location": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"minItems": 2,
"maxItems": 2,
"description": "[lon, lat]"
},
"distance": {
"type": "string"
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"location",
"distance"
]
},
"GeoPoint": {
"type": "object",
"properties": {
"lon": {
"type": "number",
"format": "double"
},
"lat": {
"type": "number",
"format": "double"
}
}
},
"GeoShape": {
"type": "object",
"description": "A GeoJSON shape object. This is a simplified representation.",
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": {}
}
},
"required": [
"type",
"coordinates"
]
},
"GeoShapeGeometry": {
"type": "object",
"properties": {
"shape": {
"$ref": "#/$defs/GeoShape"
},
"relation": {
"type": "string",
"enum": [
"intersects",
"contains",
"within"
]
}
},
"required": [
"shape",
"relation"
]
},
"GeoShapeQuery": {
"type": "object",
"properties": {
"geometry": {
"$ref": "#/$defs/GeoShapeGeometry"
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"geometry"
]
},
"GraphAggregatesReturn": {
"type": "object",
"additionalProperties": false,
"required": [
"aggregates"
],
"properties": {
"aggregates": {
"type": "object",
"minProperties": 1,
"maxProperties": 64,
"additionalProperties": {
# --- truncated at 32 KB (182 KB total) ---
# Full source: https://artifacts.apis.io/antfly/json-schema/antfly-stateful-query-request-schema.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/antfly-stateful-query-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.