Unveil the Self-managed Components ecosystem
The Self-managed Components (SmC) developer's package is a set of the Empathy Platform essential capabilities, features, and tools to get developers like you started quickly with complete search and discovery experiences.
note
The SmC package includes as catalog a subset of the public IMDb movie dataset (opens new window) pre-configured for English.
The Self-managed components architecture is formed by four main elements: an indexing job, an Elasticsearch image, a Search service image, and a Search interface layer.
The SmC package includes the following components:
Indexing job: A data ingestion pipeline that takes all the files in the
collection-filesfolder and indexes them into Elasticsearch. This process takes around 2-3 minutes to complete when you first deploy SmC.Elasticsearch: An easy and portable way to run elastic and consume the index files. It runs on port 9200. You can use management tools such as Cerebro (opens new window) or Kibana (opens new window) to manage your SmC-based project.
Search service: The Empathy Platform's search microservice handles query processing, applying configurations, filters, etc., and communicating with Elasticsearch. This Search service is exclusively published as a Docker image and runs on port 8080. The search interface layer interacts with the Search service.
Search interface layer: An isolated, Vue-based interface search layer for your store web application. It runs on port 8081. It's built using the Empathy Platform Interface X Archetype (opens new window) (
empathyco/x-archetype), which is Empathy's vision of the ideal user interface experience with a mix of selected Interface X Components.
SmC project's structure
Once you have downloaded and deployed the SmC package, discover the project's structure held within. The most important elements are two folders: indexing and srv. The parent directory indexing contains two child folders: collection-files and scripts.
Child folders in collection files
The collection-files folder inside the indexing parent directory contains a set of catalog folders to be indexed on Elasticsearch, each folder with two .json files: data.json and mapping.json.
The scripts folder inside the indexing parent directory contains the index-data.sh script to create a catalog for each child folder in the collection-files folder. This script uses the information in the mapping.json file to create the mapping of the Elasticsearch index and then populates the catalog with data from the data.json file in the corresponding child folder (catalog, empathize, links, etc.).
The data.json file must follow the schema defined in the mapping.json file. Additionally, each product should be enclosed within a _source object, and all _source objects should be formatted as a list, following a structure similar to the example below.
{
"hits": {
"total": 15000,
"max_score": 1,
"hits": [
/* insert _source list here */
]
}
}
catalog/en
This folder contains information about the indexed products. It can be modified to index other products but, at the moment, they all must be in English (that's why it's inside anenfolder) and for the client calledimdb. It contains duplicated fields with__*names which are created exclusively for configurations.Example of a document
{ "_source": { "__url": "https://www.imdb.com/title/tt0000001", "id": "tt0000001", "type": "short", "primaryTitle": "Carmencita", "originalTitle": "Carmencita", "isAdult": false, "startYear": 1894, "runtimeMinutes": 1, "genres": [ "Documentary", "Short" ], "description": "Carmencita", "__name": "Carmencita", "__id": "tt0000001", "__boostId": "tt0000001", "__externalId": "tt0000001", "__images": [ "https://m.media-amazon.com/images/M/MV5BZmUzOWFiNDAtNGRmZi00NTIxLWJiMTUtYzhkZGRlNzg1ZjFmXkEyXkFqcGdeQXVyNDE5MTU2MDE@._V1_.jpg" ], "__prices": { "current": { "value": 36.99 } }, "price": 36.99 } }empathize/
This folder contains documents with information about the queries made and their languages. You can configure what information to store here, so you can have different popular searches and query suggestions.Example of empathize
{ "_source": { "keywords": "hamlet", "weight": 6, "extra_lang": [ "en" ] } }links/
This folder includes data to add promoted results, banners, and redirections. You must indicate the following:image_url: image to showtype: type of element ("PROMOTED", "BANNER", or "DIRECT")langs: languages affectedposition: position in the result listkeywords: queries affectedtitle: title of the configurationurl: where to redirect when clicked
You can also set thematch_allflag totrue, so the product related to the document is shown for all queries.Example of links
{ "_source": { "id": "123", "url": "https://en.wikipedia.org/wiki/Alice%27s_Adventures_in_Wonderland", "type": "(select between "PROMOTED", "BANNER" or "DIRECT")", "keywords": [ "wonderland", "alice in wonderland" ], "langs": [ "en" ], "filters": {}, "schedule": {}, "title": "Alice In Wonderland", "position": 1, "image_url": "https://miro.medium.com/v2/resize:fit:946/1*ZrKqqzr9ZwjpuP1KkJ69eQ.jpeg", "match_all": false } }searchconfigurations/
This folder contains the configurations for boosting and burying products. You must indicate the following:langs: languages affectedqueries: queries affectedid: the ID of the productaction: the action to perform ("BOOST" or "BURY")
Example of boosted or buried documents
{ "field_name":"__id", <--- name of the field to match. Here we are using the __id field "field_value":"123", "action":*select between "BURY" and "BOOST"*, "schedule":{ }, "filters":{ }, "type":"PRODUCTS" }topclicked/
This folder contains the information to show top product recommendations. You must indicate the following:id: the ID of the productclick_count: the number of received clickslang: the language
Example of top clicked documents
{ "_source": { "product_id": "123", "click_count": 200, "lang": "en", "extra": { "lang": "en" } } }
Plugin configurations
The plugin-configs folder inside the srv parent directory includes the imdb.json file. This file contains the configurations to be applied to the search experience, such as filters and facets, pagination, fields to return, fields to match, and weight of each field.
You can modify this file to change the search experience.
API Endpoints
The SmC package uses both Empathy Platform internal and external endpoints.
Internal endpoints
These are the local endpoints that can be consulted:
/search
Main endpoint to execute queries and retrieve results from the movie catalog.
Example request:
http://localhost:8080/query/imdb/search?query=wonderland&lang=en
Example response:
{
"catalog": {
"content": [
{
"primaryTitle": "Alice in Wonderland",
"runtimeMinutes": 9,
"__images": [
"https://m.media-amazon.com/images/M/MV5BODQyZWYxZWYtNDRmZC00ZjQxLTlhZGQtM2JmZGNlYjViNGU5XkEyXkFqcGdeQXVyNDk0MDg4NDk@._V1_.jpg"
],
"__url": "https://www.imdb.com/title/tt0000420",
"startYear": 1903,
"description": "Alice in Wonderland",
"type": "short",
"score": 1,
"genres": [
"Fantasy"
],
"__id": "tt0000420",
"__prices": {
"current": {
"value": 13.99
}
},
"isAdult": false
}
],
"numFound": 1,
"facets": [
{
"facet": "genres",
"label": "genres",
"type": "value",
"values": [
{
"id": "fantasy",
"value": "fantasy",
"count": 1,
"filter": "genres:fantasy"
}
]
}
]
},
"direct": {
"content": []
},
"banner": {
"content": []
},
"promoted": {
"content": [
{
"image_url": "https://miro.medium.com/v2/resize:fit:946/1*ZrKqqzr9ZwjpuP1KkJ69eQ.jpeg",
"id": "661e868686920a77214c90c4",
"position": 1,
"title": "Alice In Wonderland",
"url": "https://en.wikipedia.org/wiki/Alice%27s_Adventures_in_Wonderland"
}
]
}
}
/empathize
Endpoint to retrieve results of popular searches and query suggestions.
Example request for query suggestions:
http://localhost:8080/query/imdb/empathize?query=wonderland&lang=en
Example request for popular searches:
http://localhost:8080/query/imdb/empathize?lang=en
Example response:
{
"topTrends": {
"content": [
{
"keywords": "wonderland"
},
{
"keywords": "wonderland adventures"
}
]
}
}
/topclicked
Endpoint to retrieve top product recommendations.
Example request:
<http://localhost:8080/query/imdb/topclicked?lang=en>
Example response:
{
"topclicked": {
"content": [
{
"primaryTitle": "Alice in Wonderland",
"runtimeMinutes": 9,
"__images": [
"https://m.media-amazon.com/images/M/MV5BODQyZWYxZWYtNDRmZC00ZjQxLTlhZGQtM2JmZGNlYjViNGU5XkEyXkFqcGdeQXVyNDk0MDg4NDk@._V1_.jpg"
],
"__url": "https://www.imdb.com/title/tt0000420",
"startYear": 1903,
"description": "Alice in Wonderland",
"type": "short",
"score": 1,
"genres": [
"Fantasy"
],
"__id": "tt0000420",
"__prices": {
"current": {
"value": 13.99
}
},
"isAdult": false
}
],
"numFound": 1,
"facets": [
{
"facet": "genres",
"label": "genres",
"type": "value",
"values": [
{
"id": "fantasy",
"value": "fantasy",
"count": 1,
"filter": "genres:fantasy"
}
]
}
]
},
"direct": {
"content": []
},
"banner": {
"content": []
},
"promoted": {
"content": [
{
"image_url": "https://miro.medium.com/v2/resize:fit:946/1*ZrKqqzr9ZwjpuP1KkJ69eQ.jpeg",
"id": "661e868686920a77214c90c4",
"position": 1,
"title": "Alice In Wonderland",
"url": "https://en.wikipedia.org/wiki/Alice%27s_Adventures_in_Wonderland"
}
]
}
}
External endpoints
The following endpoints are hosted on Empathy Platform's servers as they depend on internal tools such as Related Tags or Next Queries. You can't customize them, but you can see how they work:
/nextqueries
Endpoint to retrieve next queries (queries performed by shoppers related to the main query).
Example request:
<https://api.staging.empathy.co/nextqueries/imdb?query=wonderland&lang=en>
Example response:
{
"status": 200,
"data": {
"nextqueries": [
{
"query": "cinderella",
"position": 0,
"source": "CURATED"
},
{
"query": "hamlet",
"position": 1,
"source": "CURATED"
}
]
}
}
/relatedtags
Endpoint to retrieve terms or keywords used by shoppers to refine the main query.
Example request:
<https://api.staging.empathy.co/relatedtags/imdb?query=wonderland&lang=en>
Example response:
{
"status": 200,
"data": {
"relatedtags": [
{
"query": "alice in wonderland",
"tag": "alice in",
"position": 0,
"source": "CURATED"
}
]
}
}