Ask a question to an existing dataset | Dadosfera AutoDriveDDF API

Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

Description

Submit a natural-language question that AutoDriveDDF will answer using the specified dataset as context.
Ideal for ad-hoc insight, non-technical users, or exploratory analysis where you’d rather “ask” than write SQL.

For small datasets or simple prompts, the API may answer synchronously.
For larger datasets or more complex questions, the request is queued for background processing. You receive a question_id and poll the GET endpoint to retrieve the answer later.

HTTP Request

POST /dataset/{dataset_id}/ai_question

No query parameters; the dataset is identified by the path.

Authentication

In your REST client (Postman/Insomnia), select Basic Auth and enter your Username and Password.

The client will automatically generate the Authorization: Basic … header for you. Do not add that header manually.

Request Headers

Header	Example	Required	Notes
Authorization	`Basic YWRtaW46bXlwYXNzd29yZA==`	✓	HTTP Basic Auth – always use HTTPS.
Content-Type	`application/json`	✓	Indicates a JSON payload.
Accept	`application/json`	—	Ensures JSON response.

Path Parameters

Location	Name	Type	Required	Description
Path	`dataset_id`	string	✓	UUID of the dataset created earlier, e.g. `c8004e22-87f7-441f-8302-80c934841196`.

Request Body

Field	Type	Required	Description
`question`	string	✓	The natural-language question you want answered, e.g. `"What were the total sales in Q1?"`. Maximum 1000 characters.
`fetch_k`	integer	✓	Number of top documents to retrieve initially (e.g. `250`). The system ranks these and then selects the next `k` documents for answer synthesis.
`k`	integer	✓	Number of documents (from the initial `fetch_k`) to actually pass to the model for an answer (e.g. `100`).
`model`	string	✓	The AI model identifier to use, e.g. `"gemini-2.5-flash-preview-04-17"`.

Note: Higher fetch_k and k values can improve answer quality at the expense of longer processing time. If omitted, the server may apply sensible defaults (check your environment’s configuration).

Example Request Body (JSON)

{
  "question": "Why do some pipeline jobs fail intermittently?",
  "fetch_k": 250,
  "k": 100,
  "model": "gemini-2.5-flash-preview-04-17"
}

Example Request (cURL)

curl -u admin:mypassword \
     -H "Content-Type: application/json" \
     -d '{
           "question": "Why do some pipeline jobs fail intermittently?",
           "fetch_k": 250,
           "k": 100,
           "model": "gemini-2.5-flash-preview-04-17"
         }' \
     https://api.autodriveddf.example/dataset/c8004e22-87f7-441f-8302-80c934841196/ai_question

Success Response `200 OK` (Asynchronous)

{
  "dataset_id": "c8004e22-87f7-441f-8302-80c934841196",
  "question_id": "04534356-9ee0-431d-8b6e-74c2eed261c2",
}

Field	Description
`dataset_id`	UUID of the dataset queried.
`question_id`	Unique UUID for this question instance (use it to poll for the answer).

Notes on Usage

Synchronous vs Asynchronous:
- For small datasets, the API may return a complete answer in a single POST response (status 200 OK with answer).
- For larger datasets, you will receive a question_id immediately and must poll the GET endpoint until status = "completed".
Rate Limits:
AI-powered questions may count against a separate rate limit. Expect slower throughput than simple document retrieval calls.
Parameter Tuning:
- A larger fetch_k retrieves more context but takes longer.
- A larger k provides more context to the model, potentially improving accuracy at the cost of latency.
Language:
The answer’s language matches the question’s language. Non-English questions will yield non-English answers, provided the underlying model supports that language.

Next Steps
Once you receive a completed answer, you can:

Analyze the returned snippets to verify facts.
Use the answer text in your application or dashboard.
Ask follow-up questions by re-using the same dataset_id.
If you want only relevant documents (no AI answer), use
POST /dataset/{dataset_id}/question → GET /dataset/{dataset_id}/question/{question_id} instead.

This field can be used to filter documents using the metadata of the documents. Example: metadata_filter={"source": "file.txt"} In this scenario, before selecting the documents, the following filter would be routerlied to the dataset.

Distance Metric in Embedding Distances In the realm of embeddings, where data points are represented as vectors in a continuous space, a distance metric quantifies the similarity or dissimilarity between these vectors. It allows us to gauge how close or far apart two embeddings are, helping capture semantic or contextual relationships. Available metrics: - "L2": "Euclidean Distance" - "L1": "Nuclear distance" - "max": "L-infinity" - "cos": "Cosine" - "dot": "dot product"

Whether to use MMR (Maximal Marginal Relevance) in the selection of documents to retrieve. MMR is an algorithm commonly used in information retrieval and text summarization. Its primary goal is to balance relevance and diversity. When retrieving or summarizing documents, MMR ensures that the selected items are not only relevant to the query or topic but also diverse enough to provide comprehensive information. This prevents redundancy and offers a broader perspective on the topic.