Connect to Solr via CLI

Solr Server components installed on ADH hosts provide the /usr/lib/solr/bin/solr script that allows you to run CLI commands to manage your Solr cluster. Although it is recommended to control the activity of your Solr cluster via ADCM, some of the Solr CLI commands can be useful to perform actions that are unavailable in the Solr Admin UI. These commands are highlighted further in the article.

The general usage of the /usr/lib/solr/bin/solr script is as follows:

$ /usr/lib/solr/bin/solr <COMMAND> [<PARAMETERS>]

The detailed information about all the supported COMMAND and PARAMETERS values is available in the Solr reference documentation. To get help information for a particular command, use the following syntax:

$ /usr/lib/solr/bin/solr <COMMAND> -help

For more verbose command output, append the -V flag to your commands.

NOTE
As an ADH service, Solr always runs in the SolrCloud mode. Thus, some commands related to the standalone mode may have no effect at all.

Сontrol commands: start, stop, restart

Although the /usr/lib/solr/bin/solr script accepts commands like start, stop, and restart, it is highly recommended to use ADCM to perform these actions. Under the hood, ADCM invokes these commands to control Solr processes. However, ADCM additionally takes care about running these commands properly. For example, setting environment variables, submitting commands with sufficient user permissions, handling errors, etc.

Running start, stop, and restart commands via /usr/lib/solr/bin/solr may lead to Solr startup issues and the malfunction of the entire Solr cluster.

System information commands

Solr provides several commands that might be useful for getting status information and diagnosing your Solr cluster. These commands are shown below:

$ /usr/lib/solr/bin/solr version
$ /usr/lib/solr/bin/solr status
$ /usr/lib/solr/bin/solr healthcheck [<PARAMETERS>]

Command parameters

Command: healthcheck
Parameter Description

-c <collection_name>

The name of the collection

-z <zk_connection_string>

Optional. The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string

Examples

Get Solr version
$ /usr/lib/solr/bin/solr version

Sample output:

8.11.2
Get Solr node status
$ /usr/lib/solr/bin/solr status

Sample output:

Found 1 Solr nodes:

Solr process 23658 running on port 8983
{
  "solr_home":"/srv/solr/server",
  "version":"8.11.2 3cb85f40e394dcfb50fe77310908cce385381ba2 - jenkins - 2024-03-20 17:52:09",
  "startTime":"2024-05-23T22:52:07.271Z",
  "uptime":"0 days, 0 hours, 0 minutes, 6 seconds",
  "memory":"105.9 MB (%21.6) of 491 MB",
  "cloud":{
    "ZooKeeper":"ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-7.solr.server",
    "liveNodes":"3",
    "collections":"0"}}
Run a collection healthcheck
$ /usr/lib/solr/bin/solr healthcheck -c test_collection

Sample output:

