src/docs/user/cluster/cluster_search.diviner

   1 @title Cluster: Search
   2 @group cluster
   3
   4 Overview
   5 ========
   6
   7 You can configure Phabricator to connect to one or more fulltext search
   8 services.
   9
  10 By default, Phabricator will use MySQL for fulltext search. This is suitable
  11 for most installs. However, alternate engines are supported.
  12
  13
  14 Configuring Search Services
  15 ===========================
  16
  17 To configure search services, adjust the `cluster.search` configuration
  18 option. This option contains a list of one or more fulltext search services,
  19 like this:
  20
  21 ```lang=json
  22 [
  23   {
  24     "type": "...",
  25     "hosts": [
  26       ...
  27     ],
  28     "roles": {
  29       "read": true,
  30       "write": true
  31     }
  32   }
  33 ]
  34 ```
  35
  36 When a user makes a change to a document, Phabricator writes the updated
  37 document into every configured, writable fulltext service.
  38
  39 When a user issues a query, Phabricator tries configured, readable services
  40 in order until it is able to execute the query successfully.
  41
  42 These options are supported by all service types:
  43
  44 | Key | Description |
  45 |---|---|
  46 | `type` | Constant identifying the service type, like `mysql`.
  47 | `roles` | Dictionary of role settings, for enabling reads and writes.
  48 | `hosts` | List of hosts for this service.
  49
  50 Some service types support additional options.
  51
  52 Available Service Types
  53 =======================
  54
  55 These service types are supported:
  56
  57 | Service | Key | Description |
  58 |---|---|---|
  59 | MySQL | `mysql` | Default MySQL fulltext index.
  60 | Elasticsearch | `elasticsearch` | Use an external Elasticsearch service
  61
  62
  63 Fulltext Service Roles
  64 ======================
  65
  66 These roles are supported:
  67
  68 | Role | Key | Description
  69 |---|---|---|
  70 | Read | `read` | Allows the service to be queried when users search.
  71 | Write | `write` | Allows documents to be published to the service.
  72
  73
  74 Specifying Hosts
  75 ================
  76
  77 The `hosts` key should contain a list of dictionaries, each specifying the
  78 details of a host. A service should normally have one or more hosts.
  79
  80 When an option is set at the service level, it serves as a default for all
  81 hosts. It may be overridden by changing the value for a particular host.
  82
  83
  84 Service Type: MySQL
  85 ==============
  86
  87 The `mysql` service type does not require any configuration, and does not
  88 need to have hosts specified. This service uses the builtin database to
  89 index and search documents.
  90
  91 A typical `mysql` service configuration looks like this:
  92
  93 ```lang=json
  94 {
  95   "type": "mysql"
  96 }
  97 ```
  98
  99
 100 Service Type: Elasticsearch
 101 ======================
 102
 103 The `elasticsearch` service type supports these options:
 104
 105 | Key | Description |
 106 |---|---|
 107 | `protocol` | Either `"http"` (default) or `"https"`.
 108 | `port` | Elasticsearch TCP port.
 109 | `version` | Elasticsearch version, either `2` or `5` (default).
 110 | `path` | Path for the index. Defaults to `/phabricator`. Advanced.
 111
 112 A typical `elasticsearch` service configuration looks like this:
 113
 114 ```lang=json
 115 {
 116   "type": "elasticsearch",
 117   "hosts": [
 118     {
 119       "protocol": "http",
 120       "host": "127.0.0.1",
 121       "port": 9200
 122     }
 123   ]
 124 }
 125 ```
 126
 127 Monitoring Search Services
 128 ==========================
 129
 130 You can monitor fulltext search in {nav Config > Search Servers}. This
 131 interface shows you a quick overview of services and their health.
 132
 133 The table on this page shows some basic stats for each configured service,
 134 followed by the configuration and current status of each host.
 135
 136
 137 Rebuilding Indexes
 138 ==================
 139
 140 After adding new search services, you will need to rebuild document indexes
 141 on them. To do this, first initialize the services:
 142
 143 ```
 144 phabricator/ $ ./bin/search init
 145 ```
 146
 147 This will perform index setup steps and other one-time configuration.
 148
 149 To populate documents in all indexes, run this command:
 150
 151 ```
 152 phabricator/ $ ./bin/search index --force --background --type all
 153 ```
 154
 155 This initiates an exhaustive rebuild of the document indexes. To get a more
 156 detailed list of indexing options available, run:
 157
 158 ```
 159 phabricator/ $ ./bin/search help index
 160 ```
 161
 162
 163 Advanced Example
 164 ================
 165
 166 This is a more advanced example which shows a configuration with multiple
 167 different services in different roles. In this example:
 168
 169   - Phabricator is using an Elasticsearch 2 service as its primary fulltext
 170     service.
 171   - An Elasticsearch 5 service is online, but only receiving writes.
 172   - The MySQL service is serving as a backup if Elasticsearch fails.
 173
 174 This particular configuration may not be very useful. It is primarily
 175 intended to show how to configure many different options.
 176
 177
 178 ```lang=json
 179 [
 180   {
 181     "type": "elasticsearch",
 182     "version": 2,
 183     "hosts": [
 184       {
 185         "host": "elastic2.mycompany.com",
 186         "port": 9200,
 187         "protocol": "http"
 188       }
 189     ]
 190   },
 191   {
 192     "type": "elasticsearch",
 193     "version": 5,
 194     "hosts": [
 195       {
 196         "host": "elastic5.mycompany.com",
 197         "port": 9789,
 198         "protocol": "https"
 199         "roles": {
 200           "read": false,
 201           "write": true
 202         }
 203       }
 204     ]
 205   },
 206   {
 207     "type": "mysql"
 208   }
 209 ]
 210 ```