SearchListings

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

POST /v2/domains/domainIdentifier/listings/search HTTP/1.1
Content-type: application/json

{
   "additionalAttributes": [ "string" ],
   "aggregations": [ 
      { 
         "attribute": "string",
         "displayValue": "string"
      }
   ],
   "filters": { ... },
   "maxResults": number,
   "nextToken": "string",
   "searchIn": [ 
      { 
         "attribute": "string"
      }
   ],
   "searchText": "string",
   "sort": { 
      "attribute": "string",
      "order": "string"
   }
}

URI Request Parameters

The request uses the following URI parameters.

Request Body

The request accepts the following data in JSON format.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
   "aggregates": [ 
      { 
         "attribute": "string",
         "displayValue": "string",
         "items": [ 
            { 
               "count": number,
               "displayValue": "string",
               "value": "string"
            }
         ]
      }
   ],
   "items": [ 
      { ... }
   ],
   "nextToken": "string",
   "totalMatchCount": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Errors

For information about the errors that are common to all actions, see Common Errors.

Examples

Example

This example illustrates a lexical search.

Sample Request

aws datazone search-listings \
--domain-identifier "dzd_4q2el0k35ngqa8" \
--search-in '[{"attribute":"DataProductMetadataForm.name"}]' \
--search-text "\"car\"" \
--additional-attributes '["FORMS"]'    
            

Sample Response

{
    "items": [
        {
            "assetListing": {
                "additionalAttributes": {
                    "forms": "{\"S3ObjectCollectionForm\":{\"bucketArn\":\"arn:aws:s3:::bucket/prefix\"},\"DataProductMetadataForm\":{\"name\":\"car\"}}"
                },
                "createdAt": "2025-08-28T21:41:17.026000+00:00",
                "entityId": "asl5ff7g6psoi8",
                "entityRevision": "4",
                "entityType": "S3ObjectCollectionAssetType",
                "glossaryTerms": [],
                "listingCreatedBy": "f697efa1-8b40-41c1-b1ef-977412f9d3d4",
                "listingId": "3tgx25pz22pic0",
                "listingRevision": "6",
                "listingUpdatedBy": "f697efa1-8b40-41c1-b1ef-977412f9d3d4",
                "name": "test",
                "owningProjectId": "4mo2oiauaqbrtc"
            }
        }
    ],
    "totalMatchCount": 1
}
            

Example

This example illustrates the filtering capabilities of the SearchListings APIs. Note: __DataZoneGlossaryTerms is a special keyword for getting all aggregated glossary terms across assets, custom metadata forms and columns.

Sample Request

aws datazone search-listings \
    --domain-identifier "dzd_4q2el0k35ngqa8" \
    --filters '{ "or": [
        { "filter": { "attribute": "__DataZoneGlossaryTerms", "value": "cxjyge917oaaa8" } },
        { "filter": { "attribute": "__DataZoneGlossaryTerms", "value": "46i8vpwe0s0t9j" } }
    ] }'
            

Sample Response

{
    "items": [
        {
            "assetListing": {
                "createdAt": "2025-09-05T16:53:55.563000+00:00",
                "entityId": "dgutcpgqbkbcsw",
                "entityRevision": "2",
                "entityType": "S3ObjectCollectionAssetType",
                "glossaryTerms": [
                    {
                        "name": "artist"
                    }
                ],
                "listingCreatedBy": "f697efa1-8b40-41c1-b1ef-977412f9d3d4",
                "listingId": "anj2uue0h4qd1s",
                "listingRevision": "2",
                "listingUpdatedBy": "f697efa1-8b40-41c1-b1ef-977412f9d3d4",
                "name": "blab",
                "owningProjectId": "4mo2oiauaqbrtc"
            }
        }
    ],
    "totalMatchCount": 1
}
            

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: