# Antfly Query Operations API

**Canonical:** https://apis.io/apis/antfly/antfly-query-operations-api/  
**Provider:** Antfly — https://apis.io/providers/antfly/  
**Base URL:** https://api.antfly.io  
**Documentation:** https://antfly.io/docs/api

Antfly Query Operations API is one of 20 APIs that [Antfly](https://apis.io/providers/antfly/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include query_operations. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

Execute queries across tables using full-text search, vector similarity search, or hybrid approaches combining both with Reciprocal Rank Fusion (RRF). ## Query Types ### Full-Text Search Uses Antfly query syntax for powerful text searching: - Field-specific queries: `body:computer` - Boolean operators: `AND`, `OR`, `NOT` - Range queries: `year:>2020` - Phrase queries: `"exact phrase"` ### Semantic Search Natural language queries using vector similarity: - Searches across specified embedding indexes - Returns semantically similar documents - Supports multiple embedding models ### Hybrid Search (RRF) Combines full-text and semantic search using Reciprocal Rank Fusion: ```json { "full_text_search": {"query": "body:computer"}, "semantic_search": "artificial intelligence", "indexes": ["title_body_nomic"] } ``` ## Filtering and Exclusion Refine results with powerful filtering: ### Filter Prefix Only return documents whose keys start with a specific string: ```json {"filter_prefix": "user:"} ``` Returns only keys like "user:123", "user:456" ### Filter Query Apply an Antfly query as an AND condition: ```json {"filter_query": {"query": "+category:technology +year:>2020"}} ``` Documents must match both the main query and filter query. ### Exclusion Query Exclude documents matching an Antfly query (NOT condition): ```json {"exclusion_query": {"query": "category:deprecated OR status:archived"}} ``` **Performance Note**: All filters are applied before scoring and ranking, improving query performance. ## RAG (Retrieval-Augmented Generation) Execute queries and generate summaries using LLMs: - Supports multiple retrieval queries - Streams results as Server-Sent Events (SSE) - Returns markdown summaries with inline citations - Combines results from multiple tables ## Retrieval Agent Intelligent query routing with automatic query generation: - Classifies queries as "question" or "search" - Generates optimal search queries across tables - Returns generated responses (for questions) or document IDs (for searches) - Streams classification, keywords, queries, and results ## Improving Search Relevance Antfly provides several techniques to improve search result quality: ### 1. Hybrid Search (Combine Full-Text + Semantic) Use both `full_text_search` and `semantic_search` together. Results are merged using Reciprocal Rank Fusion (RRF) to balance keyword matching and semantic similarity. ### 2. Reranking Apply a cross-encoder model to re-score results based on query-document relevance. Rerankers are more accurate than embedding models but slower, so use them on already-filtered results (e.g., top 50-100). ```json { "semantic_search": "gaming laptops", "limit": 10, "reranker": { "provider": "antfly", "model": "mixedbread-ai/mxbai-rerank-base-v1", "field": "description", "candidate_count": 100 } } ``` ### 3. Result Pruning Filter out low-quality results by detecting score gaps or setting minimum thresholds: ```json { "semantic_search": "machine learning", "pruner": { "min_score_ratio": 0.5, "max_score_gap_percent": 30.0 } } ``` - `min_score_ratio`: Keep only results scoring at least X% of the top result - `max_score_gap_percent`: Stop when a consecutive score gap exceeds X% of the total score range ### 4. Merge Strategies Choose how full-text and semantic results are combined: - `rrf` (default): Reciprocal Rank Fusion - balanced, works well in most cases - `rsf`: Relative Score Fusion - normalizes and weights scores differently ### 5. Query Filtering Use `filter_query` and `filter_prefix` to pre-filter before scoring, improving both performance and relevance by removing irrelevant documents early. **Best Practice**: Combine techniques for optimal results: 1. Start with hybrid search (full-text + semantic) 2. Apply filters to narrow the domain 3. Use reranker on top results 4. Apply pruner to remove outliers

## Operations (11)

| Method | Path | Summary |
|---|---|---|
| POST | `/db/v1/query` | Perform a global query |
| POST | `/db/v1/eval` | Standalone evaluation endpoint |
| POST | `/db/v1/agents/query-builder` | Build a search query from natural language |
| POST | `/db/v1/agents/retrieval` | Retrieval Agent - Agentic document retrieval with tool calling |
| POST | `/db/v1/agents/research` | Research Agent - Bounded multi-phase research with a cited report |
| POST | `/db/v1/agents/research/jobs` | Start a durable research job |
| GET | `/db/v1/agents/research/jobs/{jobId}` | Get a durable research job |
| POST | `/db/v1/agents/research/jobs/{jobId}/advance` | Advance a durable research job |
| POST | `/db/v1/agents/research/jobs/{jobId}/cancel` | Cancel a durable research job |
| POST | `/db/v1/tables/{tableName}/query` | Query a specific table |
| POST | `/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query` | Query an explicit namespace table |

## Machine-readable artifacts (7)

- **OpenAPI** — https://artifacts.apis.io/antfly/openapi/antfly-query-operations-api-openapi.yml
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-recall-result-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-inspection-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-record-page-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-record-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-memory-relationship-proposal-schema.json
- **JSONSchema** — https://artifacts.apis.io/antfly/json-schema/antfly-inference-generate-request-schema.json

## Other Antfly APIs (12)

- [Antfly AI API](https://apis.io/apis/antfly/antfly-ai-api/)
- [Antfly Cluster Management API](https://apis.io/apis/antfly/antfly-cluster-management-api/)
- [Antfly Data Operations API](https://apis.io/apis/antfly/antfly-data-operations-api/)
- [Antfly Documents API](https://apis.io/apis/antfly/antfly-documents-api/)
- [Antfly Index Management API](https://apis.io/apis/antfly/antfly-index-management-api/)
- [Antfly Inference API](https://apis.io/apis/antfly/antfly-inference-api/)
- [Antfly Installed API](https://apis.io/apis/antfly/antfly-installed-api/)
- [Antfly Memory API](https://apis.io/apis/antfly/antfly-memory-api/)
- [Antfly Ml API](https://apis.io/apis/antfly/antfly-ml-api/)
- [Antfly Models API](https://apis.io/apis/antfly/antfly-models-api/)
- [Antfly Packages API](https://apis.io/apis/antfly/antfly-packages-api/)
- [Antfly Permission API](https://apis.io/apis/antfly/antfly-permission-api/)

## Tags

query_operations

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/antfly/antfly-query-operations-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/antfly/.