Configure Index

Overview

Every index carries a configuration that controls how searches run by default and how documents are processed when they are added. You can read and replace it through the index configuration endpoint.

The configuration has three blocks:

Block	Controls	Takes effect
`searchConfig`	Default search parameters merged into every search request	Within about a minute
`collectionsConfig`	Which field holds collection membership, and the default parameters for collection browsing	Within about a minute
`addDocsConfig`	How documents are processed at indexing time	On documents indexed after the change; existing documents need to be reindexed

For the shopper-facing knobs that most stores need, such as SKU matching, out-of-stock handling and facet display names, use the simpler Search Settings endpoint instead. It manages the relevant parts of this configuration for you.

Both endpoints on this page take your API key as a bearer token:

Authorization: Bearer {api_key}

Get Index Configuration

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config

cURL
JavaScript

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config \
  -H "Authorization: Bearer {api_key}"

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config", {
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response

The response contains the three blocks plus the read-only queueType chosen when the index was created. Keys that are not set are omitted. A trimmed example:

{
  "searchConfig": {
    "searchMethod": "HYBRID",
    "limit": 60,
    "showHighlights": false,
    "collapseFields": [{ "name": "parentProductId" }],
    "hybridParameters": {
      "alpha": 0.2,
      "rrfK": 60,
      "searchableAttributesLexical": ["variantTitle"]
    }
  },
  "collectionsConfig": {
    "collections_field_name": "productCollections",
    "default": {
      "q": "*",
      "limit": 60,
      "collapseFields": [{ "name": "parentProductId" }]
    }
  },
  "addDocsConfig": {
    "collapse_fields": ["parentProductId"],
    "tensor_fields": ["productTitle", "variantImageUrl"],
    "merchandising_fields": ["productVendor"]
  },
  "queueType": "standard"
}

The response can also contain keys that Marqo manages for you, such as readAlias when your index has read routing configured. Send back only the blocks documented below; leave anything else as it is.

Errors

Status	Body	When
`404`	`{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}`	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned.
`404`	`{"error": "Index config not found"}`	The index exists but has no configuration record. Contact Marqo.

Update Index Configuration

Endpoint: PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config

Send one or more of the three blocks. Each block you include replaces that block in full; blocks you leave out are untouched. There is no merging within a block, so to change one key, read the current configuration, edit the block, and send the whole block back. An empty object is ignored rather than clearing the block.

Request Body

Parameter	Type	Default	Description
`searchConfig`	object	Unchanged	New default search parameters. See searchConfig.
`collectionsConfig`	object	Unchanged	New collection settings. See collectionsConfig.
`addDocsConfig`	object	Unchanged	New document indexing settings. See addDocsConfig.

queueType cannot be changed through this endpoint; including it returns 400.

:::warning Marqo-managed keys The endpoint also accepts routing keys that Marqo manages on your behalf, such as readAlias, which redirects the index's search reads to a different index. Sending one changes where your storefront searches are served from. Do not include them unless Marqo has asked you to, and drop them before sending back a configuration you read from GET /config. :::

Example Request

This example raises the default number of results, returns only a few fields for each product, and collapses variants so each product appears once.

cURL
JavaScript

curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
  "searchConfig": {
    "searchMethod": "HYBRID",
    "limit": 24,
    "attributesToRetrieve": ["_id", "productTitle", "price", "variantImageUrl"],
    "collapseFields": [{ "name": "parentProductId" }]
  }
}'

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    searchConfig: {
      searchMethod: "HYBRID",
      limit: 24,
      attributesToRetrieve: ["_id", "productTitle", "price", "variantImageUrl"],
      collapseFields: [{ name: "parentProductId" }],
    },
  }),
});

Response

200 OK with an empty body.

Errors

Status	Body	When
`400`	`{"error": "Updating queueType is not supported via this endpoint"}`	The body includes `queueType`.
`404`	`{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}`	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned.
`422`	`{"error": [...]}`	`addDocsConfig` or `collectionsConfig` failed validation. The list describes each invalid key.

searchConfig

searchConfig is a set of Marqo search parameters that is merged into every search request against the index. A parameter sent in a search request overrides the same parameter here, so this block sets the defaults for your storefront. Keys use camelCase, the same as the search request body.

Commonly used keys:

Key	Type	Description
`limit`	integer	Default number of results per page when a search does not pass `limit`.
`attributesToRetrieve`	array of strings	Which document fields to return in each result when a search does not pass `attributesToRetrieve`.
`sortBy`	object	Default sort, using the same shape as `sortBy` on the search request.
`facets`	object	Default facet configuration for search responses.
`filter`	string	A filter applied to every search, for example to hide unpublished products.
`collapseFields`	array of objects	Fields to collapse results on, so that one result is returned per product rather than per variant: `[{"name": "parentProductId"}]`. See Deduping variants.
`queryPrefix`	string	Text prepended to every query before it is embedded.
`language`	string	Language used for lexical search when a request does not pass one.
`showHighlights`	boolean	Whether results include the matched text highlights.
`searchMethod`	string	`HYBRID` combines keyword and semantic matching, which is the default for new indexes.
`hybridParameters`	object	Tuning for hybrid search, such as the balance between keyword and semantic matching (`alpha`) and which fields keyword search looks at (`searchableAttributesLexical`).
`scoreModifiers`	object	Boosts and penalties applied to result scores based on numeric document fields.
`relevanceCutoff`	object	Drops low-relevance results from the tail of the result set. Whether it applies is also controlled by `relevanceSearch` and `relevanceSort` in Search Settings.

