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
View JSON Schema on GitHub

JSON Schema

antfly-stateful-query-request-schema.json Raw ↑
{
  "$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.
All 92 tools →

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.