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

# Query

> Documentation for how to call the Query APIs using the Aryn SDK

Please find the documentation for the functions that call the Query APIs using the SDK below. All parameters are optional unless specified otherwise.

## Search

Search over a docset and get back documents or elements that match your search criteria.

<AccordionGroup>
  <Accordion title="Parameters">
    * `docset_id`: A string specifying the id of the docset you are searching over.
    * `query`: A string that specifies what term you are searching for within the contents of your documents. The query\_type parameter specified below will control exactly how this query parameter is used to search over your documents.
    * `query_type`: An enum that can be either `keyword`, `vector`, or `lexical`:
      * When `keyword` is specified, the search call will perform a substring match and return results that contain strings that contain the query term specified.
      * When `vector` is specified, the search call will internally embed the query with the embedding function associated with the docset you are querying on and perform a k-nearest neighbor search to retrieve the results.
      * When `lexical` is specified, the search call will perform an exact string match and return results where the query string shows up as a standalone word.
    * `properties_filter`: A string that specifies a boolean expression. This expression specifies the condition to use when extracting documents or elements from the docset. The boolean expression is a string consisting of conditions separated by the AND keywords. The following are a few examples:
      * `(properties.entity.company_name="Microsoft") AND (properties.entity.year="2024")`
      * `(properties.entity.company_ticker="AMZN") AND (properties.entity.year="2023") AND (properties.entity.quarter="Q2")`
    * `k`: The number of records to return back.
    * `return_type`: An enum that an be either `doc` or `element`. When `doc` is specified, documents that match the search criteria are retuned. When `element` is specified, specific sections of the document (i.e. elements) are returned.
    * `page_token`:   A string used for pagination purposes. If provided, this will indicate to the server where to begin the next set of records to return. Valid for 24 hours.
  </Accordion>

  <Accordion title="Example">
    ```python theme={null}
    from aryn_sdk.client import Client
    from aryn_sdk.types.search import SearchRequest

    myClient = Client()
    client_response = myClient.search(
        docset_id="aryn:ds-031ppkfhkzq42baiunmr8yh",
        query=SearchRequest(
            query="weather",
            properties_filter="""(properties.entity.aircraft like "Cessna") and (properties.entity.operator <> "n/a") and (properties.entity.lowestCloudCondition = "Clear")""",
            query_type="hybrid",
            return_type="element",
        ),
    )

    search_results = client_response.value.results

    for result in search_results:
        print(result)
    ```
  </Accordion>

  <Accordion title="Return Value">
    A SearchResponse object which contains the following attributes:

    * `results`: A list containing either the documents or elements that matched the search criteria.
    * `query_embedding`: If the query\_type selected is 'vector', this field indicates the embedding vector that was used to perform the search.
    * `next_page_token`: The pagination token. If None, there are no more search results to retrieve. If not None, the caller may use this to retrieve more results for the particular search query.
  </Accordion>

  <Accordion title="Exceptions">
    User errors:

    * `HTTPError: Error:status_code 403`. Reason: `"No Aryn API Key provided"`
      * Fix: Please provide an API key either as a parameter or specify it in the environment variable `ARYN_API_KEY`.
    * `HTTPError: Error:status_code 403`. Reason: `"Invalid Aryn API key"`
      * Fix: Please provide a valid API key either as a parameter or specify it in the environment variable `ARYN_API_KEY`.
    * `HTTPError: Error:status_code 403`. Reason: `"Expired Aryn API key"`
      * Fix: Please get a new API key [here](https://console.aryn.ai/api-keys).
    * `HTTPError: Error:status_code 404`. Reason: `"Docset not found error"`
      * Fix: Please try again with a valid docset id.
    * `HTTPError: Error:status_code 400`. Reason: `"Incorrect input"`
      * Fix: Please try again with correct input.

    Other errors:

    * `HTTPError: Error:status_code 5xx`. Reason: `Internal Server Error`
  </Accordion>
</AccordionGroup>

## Generate Plan

Generate a query plan for the given query, but do not run it.

<AccordionGroup>
  <Accordion title="Parameters">
    <ParamField path="query" type="Query" required>
      A `Query` object describing the query to build and return a `LogicalPlan` for.
    </ParamField>
  </Accordion>

  <Accordion title="Example">
    ```python theme={null}
    from aryn_sdk.client.client import Client, generate_plan, Query
    c = Client()
    c.generate_plan(query=Query(
        docset_id="aryn:ds-u3915kxzdi8fosmv542ynv4",
        query="What was the breakdown of aircraft types for incidents with substantial damage?"
    ))
    ```
  </Accordion>

  <Accordion title="Return Value">
    A `LogicalPlan` object.
  </Accordion>

  <Accordion title="Exceptions">
    * `HTTPError 403`: "No Aryn API Key provided"
    * `HTTPError 403`: "Invalid Aryn API key"
    * `HTTPError 403`: "Expired Aryn API key"
    * `HTTPError 5xx`: Internal Server Error
  </Accordion>
</AccordionGroup>

## Edit Plan

Edit a plan.

<AccordionGroup>
  <Accordion title="Parameters">
    <ParamField path="query" type="Query" required>The query to edit.</ParamField>
    <ParamField path="feedback" type="string" required>The changes to the plan you would like.</ParamField>
  </Accordion>

  <Accordion title="Example">
    ```python theme={null}
    from aryn_sdk.client.client import Client, edit_plan
    c = Client()
    c.edit_plan(query=myQuery, feedback="Add a filter to select just documents that mention inflation.")
    ```
  </Accordion>

  <Accordion title="Return Value">
    A `LogicalPlan` object.
  </Accordion>

  <Accordion title="Exceptions">
    * `HTTPError 403`: "No Aryn API Key provided"
    * `HTTPError 403`: "Invalid Aryn API key"
    * `HTTPError 403`: "Expired Aryn API key"
    * `HTTPError 5xx`: Internal Server Error
  </Accordion>
</AccordionGroup>

## Query

Run a query either from a `Query` based on a string or a `Query` based on a plan.

<AccordionGroup>
  <Accordion title="Parameters">
    <ParamField path="query" type="Query" required>The query to run.</ParamField>
  </Accordion>

  <Accordion title="Example">
    ```python theme={null}
    from aryn_sdk.client.client import Client, Query
    c = Client()
    docset_id = None # my docset id

    # Do RAG on the documents
    results = c.query(query=Query(docset_id=docset_id, query="test_query", stream=True, rag_mode=True))

    # Do Deep Analytics which involves generating a logical plan and running it on the documents
    results = c.query(query=Query(docset_id=docset_id, query="test_query", stream=True))
    ```
  </Accordion>

  <Accordion title="Return Value">
    Either a `QueryResult` or an `Iterator[QueryEvent]`.
  </Accordion>

  <Accordion title="Exceptions">
    * `HTTPError 403`: "No Aryn API Key provided"
    * `HTTPError 403`: "Invalid Aryn API key"
    * `HTTPError 403`: "Expired Aryn API key"
    * `HTTPError 5xx`: Internal Server Error
  </Accordion>
</AccordionGroup>

## Client Options

<AccordionGroup>
  <Accordion title="Parameters">
    * `region`: A string that specifies the region to use for the DocParse server. Valid values are `US` and `None`. Default is `None`.
    * `timeout`: A float that specifies the timeout in seconds for the client. Default is `240.0`.
  </Accordion>

  <Accordion title="Example">
    ```python theme={null}
    from aryn_sdk.client import Client
    client = Client(region="US", timeout=240.0)
    ```
  </Accordion>
</AccordionGroup>