:doc:`QConnect <../../qconnect>` / Client / retrieve

********
retrieve
********



.. py:method:: QConnect.Client.retrieve(**kwargs)

  

  Retrieves content from knowledge sources based on a query.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/qconnect-2020-10-19/Retrieve>`_  


  **Request Syntax**
  ::

    response = client.retrieve(
        assistantId='string',
        retrievalConfiguration={
            'knowledgeSource': {
                'assistantAssociationIds': [
                    'string',
                ]
            },
            'filter': {
                'andAll': [
                    {'... recursive ...'},
                ],
                'equals': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'greaterThan': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'greaterThanOrEquals': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'in': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'lessThan': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'lessThanOrEquals': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'listContains': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'notEquals': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'notIn': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'orAll': [
                    {'... recursive ...'},
                ],
                'startsWith': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                },
                'stringContains': {
                    'key': 'string',
                    'value': {...}|[...]|123|123.4|'string'|True|None
                }
            },
            'numberOfResults': 123,
            'overrideKnowledgeBaseSearchType': 'HYBRID'|'SEMANTIC'
        },
        retrievalQuery='string'
    )
    
  :type assistantId: string
  :param assistantId: **[REQUIRED]** 

    The identifier of the Amazon Q in Connect assistant for content retrieval.

    

  
  :type retrievalConfiguration: dict
  :param retrievalConfiguration: **[REQUIRED]** 

    The configuration for the content retrieval operation.

    

  
    - **knowledgeSource** *(dict) --* **[REQUIRED]** 

      The knowledge source configuration for content retrieval.

      .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``assistantAssociationIds``. 

    
      - **assistantAssociationIds** *(list) --* 

        The list of assistant association identifiers for the knowledge source.

        

      
        - *(string) --* 

        
    
    
    - **filter** *(dict) --* 

      The filter configuration for content retrieval.

      .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``andAll``, ``equals``, ``greaterThan``, ``greaterThanOrEquals``, ``in``, ``lessThan``, ``lessThanOrEquals``, ``listContains``, ``notEquals``, ``notIn``, ``orAll``, ``startsWith``, ``stringContains``. 

    
      - **andAll** *(list) --* 

        Filter configuration that requires all conditions to be met.

        

      
        - *(dict) --* 

          Configuration for filtering content during retrieval operations.

          .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``andAll``, ``equals``, ``greaterThan``, ``greaterThanOrEquals``, ``in``, ``lessThan``, ``lessThanOrEquals``, ``listContains``, ``notEquals``, ``notIn``, ``orAll``, ``startsWith``, ``stringContains``. 

        
    
      - **equals** *(dict) --* 

        Filter configuration for exact equality matching.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **greaterThan** *(dict) --* 

        Filter configuration for greater than comparison.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **greaterThanOrEquals** *(dict) --* 

        Filter configuration for greater than or equal comparison.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **in** *(dict) --* 

        Filter configuration for membership in a set of values.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **lessThan** *(dict) --* 

        Filter configuration for less than comparison.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **lessThanOrEquals** *(dict) --* 

        Filter configuration for less than or equal comparison.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **listContains** *(dict) --* 

        Filter configuration for checking if a list contains a value.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **notEquals** *(dict) --* 

        Filter configuration for inequality matching.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **notIn** *(dict) --* 

        Filter configuration for exclusion from a set of values.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **orAll** *(list) --* 

        Filter configuration where any condition can be met.

        

      
        - *(dict) --* 

          Configuration for filtering content during retrieval operations.

          .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``andAll``, ``equals``, ``greaterThan``, ``greaterThanOrEquals``, ``in``, ``lessThan``, ``lessThanOrEquals``, ``listContains``, ``notEquals``, ``notIn``, ``orAll``, ``startsWith``, ``stringContains``. 

        
    
      - **startsWith** *(dict) --* 

        Filter configuration for prefix matching.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
      - **stringContains** *(dict) --* 

        Filter configuration for substring matching.

        

      
        - **key** *(string) --* **[REQUIRED]** 

          The key of the filter attribute.

          

        
        - **value** (:ref:`document<document>`) -- **[REQUIRED]** 

          The value of the filter attribute.

          

        
      
    
    - **numberOfResults** *(integer) --* 

      The number of results to retrieve.

      

    
    - **overrideKnowledgeBaseSearchType** *(string) --* 

      Override setting for the knowledge base search type during retrieval.

      

    
  
  :type retrievalQuery: string
  :param retrievalQuery: **[REQUIRED]** 

    The query for content retrieval.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'results': [
              {
                  'associationId': 'string',
                  'sourceId': 'string',
                  'referenceType': 'WEB_CRAWLER'|'KNOWLEDGE_BASE'|'BEDROCK_KB_S3'|'BEDROCK_KB_WEB'|'BEDROCK_KB_CONFLUENCE'|'BEDROCK_KB_SALESFORCE'|'BEDROCK_KB_SHAREPOINT'|'BEDROCK_KB_KENDRA'|'BEDROCK_KB_CUSTOM_DOCUMENT'|'BEDROCK_KB_SQL',
                  'contentText': 'string'
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **results** *(list) --* 

        The results of the content retrieval operation.

        
        

        - *(dict) --* 

          A single result from a content retrieval operation.

          
          

          - **associationId** *(string) --* 

            The identifier of the assistant association for the retrieved result.

            
          

          - **sourceId** *(string) --* 

            The URL, URI, or ID of the retrieved content when available, or a UUID when unavailable.

            
          

          - **referenceType** *(string) --* 

            A type to define the KB origin of a retrieved content.

            
          

          - **contentText** *(string) --* 

            The text content of the retrieved result.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`QConnect.Client.exceptions.RequestTimeoutException`

  
  *   :py:class:`QConnect.Client.exceptions.ValidationException`

  
  *   :py:class:`QConnect.Client.exceptions.ConflictException`

  
  *   :py:class:`QConnect.Client.exceptions.ServiceQuotaExceededException`

  
  *   :py:class:`QConnect.Client.exceptions.DependencyFailedException`

  
  *   :py:class:`QConnect.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`QConnect.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`QConnect.Client.exceptions.ThrottlingException`

  