Getting Started

This is a quick start document for Mach5. It lets a user create a store, store route, warehouse, add index and sample data, run sample queries and searches

Prerequisites

• This document assumes that Mach5 is deployed and running successfully
• Mach5 UI is accessible at http://localhost:8888

In Mach5 - Namespace default is already pre-existing

Add a Store

Store is the S3 bucket configuration where Mach5 will store index data

• Click on Stores on the left panel of Mach5 UI
• This opens the following page:

• You can add a new store by clicking the + icon on rightmost corner of the page
• Name :Type in name of the new store, eg. teststore
• Store Type :Select S3
• Bucket : Type name of the already existing bucket in S3, eg. testbucket
• Prefix : Specify a prefix name, eg. mach5store. All data will be stored under this prefix inside testbucket in S3
• S3 Endpoint : Keep it empty. On AWS EKS, configuration of S3 Endpoint is not needed.
• If you are using local S3 deployment, for eg Minio then you need to define this endpoint, eg. http://<Minio host>:<Minio port>
• DynamoDB Endpoint : Keep it empty. On AWS EKS, configuration of DynamoDB Endpoint is not needed
• If you are not on AWS EKS, specify this as http://dynamodb:8000
• Click on Save

• Verify that the Store is created, the page shows the details as below for teststore

Add a Store Route

Store Route applies to the index name pattern to use to identify which store should be used to write the index data

• Click on the Store Routes on the left panel of Mach5 UI
• This opens the following page:

Adding A New Store Route

• You can add a store route by clicking the + icon on rightmost corner of the page
• Pattern : Keep default pattern as .*
• Stores : Select the teststore that we have created
• Priority : Keep the default value as 10
• Click on Save

• Verify that the Store Routes page shows the details as below. The Store Route id is automatically generated

Add a Warehouse

Warehouse creates the compute resource for running queries on the index data

• Click on Warehouses on the left panel of Mach5 UI
• This opens the following page:

Adding a new Warehouse

You can add a new warehouse by clicking the + icon on rightmost corner of the page

• Name : Type in name of the new Warehouse, say testwarehouse
• Enabled : Keep default checkbox selection as selected
• Enable Dashboards : Keep default checkbox selection as selected
• Immutable : Keep default checkbox selection as deselected
• Performance Options
• Enable Cache Warning : Keep default checkbox selection as selected
• Segment Cache Capacity : Keep as empty
• Index Access Memory Limit : Keep as empty
• Read Cache Size Limit : Keep as empty
• Local Parallelism : Keep as empty
• Number of OpenSearch API Gateways : Keep as empty
• Number of Workers : Keep default as 1
• Replicas : Keep as empty
• Click on Save

• Verify that the Warehouse addition is sucessful
• The Warehouses page shows the details as below. The testwarehouse id is automatically generated

The warehouse page for testwarehouse has two links for Dashboards and OpenSearch API

Disable a Warehouse

When not in use, Warehouse can be disabled so that resources are not used unnecessarily. Given below are steps to disable a warehouse

• Navigate to Warehouse page, existing warehouse are listed
• Click on edit action for testwarehouse. This edit symbol is next to delete button
• Deselect checkbox Enabled
• Click save
• testwarehouse is now disabled

• Verify that testwarehouse is disabled
• Click on the testwarehouse in Warehouses page and verify that Enabled field is false

Note: Disabled warehouse can be enabled anytime it needs to be re-used

• Navigate to the Warehouse page
• Click on edit action for testwarehouse.
• Select checkbox Enabled
• Click save

Dashboard of a Warehouse

Click on testwarehouse -> Dashboards link -> /warehouse/default/testwarehouse/dashboards/

Dashboards page will be opened for usage as shown below

Add Sample data

• Click "Add Data" for say Sample flight data

You can choose the any pre-built dataset of your choice

• Once added, click "View Data" to see a pre-built dashboard

• View data - Sample flights data

Dev Tools to Run Queries in Dashboard

You can run queries directly from the Dashboard using Dev Tools.

• Click on “Interact with OpenSearch API”

• OR Click on Dev Tools from side bar

Create an Index

• We are creating an index named products
• On the left pane, type/paste given below data

PUT products
{
    "mappings": {
        "properties": {
        "name": { "type": "text" },
        "category": { "type": "keyword" },
        "price": { "type": "float" },
        "stock": { "type": "boolean" }
        }
    }
}

• Keep cursor on same line as PUT products and click on Play button
• Check output in right pane

Add data via Bulk API

• We are adding 3 documents in bulk in the index products that we previously created
• On the left pane, type/paste given below data

POST _bulk
{ "index": { "_index": "products", "_id": 1 }}
{ "name": "Smartphone", "category": "electronics", "price": 999.99, "stock": true }
{ "index": { "_index": "products", "_id": 2 }}
{ "name": "Laptop", "category": "electronics", "price": 1299.00, "stock": false }
{ "index": { "_index": "products", "_id": 3 }}
{ "name": "Shoes", "category": "apparel", "price": 299.00, "stock": true }
                        

• Keep cursor on same line as POST _bulk and click on Play button
• Check output in right pane

Query all documents

• We are querying the documents we added in the index products
• On the left pane, type/paste given below data

GET products/_search
{
"query": {
    "match_all": {}
}
}

• Keep cursor on same line as GET products/_search and click on Play button
• Check output in right pane

Similarly run all other such queries in Dev Tools

Count Documents

GET products/_count

Filter by category

GET products/_search
{
"query": {
    "term": {
    "category": "electronics"
}
}
}

Aggregate by average price

GET products/_search
{
    "size": 0,
    "aggs": {
    "average_price": {
    "avg": {
    "field": "price"
    }
}
}
}

Delete the index

DELETE products