QConnect / Client / retrieve

retrieve¶

QConnect.Client.retrieve(**kwargs)¶

Retrieves content from knowledge sources based on a query.

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'
)

Parameters:

assistantId (string) –
[REQUIRED]

The identifier of the Amazon Q in Connect assistant for content retrieval.
retrievalConfiguration (dict) –
[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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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.
retrievalQuery (string) –
[REQUIRED]

The query for content retrieval.

Return type:

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'
        },
    ],
    'errors': [
        {
            'associationId': 'string',
            'code': 'ACCESS_DENIED'|'RESOURCE_NOT_FOUND'|'VALIDATION_ERROR'|'THROTTLED'|'DEPENDENCY_FAILED'|'INTERNAL_SERVER_ERROR',
            'message': '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.
- errors (list) –
  
  The per-association errors returned when one or more knowledge base associations fail during a Retrieve operation that spans multiple assistant associations. The overall operation still succeeds and returns the results from the associations that were queried successfully. This list contains one entry for each association that failed, up to a maximum of five.
  - (dict) –
    
    An error returned for a single assistant association whose knowledge base retrieval failed during a Retrieve operation. The overall operation still succeeds and returns the results from the associations that were queried successfully.
    - associationId (string) –
      
      The identifier of the assistant association whose knowledge base retrieval failed.
    - code (string) –
      
      The error code that categorizes the retrieval failure for the assistant association.
    - message (string) –
      
      A human-readable description of the retrieval failure for the assistant association.

Exceptions

QConnect.Client.exceptions.RequestTimeoutException
QConnect.Client.exceptions.ValidationException
QConnect.Client.exceptions.ConflictException
QConnect.Client.exceptions.ServiceQuotaExceededException
QConnect.Client.exceptions.DependencyFailedException
QConnect.Client.exceptions.AccessDeniedException
QConnect.Client.exceptions.ResourceNotFoundException
QConnect.Client.exceptions.ThrottlingException