Introduction

Manticore Search supports two formats of HTTP JSON requests: a common Manticore format and an Elasticsearch-like one. The latter has the same syntax as queries in Elasticsearch.

You can use the Elasticsearch-like format for adding new documents to a table as well as for replacing, updating and deleting already existing documents.

Lets's look at some basic examples of Elasticsearch-like requests.

Adding documents

Let's create a test table and add new documents to it.

curl -s localhost:9308/cli -d "CREATE TABLE products(title TEXT, price FLOAT)"

There're two ways of adding a document to a table in the Elasticsearch-like way. To do this, you can use _create or _doc queries.

POST /products/_create/1
{
  "title": "Red Bag with Tassel",
  "price": 19.85
}
POST /products/_doc/2
{
"title": "Red Bag with Tassel",
"price": 19.85
}

Let's run these queries:

curl -s localhost:9308/products/_create/1 -d ' { "title": "Red Bag with Tassel", "price": 19.85 } ' | jq

curl -s localhost:9308/products/_doc/2 -d ' { "title": "Red Bag with Tassel", "price": 19.85 } ' | jq

And see the result:

curl -s localhost:9308/cli -d "SELECT * FROM products"

Note that in both cases the id of a new document is set explicitly in the request path. Instead, if you want it to be auto-generated, you should use the following syntax:

POST /products/_doc/
{
  "title": "Red Bag with Tassel",
  "price": 19.85
}

curl -s localhost:9308/products/_doc/ -d ' { "title": "Red Bag with Tassel", "price": 19.85 } ' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"

Note that the use of _create is not supported by this variant of syntax. Also note that only POST method is allowed here.

Replacing documents

To replace an existing document, use the following syntax:

POST /products/_doc/1
{
  "title": "Yellow Bag with Tassel",
  "price": 50.00
}

curl -s localhost:9308/products/_doc/1 -d ' { "title": "Red Bag with Tassel", "price": 50.00 } ' | jq

We can verify that the document with id=1 has been successfully replaced by running the following command:

curl -s localhost:9308/cli -d "SELECT * FROM products"

Note that only the _doc syntax is allowed for replacing. For example, the following request will produce an error:

curl -s localhost:9308/products/_create/2 -d ' { "title": "Red Bag with Tassel", "price": 100.00 } ' | jq

Also, the replace request can be made with PUT method:

curl -sX PUT localhost:9308/products/_doc/2 -d ' { "title": "Red Bag with Tassel", "price": 150.00 } ' | jq

We can verify the changes by running the same SELECT command as before.

curl -s localhost:9308/cli -d "SELECT * FROM products"

Bulk requests

You can execute bulk requests using the Elasticsearch-like format as well. Let's empty out test table first:

curl -s localhost:9308/cli -d "TRUNCATE TABLE products"

and run the examples of bulk requests. To create new documents in bulk, use the following syntax:

POST /_bulk
-H "Content-Type: application/x-ndjson" -d '
{ "index" : { "_index" : "products" } }
{ "title" : "Yellow Bag", "price": 12 }
{ "create" : { "_index" : "products" } }
{ "title" : "Red Bag", "price": 12.5, "id": 3 }
{ "create" : { "_index" : "products", "_id": "4" } }
{ "title" : "Red Bag", "price": 12.5 }
'

Note that, when executing create bulk requets, you can specify the id of an inserted document in both Manticore:

{ "title" : "Red Bag", "price": 12.5, "id": 3 }

and Elastic-like ways:

{ "create" : { "_index" : "products", "_id": "4" } }

However, you cannot use both ways for the same document simultaneously.

Also note that the Content-type header must be set as application/x-ndjson in all bulk requests.

curl -s localhost:9308/_bulk -H 'Content-Type: application/x-ndjson' -d '
{ "index" : { "_index" : "products" } }
{ "title" : "Yellow Bag", "price": 12 }
{ "create" : { "_index" : "products" } }
{ "title" : "Red Bag", "price": 12.5, "id": 3 }
{ "create" : { "_index" : "products", "_id": "4" } }
{ "title" : "Red Bag", "price": 12.5 }
' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"

To update existing documents in bulk, use:

POST /_bulk
-H "Content-Type: application/x-ndjson" -d '
{ "update" : { "_index" : "products", "_id": "3" } }
{ "doc" : { "price": 5 }
{ "update" : { "_index" : "products", "_id": "4" } }
{ "doc" : { "price": 5 }
'

curl -s localhost:9308/_bulk -H 'Content-Type: application/x-ndjson' -d'
{ "update" : { "_index" : "products", "_id": "3" } }
{ "doc" : { "price": 5 } }
{ "update" : { "_index" : "products", "_id": "4" } }
{ "doc" : { "price": 5 } }
' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"

Finally, to delete existing documents in bulk, use:

POST /_bulk
-H "Content-Type: application/x-ndjson" -d '
{ "delete" : { "_index" : "products", "_id": "3" } }
{ "delete" : { "_index" : "products", "_id": "4" } }
'

curl -s localhost:9308/_bulk -H 'Content-Type: application/x-ndjson' -d'
{ "delete" : { "_index" : "products", "_id": "3" } }
{ "delete" : { "_index" : "products", "_id": "4" } }
' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"

Using the Auto schema mechanism

Note that you don't need for a table to exist before adding documents to it. If it does not yet exist, Manticore will attempt to create it automatically. This feature is enabled by default. For more information, see the Auto schema course.

Here are some examples of Elasticsearch-like requests using the auto schema mechanism.

Let's delete our products table:

curl -s localhost:9308/cli -d "DROP TABLE products"

And try to insert a document to it again:

curl -s localhost:9308/products/_create/1 -d ' { "title": "Red Bag with Tassel", "price": 19.85 } ' | jq

curl -s localhost:9308/cli -d "DESCRIBE products"

curl -s localhost:9308/cli -d "SELECT * FROM products"

As we see, the table's been successfully created and the document's been added to it.

Another example with the _doc syntax:

curl -s localhost:9308/cli -d "DROP TABLE products"

curl -s localhost:9308/products/_doc/1 -d ' { "title": "Red Bag with Tassel", "price": 50.00 } ' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"

You can use bulk requests with auto schema as well:

curl -s localhost:9308/cli -d "DROP TABLE products"

curl -s localhost:9308/_bulk -H 'Content-Type: application/x-ndjson' -d '
{ "index" : { "_index" : "products" } }
{ "title" : "Yellow Bag", "price": 12 }
{ "create" : { "_index" : "products" } }
{ "title" : "Red Bag", "price": 12.5, "id": 3 }
{ "create" : { "_index" : "products", "_id": "4" } }
{ "title" : "Red Bag", "price": 12.5 }
' | jq

curl -s localhost:9308/cli -d "SELECT * FROM products"