perform_catalog_search¶

CatalogApi.perform_catalog_search(role_id, accept_encoding=None, search_type=None, query=None, fields_to_match=None, get_metrics=None, include_match_score=None, page_number=None, limit=None, offset=None, access_level=None, start_time=None, end_time=None, time_field=None, domain=None, asset_type=None, tenant=None, datasource_name=None, datasource_type=None, keywords=None, tags_attached=None, data_classification=None, file_type=None, target_location=None, ingestion_type=None, data_category=None, created_by=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Search catalog assets

Searches across catalog data sources and returns the assets associated with each. Despite being a POST, this operation takes no request body: every input is a query parameter, and any body sent is ignored. Two search modes are available via search_type. “traditional” does keyword matching over the fields named in FieldsToMatch. “semantic” does embedding-based matching, requires a non-empty query, requires AI services to be enabled, and returns extra per-asset attributes. Setting get_metrics=true changes the response shape entirely: it returns only facet counts and total_count, with no Results array and no pagination keys. Use it to populate filter controls, then run the real search separately. Filtering: any query parameter that is not one of the documented system parameters is treated as a filter on the catalog field of that exact name, with comma-separated values. Filter values are lower-cased before matching, except for FieldsToMatch. There is no allow-list, so a misspelled filter name silently matches nothing rather than erroring. Pagination: paging is by page_number, which is zero-based, combined with limit as the page size. Read next_available in the response; while it is “yes” increment page_number, and stop when it is “no”. total_pages is also returned. Note that the offset parameter is validated but has no effect.

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. (required)
accept_encoding (str) – When this includes “gzip” the response body is gzip-compressed and base64-encoded, and the response carries Content-Encoding: gzip. Worth using, since catalog search responses can be large.
search_type (str) – Search mode. “semantic” additionally requires a non-empty query and an environment with AI services and catalog AI search enabled; otherwise it fails with AI-1005 or AI-1007. An unrecognised value is rejected with IPV-1071.
query (str) – Search text. Optional for traditional search, but mandatory and non-empty for semantic search, where omitting it is rejected with IPV-1052. Longer than 255 characters is rejected with IPV-1068. When FieldsToMatch is “Any”, two advanced forms are recognised: a value ending in “~” or “~<digit>” is treated as a fuzzy query, and a value wrapped in forward slashes is treated as a regular expression. Otherwise the value is escaped and matched as a substring.
fields_to_match (str) – Comma-separated list of fields the query text is matched against. The special value “Any” searches across all fields and enables the fuzzy and regex query forms. When omitted and query is non-empty, the backend defaults to AssetName, Description, AssetId and DisplayName. Values here are not lower-cased, and are not validated against the index, so an unknown field name simply matches nothing.
get_metrics (str) – When “true”, return only facet counts and total_count using the CatalogSearchMetricsResponse shape, with no Results array and no pagination keys.
include_match_score (str) – When “true”, each result carries a MatchScore and results below the relevance threshold are dropped. Applies to semantic search only and is ignored for traditional search.
page_number (int) – Zero-based index of the page to return, used together with limit. Must be a non-negative integer, otherwise the request is rejected with IPV-1004.
limit (int) – Page size. Must be a non-negative integer and no greater than 5000; a larger value is rejected with IPV-1050.
offset (int) – Accepted and validated as a non-negative integer, but it has no effect on the response. Use page_number for paging.
access_level (str) – Restricts results to assets the caller holds this level of access on. An unrecognised value is rejected with IPV-1071.
start_time (str) – Start of the time window, in “YYYY-MM-DD HH:MM:SS” format. Note this is a space-separated format, not RFC 3339; sending “2026-01-01T00:00:00Z” is rejected with IPV-1056. Time filtering is applied only when start_time or end_time is explicitly supplied. When one is given the other defaults to six months ago and now respectively, and start_time must not be later than end_time (IPV-1036).
end_time (str) – End of the time window, in “YYYY-MM-DD HH:MM:SS” format. See start_time for how time filtering is activated.
time_field (str) – Which timestamp the time window applies to. Only validated when time filtering is active, that is when start_time or end_time was supplied; otherwise the value is ignored entirely.
domain (str) – Filter by domain. Comma-separated for multiple values, matched case-insensitively. One of several field filters: see the operation description for how arbitrary field filters are handled.
asset_type (str) – Filter by asset type. Comma-separated, case-insensitive.
tenant (str) – Filter by tenant, restricted to tenants the caller can access. When omitted the search covers all accessible tenants plus assets that have no tenant.
datasource_name (str) – Filter by datasource name for traditional search. Note that the semantic search path reads this filter under the differently-cased name “Datasourcename”; the two are not interchangeable.
datasource_type (str) – Filter by datasource type. Comma-separated, case-insensitive.
keywords (str) – Filter by keyword. Comma-separated, case-insensitive.
tags_attached (str) – Filter by attached tag. Comma-separated, case-insensitive.
data_classification (str) – Filter by data classification. Comma-separated, case-insensitive.
file_type (str) – Filter by file type. Comma-separated, case-insensitive.
target_location (str) – Filter by target location. Comma-separated, case-insensitive.
ingestion_type (str) – Filter by ingestion type. Comma-separated, case-insensitive.
data_category (str) – Filter by data category. Comma-separated, case-insensitive.
created_by (str) – Filter by creating user. Comma-separated, case-insensitive.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

PerformCatalogSearch200Response

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /catalog/search

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`
`Accept-Encoding`	header	`"gzip"`
`search_type`	query	`"traditional"`
`query`	query	`"customer orders"`
`FieldsToMatch`	query	`"AssetName,Description"`
`get_metrics`	query	`"false"`
`include_match_score`	query	`"false"`
`page_number`	query	`0`
`limit`	query	`1000`
`access_level`	query	`"all"`
`start_time`	query	`"2026-01-01 00:00:00"`
`end_time`	query	`"2026-06-30 23:59:59"`
`time_field`	query	`"CreationTime"`
`Domain`	query	`"sales,finance"`
`AssetType`	query	`"dataset"`
`Tenant`	query	`"amorphic"`
`DatasourceName`	query	`"sales_source"`
`DatasourceType`	query	`"jdbc"`
`Keywords`	query	`"orders"`
`TagsAttached`	query	`"pii"`
`DataClassification`	query	`"confidential"`
`FileType`	query	`"csv"`
`TargetLocation`	query	`"s3athena"`
`IngestionType`	query	`"file"`
`DataCategory`	query	`"internal"`
`CreatedBy`	query	`"user1"`

Success (HTTP 200)¶

Search results. The body is CatalogSearchResponse normally, or CatalogSearchMetricsResponse when get_metrics=true. When the request sends Accept-Encoding: gzip the body is gzip-compressed and base64-encoded.

Traditional keyword search

{
  "Results": [
    {
      "AssetId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "AssetName": "customer_orders",
      "DisplayName": "Customer Orders",
      "AssetType": "dataset",
      "Description": "Order line items, refreshed monthly",
      "AccessType": "read-only",
      "DatasourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "DatasourceName": "sales_source",
      "DatasourceType": "jdbc",
      "Domain": "sales",
      "TargetLocation": "s3athena",
      "Keywords": [
        "orders",
        "sales"
      ],
      "ResourceType": "dataset",
      "IngestionType": "file",
      "DataCategory": "internal",
      "LastModifiedTime": "2026-02-25T12:30:45.123456+00:00"
    }
  ],
  "Metrics": {
    "Domain": {
      "sales": 42
    },
    "AssetType": {
      "dataset": 55
    },
    "FieldsToMatch": {
      "AssetName": 0,
      "Any": 0
    }
  },
  "count": 1,
  "total_count": 142,
  "total_pages": 1,
  "next_available": "no"
}

Semantic search with include_match_score=true

{
  "Results": [
    {
      "AssetId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "AssetName": "customer_orders",
      "DisplayName": "Customer Orders",
      "AssetType": "dataset",
      "Description": "Order line items, refreshed monthly",
      "AccessType": "owner",
      "DatasourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "DatasourceName": "sales_source",
      "Domain": "sales",
      "MatchScore": 0.82,
      "DataClassification": "confidential",
      "Tags": [],
      "GlossaryDetails": {},
      "CustomMetadata": {}
    }
  ],
  "Metrics": {
    "Domain": {
      "sales": 3
    }
  },
  "count": 1,
  "total_count": 3,
  "total_pages": 1,
  "next_available": "no"
}

Facet counts only, returned when get_metrics=true

{
  "Metrics": {
    "Domain": {
      "sales": 42,
      "finance": 17
    },
    "AssetType": {
      "dataset": 55,
      "datasource": 4
    },
    "FieldsToMatch": {
      "AssetName": 0,
      "Any": 0
    }
  },
  "total_count": 142
}

No assets matched

{
  "Results": [],
  "Metrics": {},
  "count": 0,
  "total_count": 0,
  "total_pages": 0,
  "next_available": "no"
}

Errors¶

Documented error codes: IPV-1071, IPV-1052, IPV-1068, IPV-1004, IPV-1050, IPV-1056, IPV-1036, AI-1005, AI-1007, AUTH-1001, GE-1004.

HTTP 400

Input validation, authorization, or unavailable-feature failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1071 (invalid search_type, time_field or access_level), IPV-1052 (semantic search with an empty query), IPV-1068 (query longer than 255 characters), IPV-1004 (limit, page_number or offset is not a non-negative integer), IPV-1050 (limit above 5000), IPV-1056 (start_time or end_time is not in “YYYY-MM-DD HH:MM:SS” form), IPV-1036 (start_time later than end_time), AI-1005 / AI-1007 (semantic search requested where AI services or catalog AI search are not enabled), AUTH-1001 (role_id header missing).

Semantic search requested with an empty query

{
  "Message": "IPV-1052 - Parameter query is required for semantic search"
}

limit above the maximum of 5000

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 5000"
}

start_time not in the expected format

{
  "Message": "IPV-1056 - Invalid datetime format, expected YYYY-MM-DD HH:MM:SS"
}

Semantic search on an environment without AI services

{
  "Message": "AI-1005 - AI services are not enabled. Please contact the administrator to enable it."
}

HTTP 500

Backend failure. The most common cause is the search backend being unavailable or the catalog index being rebuilt, reported as GE-1004. Body is {“Message”: “<CODE> - <text>”}.