DataZone / Client / search_listings

search_listings¶

DataZone.Client.search_listings(**kwargs)¶

Searches listings in Amazon DataZone.

SearchListings is a powerful capability that enables users to discover and explore published assets and data products across their organization. It provides both basic and advanced search functionality, allowing users to find resources based on names, descriptions, metadata, and other attributes. SearchListings also supports filtering using various criteria such as creation date, owner, or status. This API is essential for making the wealth of data resources in an organization discoverable and usable, helping users find the right data for their needs quickly and efficiently.

SearchListings returns results in a paginated format. When the result set is large, the response will include a nextToken, which can be used to retrieve the next page of results.

The SearchListings API gives users flexibility in specifying what kind of search is run.

To run a free-text search, the searchText parameter must be supplied. By default, all searchable fields are indexed for semantic search and will return semantic matches for SearchListings queries. To prevent semantic search indexing for a custom form attribute, see the CreateFormType API documentation. To run a lexical search query, enclose the query with double quotes (“”). This will disable semantic search even for fields that have semantic search enabled and will only return results that contain the keywords wrapped by double quotes (order of tokens in the query is not enforced). Free-text search is supported for all attributes annotated with @amazon.datazone#searchable.

To run a filtered search, provide filter clause using the filters parameter. To filter on glossary terms, use the special attribute __DataZoneGlossaryTerms.

To find out whether an attribute has been annotated and indexed for a given search type, use the GetFormType API to retrieve the form containing the attribute.

Request Syntax

response = client.search_listings(
    additionalAttributes=[
        'FORMS'|'TIME_SERIES_DATA_POINT_FORMS'|'TEXT_MATCH_RATIONALE',
    ],
    aggregations=[
        {
            'attribute': 'string',
            'displayValue': 'string'
        },
    ],
    domainIdentifier='string',
    filters={
        'and': [
            {'... recursive ...'},
        ],
        'filter': {
            'attribute': 'string',
            'value': 'string'
        },
        'or': [
            {'... recursive ...'},
        ]
    },
    maxResults=123,
    nextToken='string',
    searchIn=[
        {
            'attribute': 'string'
        },
    ],
    searchText='string',
    sort={
        'attribute': 'string',
        'order': 'ASCENDING'|'DESCENDING'
    }
)

Parameters:

additionalAttributes (list) –
Specifies additional attributes for the search.
- (string) –
aggregations (list) –
Enables you to specify one or more attributes to compute and return counts grouped by field values.
- (dict) –
  
  An aggregation list item.
  - attribute (string) – [REQUIRED]
    
    An attribute on which to compute aggregations.
  - displayValue (string) –
    
    The display value of the aggregation list item. Supported values include value and glossaryTerm.name.
domainIdentifier (string) –
[REQUIRED]

The identifier of the domain in which to search listings.
filters (dict) –
Specifies the filters for the search of listings.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: and, filter, or.
- and (list) –
  
  The ‘and’ search filter clause in Amazon DataZone.
  - (dict) –
    
    A search filter clause in Amazon DataZone.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: and, filter, or.
- filter (dict) –
  
  A search filter in Amazon DataZone.
  - attribute (string) – [REQUIRED]
    
    A search filter attribute in Amazon DataZone.
  - value (string) – [REQUIRED]
    
    A search filter value in Amazon DataZone.
- or (list) –
  
  The ‘or’ search filter clause in Amazon DataZone.
  - (dict) –
    
    A search filter clause in Amazon DataZone.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: and, filter, or.
maxResults (integer) – The maximum number of results to return in a single call to SearchListings. When the number of results to be listed is greater than the value of MaxResults, the response contains a NextToken value that you can use in a subsequent call to SearchListings to list the next set of results.
nextToken (string) – When the number of results is greater than the default value for the MaxResults parameter, or if you explicitly specify a value for MaxResults that is less than the number of results, the response includes a pagination token named NextToken. You can specify this NextToken value in a subsequent call to SearchListings to list the next set of results.
searchIn (list) –
The details of the search.
- (dict) –
  
  The details of the search.
  - attribute (string) – [REQUIRED]
    
    The search attribute.
searchText (string) – Specifies the text for which to search.
sort (dict) –
Specifies the way for sorting the search results.
- attribute (string) – [REQUIRED]
  
  The attribute detail of the way to sort search results.
- order (string) –
  
  The order detail of the wya to sort search results.

Return type:

dict

Returns:

Response Syntax

