Metadata Facets

Metadata facets allow you to group search results by metadata values. This is useful for exploring your data based on metadata properties like category, language, or author. You can retrieve facets for a single Store or across multiple Stores.

Basic Metadata Facets

To get all metadata facets for one or more Stores, you can call:

This returns the unnested metadata values with their respective counts:

{
  "facets": {
    "author": {
      "John Doe": 1,
      "Jane Doe": 2
    },
    "language": {
      "english": 2,
      "spanish": 1
    }
  }
}

Nested Metadata Facets

For complex metadata structures with nested objects, you can access specific nested fields by using dot notation (.) to separate the field hierarchy. This allows you to create facets for deeply nested properties without flattening your entire metadata structure.

For example, if your documents have metadata like:

This returns the nested metadata values with their respective counts:

{
  "facets": {
    "city.name": {
      "New York": 2,
      "London": 1
    },
    "city.country": {
      "United States": 2,
      "United Kingdom": 1
    }
  }
}

Multi-Store Facets

You can retrieve facets across multiple Stores by providing an array of Store identifiers. This is useful when you want to explore metadata across different data sources or Store versions.

facets = client.stores.metadata_facets(
    store_identifiers=["docs-v1", "docs-v2", "blog-posts"],
    facets=["category", "language"]
)

The response will aggregate facet counts across all specified Stores, giving you a unified view of your metadata distribution.

Filtering Search Results

Metadata facets can be obtained for search results by using the same parameters as the search endpoint. For example, to get the facets for a specific query, you can call: