Synonyms API
Overview
A synonym group rewrites searches for any of its child phrases to its parent phrase. A search whose whole query equals a child (case-insensitively, ignoring leading and trailing whitespace) runs as a search for the parent, and gets the parent's search rules. Searching for the parent is not expanded to its children.
For example, a group with parent running shoes and children runners and trainers makes a
search for Trainers return the results and merchandising of running shoes.
| Method | Path | Description |
|---|---|---|
GET | /synonyms | List synonym groups |
POST | /synonyms | Create a synonym group |
GET | /synonyms/groups/{parent} | Get a group |
PATCH | /synonyms/groups/{parent} | Add or remove children |
DELETE | /synonyms/groups/{parent} | Delete a group |
GET | /synonyms/phrases/{phrase} | Find the group a phrase belongs to |
Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise.
Encode {parent} and {phrase} as one path segment (see
Triggers in the path). Both are case-insensitive.
Synonym group fields
| Field | Type | Description |
|---|---|---|
parent | string | The phrase searches are rewritten to. Up to 200 characters. |
children | string[] | 1 to 50 phrases, each up to 200 characters, rewritten to the parent. Unique case-insensitively, and must not include the parent. |
revision | string | Read-only. See Revisions. |
Phrases are matched canonically (edge whitespace removed, lower-cased, Unicode-normalised), but
stored and returned as you wrote them, so Running Shoes keeps its capitals.
Rules
- A phrase belongs to at most one group, and a parent can't also be a child. Using a phrase that
is in another group is
409 phrase_in_use, naming the phrase. - A phrase that has its own
searchrules, or asearchfacet override set in the console, can't become a child (409 child_has_rules): once it is a child, those rules would never apply. Move or delete them first. - Phrases holding control characters, or characters no search query can contain, are
400 validation_error. - Rules stored under the parent stay with it when the group changes or is deleted.
List synonym groups
Endpoint: GET /synonyms
Ordered by parent, case-insensitively.
| Query parameter | Description |
|---|---|
search | Optional case-insensitive prefix, matched against parents and children. Up to 200 characters. |
limit | Groups per page, 1 to 25. Defaults to 10. |
cursor | The nextCursor from the previous page. |
curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms?search=run&limit=25" \
-H "Authorization: Bearer {api_key}"
{
"items": [
{
"parent": "running shoes",
"children": ["runners", "trainers", "jogging shoes"],
"revision": "4b7e19c2a0d84f6e9b3c5a1d2e7f8091"
}
],
"nextCursor": null
}
Create a synonym group
Endpoint: POST /synonyms
- cURL
- JavaScript
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"parent": "running shoes",
"children": ["runners", "trainers", "jogging shoes"]
}'
await fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms", {
method: "POST",
headers: {
Authorization: "Bearer {api_key}",
"Content-Type": "application/json",
},
body: JSON.stringify({
parent: "running shoes",
children: ["runners", "trainers", "jogging shoes"],
}),
});
Returns 201 with the created group. If a group with the same parent exists:
- with the same children (compared canonically, in any order), the request returns
200with the stored group, so a retried create succeeds; - otherwise it fails with
409 already_exists.
If-Match and If-None-Match are refused with 400 validation_error.
Get a synonym group
Endpoint: GET /synonyms/groups/{parent}
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}"
Returns the group, or 404 synonym_group_not_found.
Add or remove children
Endpoint: PATCH /synonyms/groups/{parent}
| Field | Description |
|---|---|
add | Phrases to add as children. Up to 50, each up to 200 characters. |
remove | Phrases to remove. Up to 50. |
curl -X PATCH https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"add": ["sneakers"],
"remove": ["jogging shoes"]
}'
Returns the updated group.
- Adding a phrase that is already a child, or removing one that isn't, is a no-op, so a retried
PATCHsucceeds. - Added children are checked as on create.
- A group must keep at least one child, and can have at most 50; to remove every child, delete the group.
- One
PATCHcan change at most 97 children in total (real additions plus real removals); split larger changes. - Takes an optional
If-Match. A missing group is404 synonym_group_not_foundwhateverIf-Matchsays. 409 ambiguous_synonym_group: the group was stored with children that differ only in case, accents or whitespace. Delete it and create it again.
Delete a synonym group
Endpoint: DELETE /synonyms/groups/{parent}
curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}"
Returns 204. The children stop being rewritten; rules stored under the parent stay. Returns
404 synonym_group_not_found if the group doesn't exist, including on a retry. Takes an optional
If-Match.
Look up a phrase
Endpoint: GET /synonyms/phrases/{phrase}
Finds whether a phrase is a parent or a child, and of which group.
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/phrases/trainers \
-H "Authorization: Bearer {api_key}"
{
"role": "child",
"phrase": "trainers",
"parent": "running shoes"
}
parent is set only when role is child. A phrase in no group returns
404 synonym_group_not_found.
Renaming a parent
The API has no rename. To rename a parent:
- Delete the old group.
- Create a group with the new parent and the same children.
- Move the old parent's
searchrules:GETthem, removetriggerfrom the body (it must match the path),PUTthe body to the new parent, thenDELETEthem from the old parent.
The old parent can't become a child of the new group while it still has its own rules
(409 child_has_rules), so move the rules before adding it.
The steps aren't atomic, so the children briefly aren't rewritten. The console's rename does this in one step.
Marqo may create internal synonym groups on your index. They are not listed and return 404
through the API, but they still serve and take part in conflict checks, so a conflict message can
name an internal group's parent.