> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3ntrop1a.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Process Query

> Process a user query and return an LLM-generated response

# Process Query

Main endpoint for querying the RAG system. Performs semantic search in your documents and generates an intelligent response based on the found context.

## Endpoint

```
POST /query
```

## Request Body

<ParamField body="query" type="string" required>
  The user's question or query
</ParamField>

<ParamField body="collection_id" type="string">
  ID of the collection to query (default: all collections)
</ParamField>

<ParamField body="max_results" type="integer" default="5">
  Maximum number of source documents to retrieve (1-20)
</ParamField>

<ParamField body="use_llm" type="boolean" default="true">
  Use the LLM to generate a response. If false, returns only relevant sources.
</ParamField>

<ParamField body="metadata_filter" type="object">
  Metadata filters to refine the search

  ```json theme={null}
  {
    "document_type": "pdf",
    "category": "finance"
  }
  ```
</ParamField>

## Response

<ResponseField name="query_id" type="string">
  Unique query identifier
</ResponseField>

<ResponseField name="answer" type="string">
  Response generated by the LLM (null if use\_llm=false)
</ResponseField>

<ResponseField name="sources" type="array">
  List of source documents used

  <Expandable title="properties">
    <ResponseField name="document_id" type="string">
      Source document ID
    </ResponseField>

    <ResponseField name="filename" type="string">
      Source file name
    </ResponseField>

    <ResponseField name="chunk_index" type="integer">
      Chunk index in the document
    </ResponseField>

    <ResponseField name="relevance_score" type="float">
      Relevance score (0-1)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution_time_ms" type="integer">
  Execution time in milliseconds
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 query timestamp
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8000/query \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What is the refund policy?",
      "max_results": 3,
      "use_llm": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "http://localhost:8000/query",
      json={
          "query": "What is the refund policy?",
          "max_results": 3,
          "use_llm": True
      }
  )

  result = response.json()
  print(result["answer"])
  for source in result["sources"]:
      print(f"Source: {source['filename']} (score: {source['relevance_score']})")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8000/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'What is the refund policy?',
      max_results: 3,
      use_llm: true
    })
  });

  const result = await response.json();
  console.log(result.answer);
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "query_id": "123e4567-e89b-12d3-a456-426614174000",
    "answer": "According to our documents, the refund policy allows returns within 30 days for all unused products. Refunds are processed within 7 business days to the original payment method. Return shipping costs are the customer's responsibility except for defective products.",
    "sources": [
      {
        "document_id": "doc-123",
        "filename": "refund_policy.pdf",
        "chunk_index": 2,
        "relevance_score": 0.94
      },
      {
        "document_id": "doc-456",
        "filename": "terms_conditions.pdf",
        "chunk_index": 8,
        "relevance_score": 0.87
      },
      {
        "document_id": "doc-123",
        "filename": "refund_policy.pdf",
        "chunk_index": 3,
        "relevance_score": 0.82
      }
    ],
    "execution_time_ms": 1234,
    "timestamp": "2024-02-17T10:30:45.123Z"
  }
  ```

  ```json Without LLM (use_llm=false) theme={null}
  {
    "query_id": "123e4567-e89b-12d3-a456-426614174001",
    "answer": null,
    "sources": [
      {
        "document_id": "doc-123",
        "filename": "refund_policy.pdf",
        "chunk_index": 2,
        "relevance_score": 0.94
      }
    ],
    "execution_time_ms": 234,
    "timestamp": "2024-02-17T10:31:12.456Z"
  }
  ```

  ```json No Results theme={null}
  {
    "query_id": "123e4567-e89b-12d3-a456-426614174002",
    "answer": "I could not find relevant documents to answer your question.",
    "sources": [],
    "execution_time_ms": 456,
    "timestamp": "2024-02-17T10:32:00.789Z"
  }
  ```
</ResponseExample>

## Error Codes

<ResponseField name="400" type="Bad Request">
  Invalid request (missing or incorrect parameters)
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error (LLM unavailable, processing error)
</ResponseField>

<ResponseField name="504" type="Gateway Timeout">
  Request timeout (>60 seconds)
</ResponseField>

## Best Practices

<AccordionGroup>
  <Accordion title="Optimize Performance">
    * Adjust `max_results` according to your needs (less = faster)
    * Use `use_llm=false` for pure search without generation
    * Add metadata filters to refine the search
  </Accordion>

  <Accordion title="Improve Answer Quality">
    * Formulate clear and precise questions
    * Use terms specific to your domain
    * Increase `max_results` for more context (5-10)
  </Accordion>

  <Accordion title="Use Metadata Filters">
    ```json theme={null}
    {
      "query": "What is the procedure?",
      "metadata_filter": {
        "department": "HR",
        "year": "2024"
      }
    }
    ```
  </Accordion>

  <Accordion title="Handle Errors">
    ```python theme={null}
    try:
        response = requests.post(url, json=data, timeout=60)
        response.raise_for_status()
        result = response.json()
    except requests.Timeout:
        print("The request took too long")
    except requests.HTTPError as e:
        print(f"HTTP Error: {e}")
    ```
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  * **Timeout:** 60 seconds maximum per query
  * **Query length:** 1000 characters maximum
  * **LLM context:** Limited by model's context window (\~2048-4096 tokens)
</Warning>

## Technical Notes

### Search Process

1. **Query embedding**: Conversion to vector (384 dimensions)
2. **Vector search**: K-nearest neighbors search in Qdrant (cosine similarity)
3. **Filtering**: Application of metadata filters if provided
4. **Relevance threshold**: Only results with score > 0.7 are kept
5. **Content retrieval**: Getting full text of chunks
6. **LLM generation**: Prompt construction and response generation

### LLM Prompt Format

```
Provided context:
Document 1:
[Most relevant chunk content]

Document 2:
[2nd chunk content]

...

Question: [Your question]

Answer the question based ONLY on the context provided above.
If the context does not contain enough information to answer, say so clearly.
Cite the document numbers you use in your answer.
```

## See Also

<CardGroup cols={2}>
  <Card title="Upload Documents" icon="file-upload" href="/api-reference/documents/upload">
    Add documents to the system
  </Card>

  <Card title="Collections" icon="folder" href="/guides/collections">
    Organize your documents
  </Card>
</CardGroup>