Other Marqo search parameters are accepted as well. The block is stored as you send it and is not validated on write, so a mistyped key silently has no effect and an invalid value only fails when a search runs. Test on a staging tier index first.

collectionsConfig

collectionsConfig controls the collection browsing endpoint. Keys in this block use snake_case.

Key	Type	Default	Description
`collections_field_name`	string	`productCollections`	The document field that lists the collections a product belongs to. Collection browsing filters on this field.
`default`	object	Marqo defaults	Search parameters used for every collection, in the same camelCase form as `searchConfig`.
`<collection name>`	object	None	Search parameters for one specific collection, keyed by the collection name. Use this to give a collection its own sort, limit or facets.

Example:

{
  "collectionsConfig": {
    "collections_field_name": "productCollections",
    "default": {
      "limit": 48,
      "collapseFields": [{ "name": "parentProductId" }]
    },
    "sale": {
      "limit": 48,
      "sortBy": { "fields": [{ "fieldName": "price", "order": "asc" }] }
    }
  }
}

addDocsConfig

addDocsConfig controls how documents are transformed and embedded when they are added to the index. Keys in this block use snake_case. Changes apply to documents indexed after the update; to apply them to documents already in the index, add the documents again.

The keys most relevant to catalogs sent through the Add Products API:

Key	Type	Description
`tensor_fields`	array of strings	The fields that are embedded for semantic search, such as the product title and the main image URL. Fields not listed here are still stored and searchable by keyword.
`collapse_fields`	array of strings	Fields the index prepares for collapsing results, so that `collapseFields` in `searchConfig` or in a search request can group variants by that field.
`merchandising_fields`	array of strings	Fields whose values can be used in boost and bury rules. See Merchandising fields below for the dedicated endpoint.
`fast_numeric_fields`	array of strings	Numeric fields optimized for range filters and sorting. Documents must be reindexed after adding a field here.
`version_field`	string	A document field compared on each write so that an older version of a document never overwrites a newer one. A write is skipped when the incoming value is less than or equal to the stored value.
`conflict_check_enabled`	boolean	Whether that version comparison runs. Defaults to enabled; set to `false` to always apply the latest write.
`excluded_fields`	array of strings	Fields stripped from every document before indexing, for example large payloads that are never searched or displayed.
`field_copy_map`	object	Copies the value of one field into another: each key is the target field name and each value is the source field name. The source field is kept.
`translation_locales`	array of strings	Locale codes such as `fr` or `en-GB`. Applies to indexes connected to Shopify, where translated fields are fetched and indexed as locale-suffixed fields such as `productTitle_fr`.

Indexes connected to Shopify accept further keys that control how the Shopify catalog is transformed; those are set up with the Marqo team.

Invalid values return 422 with a list of the failing keys. For example, translation_locales entries must be in the form xx or xx-YY.

Merchandising fields

Boost and bury rules can only reference fields that the index has been told to prepare for merchandising. This pair of endpoints reads and extends that list without touching the rest of addDocsConfig.

List merchandising fields

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields

cURL
JavaScript

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields \
  -H "Authorization: Bearer {api_key}"

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields", {
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

The response is a JSON array of field names, empty when none are configured:

["productVendor", "productType"]

Add merchandising fields

Endpoint: POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields

Parameter	Type	Default	Description
`fields`	array of strings	Required	Field names to make available for boost and bury rules. Fields already in the list are ignored.
`reindex`	boolean	`false`	When `true`, products already in the index are reprocessed so rules on the new fields apply to them straight away. When `false`, only products indexed after this call carry the new fields.

cURL
JavaScript

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": ["productVendor", "color"],
  "reindex": true
}'

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/config/merchandise/fields", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: ["productVendor", "color"],
    reindex: true,
  }),
});

Response

201 Created when at least one field was added, or 200 OK when every field was already present. The body lists each index that was updated:

{
  "targets": [
    {
      "systemAccountId": "...",
      "indexName": "my-store-products",
      "fieldsAdded": ["color"],
      "reindexed": false,
      "reindexJob": null
    }
  ]
}

Field	Description
`indexName`	The index that was updated.
`fieldsAdded`	The fields that were new for this index.
`reindexed`	Whether a reindex was started for this index.
`reindexJob`	The job record for the reindex when one was started, otherwise `null`.

Errors

Status	Body	When
`404`	`{"error": "Index config not found"}`	The index has no configuration record.
`422`	`{"error": "[<index>] ..."}`	The resulting configuration is invalid, for example because a field is excluded from the index by its pruning rules.

Next Steps

Search Settings: SKU matching, out-of-stock handling and facet display names
Boost and Bury: Build rules on your merchandising fields
Deduping variants: How collapseFields shapes results

Overview​

Get Index Configuration​

Response​

Errors​

Update Index Configuration​

Request Body​

Example Request​

Response​

Errors​

searchConfig​

collectionsConfig​

addDocsConfig​

Merchandising fields​

List merchandising fields​

Add merchandising fields​

Response​

Errors​

Next Steps​

Overview

Get Index Configuration

Response

Errors

Update Index Configuration

Request Body

Example Request

Response

Errors

searchConfig

collectionsConfig

addDocsConfig

Merchandising fields

List merchandising fields

Add merchandising fields

Response

Errors

Next Steps