getPagesByVectorSearch
Semantic (vector) search for pages.
Description
This method performs a semantic (vector) search for pages from a natural-language query - it matches on meaning rather than exact keywords. It returns a Promise that resolves to an IPagesResponse object - a container with items (the pages) and total - not a bare array.
Pages.getPagesByVectorSearch(
body*,
langCode,
offset,
limit
);
Parameters schema
Schema
body(required): IPagesVectorSearch
Vector search body
example:
{ queryText: "winter sale" }
body.queryText(required): string
Natural-language search query.
example: "winter sale"
body.vectorDistanceThreshold: number
Override of the cosine distance threshold (0..2).
example: 0.3
body.maxHits: number
Top-K candidates fetched before pagination. Default: 100. Max: 500.
example: 10
body.debug: boolean
When true, each returned item gets a distance field.
example: false
langCode: string
Language code. Default: "en_US"
example: "en_US"
offset: number
Parameter for pagination. Default: 0
example: 0
limit: number
Parameter for pagination. Default: 30
example: 30
Examples
Minimal example
const response = await Pages.getPagesByVectorSearch({ queryText: 'winter sale' });
Example with attributes
const response = await Pages.getPagesByVectorSearch(
{
queryText: 'winter sale',
vectorDistanceThreshold: 0.3,
maxHits: 50,
debug: true,
},
'en_US',
0,
30,
);
Example response
{
"items": [
{
"id": 9,
"config": {},
"depth": 1,
"parentId": 8,
"pageUrl": "blog1",
"attributeSetIdentifier": null,
"localizeInfos": {
"title": "Blog 1",
"htmlContent": "",
"plainContent": "",
"menuTitle": "Blog 1"
},
"isVisible": true,
"products": 0,
"childrenCount": 0,
"type": "common_page",
"position": 1,
"templateIdentifier": null,
"isSync": false,
"categoryPath": "blog/blog1",
"rating": {},
"attributeValues": {},
"moduleFormConfigs": []
}
],
"total": 1
}
Response schema
Schema: IPagesResponse
items: IPagesEntity[]
Array of found page objects.
items.id: number
The identifier of the object.
example: 8
items.parentId: number | null
The id of the parent page, if it contains null, then it is the top-level page.
example: 10
items.pageUrl: string
Unique page Url.
example: "blog"
items.depth: number
Page nesting depth relative to parentId.
example: 10
items.localizeInfos: ILocalizeInfo
The name of the page, taking into account localization.
example:
{
"title": "Blog",
"menuTitle": "Blog",
"htmlContent": "",
"plainContent": ""
}
items.isVisible: boolean
A sign of page visibility.
example: true
items.type: PageType
Page type.
example: "common_page"
items.templateIdentifier: string | null
User id of the linked template.
example: "template"
items.attributeSetIdentifier: string | null
Set of attributes id.
example: "page"
items.attributeValues: IAttributeValues
Map of attribute values keyed by marker; empty object when none.
example:
{
"text": {
"type": "string",
"value": "some text",
"position": 0,
"additionalFields": []
}
}
items.isSync: boolean
Indication of page indexing.
example: true
items.template: object
Template object.
example:
{}
items.position: number
Item number (for sorting).
example: 2
items.config: Record<string, number>
Output settings for catalog pages.
example:
{
"rowsPerPage": 1,
"productsPerRow": 1
}
items.products: number
The number of products linked to the page.
example: 0
items.childrenCount: number
Children count.
example: 1
items.blocks: IBlockEntity[] | string[]
blocks.
example:
{
"id": 4,
"attributeSetIdentifier": null,
"title": "Template",
"generalTypeId": 4,
"identifier": "template",
"version": 0,
"generalTypeName": "catalog_page",
"attributeValues": {},
"position": 1
}
items.blocks.attributeValues: IAttributeValues
Map of attribute values keyed by marker; empty object when none.
example:
{
"block-text": {
"type": "string",
"value": "some text",
"isIcon": false,
"position": 0,
"additionalFields": [],
"isProductPreview": false
}
}
items.blocks.id: number
Unique identifier of the block.
example: 1234
items.blocks.localizeInfos: ILocalizeInfo
Localization information for the block.
example:
{
"key": "value"
}
items.blocks.version: number
Version of the block entity.
example: 1
items.blocks.identifier: string
Unique string identifier for the block.
example: "block1"
items.blocks.type: BlockType
Type of the block.
example: "product"
items.blocks.position: number
Position of the block for sorting.
example: 1
items.blocks.templateIdentifier: string | null
Identifier for the template used by the block, or null if not applicable.
example: "template1"
items.blocks.isVisible: boolean
Indicates whether the block is visible.
example: true
items.blocks.countElementsPerRow: number
Number of elements displayed per row in the block, if applicable.
example: 3
items.blocks.quantity: number
Quantity of items in the block, if applicable.
example: 5
items.blocks.similarProducts: IProductsResponse
Response containing similar products associated with the block.
example:
{
"total": 10,
"items": []
}
items.blocks.products: IProductsEntity[]
Array of product entities associated with the block.
example:
[
{
"id": 1,
"name": "Product 1"
},
{
"id": 2,
"name": "Product 2"
}
]
items.moduleFormConfigs: Array<IFormConfig>
Module form configurations linked to the page.
items.rating: IRating
Rating data.
items.total: string
Total number of products linked to the page.
example: "10"
items.categoryPath: string | null
Category path string; null for nested pages that have no own category path.
example: "catalog"
items.distance: number
Cosine distance to the query. Returned only by the semantic (vector) search endpoint when debug: true is passed in the search body.
example: 0.12
total: number
Total number of found records.
example: 100
ℹ️ Semantic search matches on meaning, not on the literal text. For keyword matching across every entity type at once use globalSearch().