{
    'aggregates': [
        {
            'attribute': 'string',
            'displayValue': 'string',
            'items': [
                {
                    'count': 123,
                    'displayValue': 'string',
                    'value': 'string'
                },
            ]
        },
    ],
    'items': [
        {
            'assetListing': {
                'additionalAttributes': {
                    'forms': 'string',
                    'latestTimeSeriesDataPointForms': [
                        {
                            'contentSummary': 'string',
                            'formName': 'string',
                            'id': 'string',
                            'timestamp': datetime(2015, 1, 1),
                            'typeIdentifier': 'string',
                            'typeRevision': 'string'
                        },
                    ],
                    'matchRationale': [
                        {
                            'textMatches': [
                                {
                                    'attribute': 'string',
                                    'matchOffsets': [
                                        {
                                            'endOffset': 123,
                                            'startOffset': 123
                                        },
                                    ],
                                    'text': 'string'
                                },
                            ]
                        },
                    ]
                },
                'createdAt': datetime(2015, 1, 1),
                'description': 'string',
                'entityId': 'string',
                'entityRevision': 'string',
                'entityType': 'string',
                'glossaryTerms': [
                    {
                        'name': 'string',
                        'shortDescription': 'string'
                    },
                ],
                'governedGlossaryTerms': [
                    {
                        'name': 'string',
                        'shortDescription': 'string'
                    },
                ],
                'listingCreatedBy': 'string',
                'listingId': 'string',
                'listingRevision': 'string',
                'listingUpdatedBy': 'string',
                'name': 'string',
                'owningProjectId': 'string'
            },
            'dataProductListing': {
                'additionalAttributes': {
                    'forms': 'string',
                    'matchRationale': [
                        {
                            'textMatches': [
                                {
                                    'attribute': 'string',
                                    'matchOffsets': [
                                        {
                                            'endOffset': 123,
                                            'startOffset': 123
                                        },
                                    ],
                                    'text': 'string'
                                },
                            ]
                        },
                    ]
                },
                'createdAt': datetime(2015, 1, 1),
                'description': 'string',
                'entityId': 'string',
                'entityRevision': 'string',
                'glossaryTerms': [
                    {
                        'name': 'string',
                        'shortDescription': 'string'
                    },
                ],
                'items': [
                    {
                        'glossaryTerms': [
                            {
                                'name': 'string',
                                'shortDescription': 'string'
                            },
                        ],
                        'listingId': 'string',
                        'listingRevision': 'string'
                    },
                ],
                'listingCreatedBy': 'string',
                'listingId': 'string',
                'listingRevision': 'string',
                'listingUpdatedBy': 'string',
                'name': 'string',
                'owningProjectId': 'string'
            }
        },
    ],
    'nextToken': 'string',
    'totalMatchCount': 123
}

Response Structure

(dict) –
- aggregates (list) –
  
  Contains computed counts grouped by field values based on the requested aggregation attributes for the matching listings.
  - (dict) –
    
    The aggregation for an attribute.
    - attribute (string) –
      
      The attribute for this aggregation.
    - displayValue (string) –
      
      The display value of the aggregation output item.
    - items (list) –
      
      A list of aggregation output items.
      - (dict) –
        
        An aggregation output item.
        
        count (integer) –
        
        The count of the aggregation output item.
        
        displayValue (string) –
        
        The display value of the aggregation. If the attribute being aggregated corresponds to the id of a public resource, the service automatically resolves the id to the provided display value.
        
        value (string) –
        
        The attribute value of the aggregation output item.
