Link Search Menu Expand Document Documentation Menu
Documentation

Communicate with Lucenia

You can communicate with Lucenia using the REST API or one of the Lucenia language clients. This page introduces the Lucenia REST API. If you need to communicate with Lucenia in your programming language, see the Clients section for a list of available clients.

Lucenia REST API

You interact with Lucenia clusters using the REST API, which offers a lot of flexibility. Through the REST API, you can change most Lucenia settings, modify indexes, check cluster health, get statistics—almost everything. You can use clients like cURL or any programming language that can send HTTP requests.

You can send HTTP requests in your terminal or in the Dev Tools console in OpenSearch Dashboards.

Sending requests in a terminal

When sending cURL requests in a terminal, provide the username and password in the request:

curl -X GET "http://localhost:9200/_cluster/health" -ku admin:<custom-admin-password>

The default username is admin, and the password is set in your docker-compose.yml file in the LUCENIA_INITIAL_ADMIN_PASSWORD=<custom-admin-password> setting.

Lucenia generally returns responses in a flat JSON format by default. For a human-readable response body, provide the pretty query parameter:

curl -XGET "http://localhost:9200/_cluster/health?pretty" -ku admin:<custom-admin-password>

For more information about pretty and other useful query parameters, see Common REST parameters.

For requests that contain a body, specify the Content-Type header and provide the request payload in the -d (data) option:

curl -XGET "http://localhost:9200/students/_search?pretty" -ku admin:<custom-admin-password> -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }
}'

Sending requests in Dev Tools

This example walks through the Dev Tools console in OpenSearch Dashboards. The syntax required is a simplified format compared to the cURL command. To send requests in Dev Tools, use the following steps:

  1. Access OpenSearch Dashboards by opening http://localhost:5601/ in a web browser on the same host that is running your Lucenia cluster. The default username is admin, and the password is set in your docker-compose.yml file in the LUCENIA_INITIAL_ADMIN_PASSWORD=<custom-admin-password> setting.
  2. On the top menu bar, go to Management > Dev Tools.
  3. In the left pane of the console, enter the following request: 
     GET _cluster/health

  4. Choose the triangle icon on the upper right of the request to submit the query. You can also submit the request by pressing Ctrl+Enter (or Cmd+Enter for Mac users). To learn more about using the OpenSearch Dashboards console for submitting queries, see Running queries in the console.

In the following sections, and in most of the Lucenia documentation, requests are presented in the Dev Tools console format.

Indexing documents

To add a JSON document to an Lucenia index (that is, to index a document), you send an HTTP request with the following header:

PUT https://<host>:<port>/<index-name>/_doc/<document-id>

For example, to index a document representing a student, you can send the following request:

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.89,
  "grad_year": 2022
}

Once you send the preceding request, Lucenia creates an index called students and stores the ingested document in the index. If you don’t provide an ID for your document, Lucenia generates a document ID. In the preceding request, the document ID is specified as the student ID (1).

To learn more about indexing, see Managing indexes.

Dynamic mapping

When you index a document, Lucenia infers the field types from the JSON types submitted in the document. This process is called dynamic mapping. For more information, see Dynamic mapping.

To view the inferred field types, send a request to the _mapping endpoint:

GET /students/_mapping

Lucenia responds with the field type for each field:

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "long"
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

Lucenia mapped the numeric fields to the float and long types. Notice that Lucenia mapped the name text field to text and added a name.keyword subfield mapped to keyword. Fields mapped to text are analyzed (lowercased and split into terms) and can be used for full-text search. Fields mapped to keyword are used for exact term search.

Lucenia mapped the grad_year field to long. If you want to map it to the date type instead, you need to delete the index and then recreate it, explicitly specifying the mappings. For instructions on how to explicitly specify mappings, see Index settings and mappings.

Searching for documents

To run a search for the document, specify the index that you’re searching and a query that will be used to match documents. The simplest query is the match_all query, which matches all documents in an index:

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

Lucenia returns the indexed document:

{
  "took": 12,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "students",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "John Doe",
          "gpa": 3.89,
          "grad_year": 2022
        }
      }
    ]
  }
}

For more information about search, see Search your data.

Updating documents

In Lucenia, documents are immutable. However, you can update a document by retrieving it, updating its information, and reindexing it. You can update an entire document using the Index Document API, providing values for all existing and added fields in the document. For example, to update the gpa field and add an address field to the previously indexed document, send the following request:

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.91,
  "grad_year": 2022,
  "address": "123 Main St."
}

Alternatively, you can update parts of a document by calling the Update Document API:

POST /students/_update/1/
{
  "doc": {
    "gpa": 3.91,
    "address": "123 Main St."
  }
}

For more information about partial document updates, see Update Document API.

Deleting a document

To delete a document, send a delete request and provide the document ID:

DELETE /students/_doc/1

Deleting an index

To delete an index, send the following request:

DELETE /students

Index mappings and settings

Lucenia indexes are configured with mappings and settings:

  • A mapping is a collection of fields and the types of those fields. For more information, see Mappings and field types.
  • Settings include index data like the index name, creation date, and number of shards. For more information, see Configuring Lucenia.

You can specify the mappings and settings in one request. For example, the following request specifies the number of index shards and maps the name field to text and the grad_year field to date:

PUT /students
{
  "settings": {
    "index.number_of_shards": 1
  }, 
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "grad_year": {
        "type": "date"
      }
    }
  }
}

Now you can index the same document that you indexed in the previous section:

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.89,
  "grad_year": 2022
}

To view the mappings for the index fields, send the following request:

GET /students/_mapping

Lucenia mapped the name and grad_year fields according to the specified types and inferred the field type for the gpa field:

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "date"
        },
        "name": {
          "type": "text"
        }
      }
    }
  }
}

Once a field is created, you cannot change its type. Changing a field type requires deleting the index and recreating it with the new mappings.

Further reading

Next steps

350 characters left

Have a question? .