You can use the dotCMS REST API to manage indexes, performing all the same operations that are documented in the Managing Site Indexes with Elastic Search documentation. Note: You can verify the results of your REST API calls by viewing index information in the dotCMS backend.
User Authentication
All of the following examples assume the server is running on localhost:8082, and the user has been authenticated on your dotCMS instance as a user with permissions to modify the indexes.
In all of the following example commands:
- Replace
localhost:8082with the domain name and port of your dotCMS instance. - Provide actual values where optional values are indicated (in square brackets).
- You can also authenticate users using standard dotCMS REST API authentication (passing user and password as parameters, or using cookie based sessions).
- Admin passwords are assumed to be
admin, as on the demo site and starters prior to version 22.06. For versions 22.06 or later, this is no longer the default; now, admin passwords default to a random string generated on first startup and displayed in the server logs. This starter password can also be pre-configured through theDOT_INITIAL_ADMIN_PASSWORDenvironment variable.
Snapshot an Index
The following curl command downloads an index with name live_20160925211511:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/snapshot/index/live_20160925211511 > live_20160925211511.zip
Restore an Index Snapshot
The following example restores an index which was previously downloaded.
Note:
- The index to be restored must be sent in zip format.
- Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.
curl --user admin@dotcms.com:admin -F file=@live_20160925211511.zip -XPOST http://localhost:8082/api/v1/esindex/restoresnapshot/
Download an Index (Deprecated — See Snapshot an Index)
The following curl command downloads an index with name working_20130628092243:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/working_20130628092243 > file.zip
To download the current live or working index, pass live or working, respectively, as the index name.
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/live > live.zip
Restore an Index (Deprecated — See Restore an Index Snapshot)
The following example restores an index which was previously downloaded.
Note:
- The index to be restored must be sent in zip format.
- Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.
The URI parameter clear deletes all the documents in the index before restoring (completely overwriting the existing index with the index being restored). This parameter defaults to false.
curl --user admin@dotcms.com:admin -F file=@file.zip -XPUT http://localhost:8082/api/v1/esindex/restore/index/working_20130705193521/clear/true
Create an Index (Deprecated — See Snapshot an Index)
/api/v1/esindex/create[/parameters]
Parameters
| Parameter | Accepted Values | Description |
|---|---|---|
/live/[value] | true, false | Creates a live (true) or working (false) index. |
shards | Integer | Specifies the number of shards for the new index. |
index | Name (String) | If specified, sets the index name. If not specified, a default index name will be generated. |
/alias/[name] | Alias Name (String) | If specified, sets the index from an alias of the index. |
Response:
The name of the new index in text/plain format.
Example 1
The following curl command creates a new working index with 2 shards and a default index name:
Command:
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/false/shards/2
Response:
live_20130707211119
Example 2
The following curl command creates a new live index with 2 shards and a custom index name:
Command:
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/true/shards/2/index/fandango
Response:
live_fandango
Reindex
Updates an existing index. Usage:
/api/v1/esindex/reindex?{parameter=this&other_parameter=that}
Depending on the HTTP method employed, this can perform one of the following operations, with the associated parameters.
- Retrieve reindexation progress (via GET) Param | Type ——|—– filter | string page | int per_page | int
- Start a reindex (via POST) Param | Type ——|—– shards | int contentType | string
- Stop a reindex (via DELETE)
Example 1: Getting Reindexation Progress
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/reindex?filter=news&page=4
Example 2: Starting a Reindex
curl --user admin@dotcms.com:admin -XPOST http://localhost:8082/api/v1/esindex/reindex?shards=-15283749&contentType=DOTALL
Example 3: Halting a Reindex
curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/reindex
Clear an Index
Clears all contents out of the specified index (but does not delete the index).
/api/v1/esindex/clear/index/[index_name]
Example
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/clear/index/working_20130707223633
Delete an Index
Deletes the specified index.
Example
curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/index/working_20130707223633
Activate an Index
When used on a content index, sets the specified index to the active index. When used on a sitesearch index, makes the specified index the default index.
Example
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/activate/index/working_20130707233404
Deactivate an Index
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/deactivate/index/working_20130707233404
Update Replica
Duplicates the specified index. The number of copies of an index in a cluster is equal to the number of replicas plus one; so, for example, if there is 1 replica then there will be 2 copies of the index in the cluster.
Special Note: This API command requires the Manual Cluster Configuration settings, otherwise the command is automatically disabled.
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/updatereplica/index/working_20130707233404/replicas/1
Close an Index
Closes file descriptors and releases memory used to operate over the index. After this operation is performed, the index will not be available for queries until it is reopened with the open operation. This operation allows you to stop using an index without deleting it; however a closed index will still take up the full amount of drive space of a normal index.
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/close/index/working_20130707233404
Open an Index
Re-open an index which has been closed.
curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/open/index/working_20130707233404
Get Active Index
Returns the name of the current live or working index.
The working index (note the “type” parameter)
Example: Get Current Working Index
Command:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/working
Response:
working_20130628092243
Example: Get Current Live Index
Command:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/live
Response:
live_20130628092243
Get Document Count
Returns the number of documents stored in the specified index.
Example
Command:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/docscount/index/working_20130628092243
Response:
654
List Indices
Returns a list of all indices on the system. Uses json format, which can be easily parsed with the JSONTool.
Example
Command:
curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/indexlist/
Response:
["live_20130707233408","working_20130707233404","working_20130628092243","live_20130628092243"]