- items (list) –
  
  The results of the SearchListings action.
  - (dict) –
    
    The details of the results of the SearchListings action.
    Note
    This is a Tagged Union structure. Only one of the following top level keys will be set: assetListing, dataProductListing. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
    'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
    - assetListing (dict) –
      
      The asset listing included in the results of the SearchListings action.
      - additionalAttributes (dict) –
        
        The additional attributes of an asset published in an Amazon DataZone catalog.
        
        forms (string) –
        
        The metadata forms that form additional attributes of the metadata asset.
        
        latestTimeSeriesDataPointForms (list) –
        
        The latest time series data points forms included in the additional attributes of an asset.
        
        (dict) –
        
        The summary of the time series data points form.
        
        contentSummary (string) –
        
        The content of the summary of the time series data points form.
        
        formName (string) –
        
        The name of the time series data points summary form.
        
        id (string) –
        
        The ID of the time series data points summary form.
        
        timestamp (datetime) –
        
        The timestamp of the time series data points summary form.
        
        typeIdentifier (string) –
        
        The type ID of the time series data points summary form.
        
        typeRevision (string) –
        
        The type revision of the time series data points summary form.
        
        matchRationale (list) –
        
        List of rationales indicating why this item was matched by search.
        
        (dict) –
        
        A rationale indicating why this item was matched by search.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: textMatches. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        textMatches (list) –
        
        A list of TextMatchItems.
        
        (dict) –
        
        A structure indicating matched terms for an attribute.
        
        attribute (string) –
        
        The name of the attribute.
        
        matchOffsets (list) –
        
        List of offsets indicating matching terms in the TextMatchItem text.
        
        (dict) –
        
        The offset of a matched term.
        
        endOffset (integer) –
        
        The 0-indexed number indicating the end position (exclusive) of a matched term.
        
        startOffset (integer) –
        
        The 0-indexed number indicating the start position (inclusive) of a matched term.
        
        text (string) –
        
        Snippet of attribute text containing highlighted content.
      - createdAt (datetime) –
        
        The timestamp of when an asset published in an Amazon DataZone catalog was created.
      - description (string) –
        
        The description of an asset published in an Amazon DataZone catalog.
      - entityId (string) –
        
        The identifier of the inventory asset.
      - entityRevision (string) –
        
        The revision of the inventory asset.
      - entityType (string) –
        
        The type of the inventory asset.
      - glossaryTerms (list) –
        
        Glossary terms attached to the inventory asset.
        
        (dict) –
        
        Details of a glossary term attached to the inventory asset.
        
        name (string) –
        
        The name of a glossary term attached to the inventory asset.
        
        shortDescription (string) –
        
        The shoft description of a glossary term attached to the inventory asset.
      - governedGlossaryTerms (list) –
        
        The restricted glossary terms associated with an asset.
        
        (dict) –
        
        Details of a glossary term attached to the inventory asset.
        
        name (string) –
        
        The name of a glossary term attached to the inventory asset.
        
        shortDescription (string) –
        
        The shoft description of a glossary term attached to the inventory asset.
      - listingCreatedBy (string) –
        
        The Amazon DataZone user who created the listing.
      - listingId (string) –
        
        The identifier of the listing (asset published in Amazon DataZone catalog).
      - listingRevision (string) –
        
        The revision of the listing (asset published in Amazon DataZone catalog).
      - listingUpdatedBy (string) –
        
        The Amazon DataZone user who updated the listing.
      - name (string) –
        
        The name of the inventory asset.
      - owningProjectId (string) –
        
        The identifier of the project that owns the inventory asset.
    - dataProductListing (dict) –
      
      The data product listing.
      - additionalAttributes (dict) –
        
        The additional attributes of the asset of the data product.
        
        forms (string) –
        
        The metadata forms of the asset of the data product.
        
        matchRationale (list) –
        
        List of rationales indicating why this item was matched by search.
        
        (dict) –
        
        A rationale indicating why this item was matched by search.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: textMatches. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        textMatches (list) –
        
        A list of TextMatchItems.
        
        (dict) –
        
        A structure indicating matched terms for an attribute.
        
        attribute (string) –
        
        The name of the attribute.
        
        matchOffsets (list) –
        
        List of offsets indicating matching terms in the TextMatchItem text.
        
        (dict) –
        
        The offset of a matched term.
        
        endOffset (integer) –
        
        The 0-indexed number indicating the end position (exclusive) of a matched term.
        
        startOffset (integer) –
        
        The 0-indexed number indicating the start position (inclusive) of a matched term.
        
        text (string) –
        
        Snippet of attribute text containing highlighted content.
      - createdAt (datetime) –
        
        The timestamp at which the asset of the data product listing was created.
      - description (string) –
        
        The description of the asset of the asset of the data product.
      - entityId (string) –
        
        The entity ID of the asset of the asset of the data product.
      - entityRevision (string) –
        
        The revision of the asset of the asset of the data product.
      - glossaryTerms (list) –
        
        The glossary terms of the asset of the asset of the data product.
        
        (dict) –
        
        Details of a glossary term attached to the inventory asset.
        
        name (string) –
        
        The name of a glossary term attached to the inventory asset.
        
        shortDescription (string) –
        
        The shoft description of a glossary term attached to the inventory asset.
      - items (list) –
        
        The data of the asset of the data product.
        
        (dict) –
        
        The results of the data product summary.
        
        glossaryTerms (list) –
        
        The glossary terms of the data product listing.
        
        (dict) –
        
        Details of a glossary term attached to the inventory asset.
        
        name (string) –
        
        The name of a glossary term attached to the inventory asset.
        
        shortDescription (string) –
        
        The shoft description of a glossary term attached to the inventory asset.
        
        listingId (string) –
        
        The ID of the data product listing.
        
        listingRevision (string) –
        
        The revision of the data product listing.
      - listingCreatedBy (string) –
        
        The timestamp at which the listing was created.
      - listingId (string) –
        
        The ID of the listing.
      - listingRevision (string) –
        
        The revision of the listing.
      - listingUpdatedBy (string) –
        
        The user who updated the listing.
      - name (string) –
        
        The name of the asset of the data product.
      - owningProjectId (string) –
        
        The ID of the owning project of the asset of the data product.
- nextToken (string) –
  
  When the number of results is greater than the default value for the MaxResults parameter, or if you explicitly specify a value for MaxResults that is less than the number of results, the response includes a pagination token named NextToken. You can specify this NextToken value in a subsequent call to SearchListings to list the next set of results.
- totalMatchCount (integer) –
  
  Total number of search results.

Exceptions

DataZone.Client.exceptions.InternalServerException
DataZone.Client.exceptions.AccessDeniedException
DataZone.Client.exceptions.ThrottlingException
DataZone.Client.exceptions.ValidationException
DataZone.Client.exceptions.UnauthorizedException