{
  "collection":"test_collection",
  "status":"healthy",
  "numDocs":0,
  "numShards":2,
  "shards":[
    {
      "shard":"shard1",
      "status":"healthy",
      "replicas":[
        {
          "name":"core_node3",
          "url":"http://ka-adh-3.ru-central1.internal:8983/solr/test_collection_shard1_replica_n1/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"143.6 MB (%29.4) of 489 MB"},
        {
          "name":"core_node5",
          "url":"http://ka-adh-1.ru-central1.internal:8983/solr/test_collection_shard1_replica_n2/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"67.9 MB (%14) of 485 MB",
          "leader":true},
        {
          "name":"core_node7",
          "url":"http://ka-adh-2.ru-central1.internal:8983/solr/test_collection_shard1_replica_n4/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"63 MB (%13) of 485 MB"}]},
    {
      "shard":"shard2",
      "status":"healthy",
      "replicas":[
        {
          "name":"core_node9",
          "url":"http://ka-adh-3.ru-central1.internal:8983/solr/test_collection_shard2_replica_n6/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"144.8 MB (%29.6) of 489 MB"},
        {
          "name":"core_node11",
          "url":"http://ka-adh-1.ru-central1.internal:8983/solr/test_collection_shard2_replica_n8/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"69.3 MB (%14.3) of 485 MB"},
        {
          "name":"core_node12",
          "url":"http://ka-adh-2.ru-central1.internal:8983/solr/test_collection_shard2_replica_n10/",
          "numDocs":0,
          "status":"active",
          "uptime":"0 days, 11 hours, 21 minutes, 7 seconds",
          "memory":"65.1 MB (%13.4) of 485 MB",
          "leader":true}]}]}

Collection & core commands

You can use the /usr/lib/solr/bin/solr script to create and delete Solr collections.

The usage is as follows:

$ /usr/lib/solr/bin/solr create [<PARAMETERS>]
$ /usr/lib/solr/bin/solr create_collection [<PARAMETERS>]
$ /usr/lib/solr/bin/solr delete [<PARAMETERS>]
NOTE
In ADH, the Solr’s create and create_collection commands are equivalent. Running create detects the current Solr mode (which is always SolrCloud in ADH) and invokes the create_collection command with the same set of parameters.

Command parameters

Commands: create/create_collection
Parameter Description

-c <collection>

A name for the new collection

-d <conf_dir>

Specifies a configuration directory (configset) to use when creating a collection. If not specified, the /usr/lib/solr/server/solr/configsets/_default configset is used

-n <config_name>

The name used to upload the configuration directory to ZooKeeper. By default, the collection name is used

-s <shards>, -shards <shards>

The number of shards to split the collection, defaults to 1

-rf <replicas>, -replicationFactor <replicas>

The number of copies of each document in the collection. Defaults to 1, assuming no replication

Command: delete
Parameter Description

-c <collection>

The name of the collection to delete

-deleteConfig <true|false>

Defines whether to delete the configuration directory from ZooKeeper. The default behavior is true. If a ZooKeeper configuration directory is already used by another collection, it will not be deleted even if you pass -deleteConfig true

Examples

Create a basic collection
$ /usr/lib/solr/bin/solr create_collection -c test_collection1

Sample output:

Created collection 'test_collection1' with 1 shard(s), 1 replica(s) with config-set 'test_collection1'
Create a multi-sharded, replicated collection
$ /usr/lib/solr/bin/solr create_collection -c test_collection -shards 2 -replicationFactor 3 -V

Sample output:

Connecting to ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server ...
INFO  - 2024-05-28 08:23:31.128; org.apache.solr.common.cloud.ConnectionManager; Waiting for client to connect to ZooKeeper
INFO  - 2024-05-28 08:23:31.145; org.apache.solr.common.cloud.ConnectionManager; zkClient has connected
INFO  - 2024-05-28 08:23:31.145; org.apache.solr.common.cloud.ConnectionManager; Client is connected to ZooKeeper
INFO  - 2024-05-28 08:23:31.158; org.apache.solr.common.cloud.ZkStateReader; Updated live nodes from ZooKeeper... (0) -> (3)
INFO  - 2024-05-28 08:23:31.269; org.apache.solr.client.solrj.impl.ZkClientClusterStateProvider; Cluster at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server ready
Uploading /usr/lib/solr/server/solr/configsets/_default/conf for config test_collection to ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server

Creating new collection 'test_collection' using command:
http://ka-adh-1.ru-central1.internal:8983/solr/admin/collections?action=CREATE&name=test_collection&numShards=2&replicationFactor=3&maxShardsPerNode=-1&collection.configName=test_collection

{
  "responseHeader":{
    "status":0,
    "QTime":2325},
  "success":{
    "ka-adh-1.ru-central1.internal:8983_solr":{
      "responseHeader":{
        "status":0,
        "QTime":1199},
      "core":"test_collection_shard2_replica_n8"},
    "ka-adh-3.ru-central1.internal:8983_solr":{
      "responseHeader":{
        "status":0,
        "QTime":1610},
      "core":"test_collection_shard1_replica_n1"},
    "ka-adh-2.ru-central1.internal:8983_solr":{
      "responseHeader":{
        "status":0,
        "QTime":1822},
      "core":"test_collection_shard2_replica_n10"}}}
Delete a collection
$ /usr/lib/solr/bin/solr delete -c test_collection1

Sample output:

{
  "responseHeader":{
    "status":0,
    "QTime":297},
  "success":{
    "ka-adh-1.ru-central1.internal:8983_solr":{"responseHeader":{
        "status":0,
        "QTime":50}},
    "ka-adh-3.ru-central1.internal:8983_solr":{"responseHeader":{
        "status":0,
        "QTime":119}},
    "ka-adh-2.ru-central1.internal:8983_solr":{"responseHeader":{
        "status":0,
        "QTime":130}}}}


Deleted collection 'test_collection1' using command:
http://ka-adh-1.ru-central1.internal:8983/solr/admin/collections?action=DELETE&name=test_collection1

Cores

Since ADH Solr Server components always run in the SolrCloud mode, Solr manages the data in the form of collections (a single search index distributed across multiple cluster nodes) rather than cores. For this reason, the core management commands have no effect and are beyond the scope of this article.

Authentication

Using the /usr/lib/solr/bin/solr script, you can enable and disable Solr authentication.

The usage is as follows:

$ /usr/lib/solr/bin/solr auth enable [<PARAMETERS>]
$ /usr/lib/solr/bin/solr auth disable

Command parameters

Command: auth enable
Parameter Description

-authConfDir <dir>

Specifies a directory to store configuration files related to authentication

-blockUnknown <true|false>

Blocks access to all Solr endpoints for unauthenticated users

-credentials <username:password>

The credentials pair in the username:password format

-prompt <true|false>

Prompts to provide the credentials. Either the -prompt or -credentials option must be provided

-type <type>

Defines the authentication mechanism (basicAuth or kerberos) to enable. Defaults to basicAuth

-updateIncludeFileOnly <true|false>

Updates only the solr.in.sh file without actually enabling or disabling the authentication

-z <zkString>

The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string

-d <dir>

Specifies the Solr server directory (defaults to /usr/lib/solr/server/). Use this option only if you have customized your Solr home directory path

-s <dir>

Specifies the Solr home directory to store credentials and authentication configuration files (for example, basicAuth.conf)

Examples

Enable basic authentication

 
Before running the following example command, ensure that a security.json file is uploaded to ZooKeeper. You can upload the file using ZooKeeper CLI or using the /usr/lib/solr/server/scripts/cloud-scripts/zkcli.sh script.

$ /usr/lib/solr/bin/solr auth enable \
    -type basicAuth \
    -prompt true \
    -z ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-6.solr.server \
    -blockUnknown true

Sample output:

Security is enabled. You can disable it with 'bin/solr auth disable'. Existing security.json:
{"authentication":{"blockUnknown":true,"class":"solr.BasicAuthPlugin","realm":"My Solr users","forwardCredentials":false},"authorization":{"class":"solr.RuleBasedAuthorizationPlugin","permissions":[{"name":"security-edit","role":"admin"}],"user-role":{"solr":"admin"}}}
Disable authentication
$ /usr/lib/solr/bin/solr auth disable

Sample output:

Security has been disabled.
Please remove any SOLR_AUTH_TYPE or SOLR_AUTHENTICATION_OPTS configuration from solr.in.sh/solr.in.cmd.

ZooKeeper commands

The /usr/lib/solr/bin/solr script supports commands to interact with ZooKeeper. For example, the zk upconfig and zk downconfig commands are used to upload/download Solr configsets from ZooKeeper. The usage is as follows:

$ /usr/lib/solr/bin/solr zk upconfig [<PARAMETERS>]
$ /usr/lib/solr/bin/solr zk downconfig [<PARAMETERS>]

Command parameters

Commands: zk upconfig/zk downconfig
Parameter Description

-n <name>

A name for the configset that has to be uploaded or downloaded from ZooKeeper. All the uploaded configsets are available in the Solr Admin UI. Using an existing name overwrites the configset in ZooKeeper

-d <configset_dir>

The path to the configset directory to upload/download. A configset directory must contain the conf directory with the solrconfig.xml file inside

-z <zk_host>

Optional. The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string

NOTE
Uploading a configset to ZooKeeper does not automatically make the changes effective. If you modify a configset already used by a collection, use the RELOAD collection command to reload any collection that uses this configset.

Also, there are several zk …​ commands that might be useful to perform common ZooKeeper operations. The usage is shown below:

$ /usr/lib/solr/bin/solr zk cp <src> <dst> [-r] [-z <zk_string>] (1)
$ /usr/lib/solr/bin/solr zk rm <path> [-r] [-z <zk_string>] (2)
$ /usr/lib/solr/bin/solr zk mv <src> <dst> [-z <zk_string>] (3)
$ /usr/lib/solr/bin/solr zk ls <path> [-r] [-z <zk_string>] (4)
$ /usr/lib/solr/bin/solr zk mkroot <path> [-z <zk_string>] (5)
1 Transfers data between the local file system and ZooKeeper Znodes. The prefix zk: assumes a ZooKeeper location, and file: indicates the local file system. At least one of <src> or <dest> must be prefixed with zk:.
2 Removes a Znode from ZooKeeper. Since <path> assumes a ZooKeeper node, no zk: prefix is necessary.
3 Moves (renames) a Znode.
4 Lists the children of a Znode.
5 Creates a new Znode. Intermediate Znodes are created, if necessary.

Examples

Download a configset from ZooKepper
$ /usr/lib/solr/bin/solr zk downconfig -n test_collection -d ~/my_test_collection_config

Sample output:

Downloading configset test_collection from ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server to directory /home/admin/my_test_collection_config/conf
Upload a directory to ZooKeeper
$ /usr/lib/solr/bin/solr zk cp -r file:/home/admin/test_dir/ zk:/Arenadata.Hadoop-8.solr.server/test_upload

Sample output:

Copying from 'file:/home/admin/test_dir/' to 'zk:/Arenadata.Hadoop-8.solr.server/test_upload'. ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server
Remove a Znode with descendants
$ /usr/lib/solr/bin/solr zk rm -r zk:/Arenadata.Hadoop-8.solr.server/test_upload

Sample output:

Removing ZooKeeper node /Arenadata.Hadoop-8.solr.server/test_upload from ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server recurse: true

Data export commands

Using the export command, you can export documents from a Solr collection in the JSON or Javabin format. The usage is as follows:

$ /usr/lib/solr/bin/solr export [<PARAMETERS>]

Command parameters

Command: export
Parameter Description

-fields <f1,f2,fn>

A comma-separated list of fields to export. By default, all fields are exported

-format <fmt>

Sets the output format for exported documents (JSON or javabin), defaulting to JSON

-limit <i>

The maximum number of documents to export. The default value is 100, use -1 to export all documents

-out

Specifies the file name to save exported data. By default, the <collection-name>.<format> template is used

-url <collection_url>

The URL address pointing to the collection

Examples

Export all data from a collection
$ sudo bin/solr export -url http://ka-adh-1.ru-central1.internal:8983/solr/test_collection

Sample output:

NO: of shards : 2

Export complete for : test_collection_shard1_replica_n2, docs : 0

Export complete for : test_collection_shard2_replica_n8, docs : 1

Total Docs exported: 0. Time taken: 0secs

Running this command creates the test_collection.json file in the local file system. The file stores the documents from the requested collection, for example:

{"key1":"foo","key2":"bar","id":"71b51c87-142c-45a6-8ea0-82ae924fd3c4"}
Export only specific fields to a custom file
$ sudo bin/solr export -url http://ka-adh-1.ru-central1.internal:8983/solr/test_collection -fields "key1"

Sample output:

NO: of shards : 2
.
Export complete for : test_collection_shard1_replica_n2, docs : 0

Export complete for : test_collection_shard2_replica_n8, docs : 1

Total Docs exported: 0. Time taken: 0secs

Running this command creates the test_export_file.json file in the local file system. The file stores the documents containing only the requested fields, for example:

{"key1":"foo"}
Found a mistake? Seleсt text and press Ctrl+Enter to report it