Manticore Search implements an SQL interface using the MySQL protocol, allowing any MySQL library or connector and many MySQL clients to be used to connect to Manticore Search and work with it as if it were a MySQL server, not Manticore.
However, the SQL dialect is different and implements only a subset of the SQL commands or functions available in MySQL. Additionally, there are clauses and functions that are specific to Manticore Search, such as the MATCH() clause for full-text search.
Manticore Search does not support server-side prepared statements, but client-side prepared statements can be used. It is important to note that Manticore implements the multi-value (MVA) data type, which has no equivalent in MySQL or libraries implementing prepared statements. In these cases, the MVA values must be crafted in the raw query.
Some MySQL clients/connectors require values for user/password and/or database name. Since Manticore Search does not have the concept of databases and there is no user access control implemented, these values can be set arbitrarily as Manticore will simply ignore them.
The default port for the SQL interface is 9306 and it's enabled by default.
You can configure the MySQL port in the searchd section of the configuration file using the listen directive like this:
searchd {
...
listen = 127.0.0.1:9306:mysql
...
}Keep in mind that Manticore doesn't have user authentication, so make sure that the MySQL port is not accessible to anyone outside of your network.
A separate MySQL port can be used for performing "VIP" connections. When connecting to this port, the thread pool is bypassed, and a new dedicated thread is always created. This is useful in cases of severe overload, where the server would either stall or prevent a connection through the regular port.
searchd {
...
listen = 127.0.0.1:9306:mysql
listen = 127.0.0.1:9307:mysql_vip
...
}The easiest way to connect to Manticore is by using a standard MySQL client:
mysql -P9306 -h0The MySQL protocol supports SSL encryption. Secure connections can be made on the same mysql listening port.
Compression can be used with MySQL connections and is available to clients by default. The client just needs to specify that the connection should use compression.
An example using the MySQL client:
mysql -P9306 -h0 -CCompression can be used in both secured and non-secured connections.
The official MySQL connectors can be used to connect to Manticore Search, however they might require certain settings passed in the DSN string as the connector can try running certain SQL commands not implemented yet in Manticore.
JDBC Connector 6.x and above require Manticore Search 2.8.2 or greater and the DSN string should contain the following options:
jdbc:mysql://IP:PORT/DB/?characterEncoding=utf8&maxAllowedPacket=512000&serverTimezone=XXXBy default Manticore Search will report it's own version to the connector, however this may cause some troubles. To overcome that mysql_version_string directive in searchd section of the configuration should be set to a version lower than 5.1.1:
searchd {
...
mysql_version_string = 5.0.37
...
}.NET MySQL connector uses connection pools by default. To correctly get the statistics of SHOW META, queries along with SHOW META command should be sent as a single multistatement (SELECT ...;SHOW META). If pooling is enabled option Allow Batch=True is required to be added to the connection string to allow multistatements:
Server=127.0.0.1;Port=9306;Database=somevalue;Uid=somevalue;Pwd=;Allow Batch=True;Manticore can be accessed using ODBC. It's recommended to set charset=UTF8 in the ODBC string. Some ODBC drivers will not like the reported version by the Manticore server as they will see it as a very old MySQL server. This can be overridden with mysql_version_string option.
Manticore SQL over MySQL supports C-style comment syntax. Everything from an opening /* sequence to a closing */ sequence is ignored. Comments can span multiple lines, can not nest, and should not get logged. MySQL specific /*! ... */ comments are also currently ignored. (As the comments support was rather added for better compatibility with mysqldump produced dumps, rather than improving general query interoperability between Manticore and MySQL.)
SELECT /*! SQL_CALC_FOUND_ROWS */ col1 FROM table1 WHERE ...You can connect to Manticore Search through HTTP/HTTPS.
By default, Manticore listens for HTTP, HTTPS, and binary requests on ports 9308 and 9312.
In the "searchd" section of your configuration file, you can define the HTTP port using the listen directive as follows:
Both lines are valid and have the same meaning (except for the port number). They both define listeners that will serve all API/HTTP/HTTPS protocols. There are no special requirements, and any HTTP client can be used to connect to Manticore.
- HTTP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9312:http
...
}All HTTP endpoints return application/json content type. For the most part, endpoints use JSON payloads for requests. However, there are some exceptions that use NDJSON or simple URL-encoded payloads.
Currently, there is no user authentication. Therefore, make sure that the HTTP interface is not accessible to anyone outside your network. As Manticore functions like any other web server, you can use a reverse proxy, such as Nginx, to implement HTTP authentication or caching.
The HTTP protocol also supports SSL encryption:
If you specify :https instead of :http only secured connections will be accepted. Otherwise in case of no valid key/certificate provided, but the client trying to connect via https - the connection will be dropped. If you make not HTTPS, but an HTTP request to 9443 it will respond with HTTP code 400.
- HTTPS
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9443:https
...
}Separate HTTP interface can be used for 'VIP' connections. In this case, the connection bypasses a thread pool and always creates a new dedicated thread. This is useful for managing Manticore Search during periods of severe overload when the server might stall or not allow regular port connections.
For more information on the listen directive, see this section.
- VIP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9318:_vip
...
}Endpoints /sql and /cli allow running SQL queries via HTTP.
/sqlendpoint accepts only SELECT statements and returns the response in HTTP JSON format.- The
/sql?mode=rawendpoint accepts any SQL query and returns the response in raw format, similar to what you would receive via mysql. - The
/cliendpoint accepts any SQL query and returns the response in raw format, similar to what you would receive via mysql. Unlike the/sqland/sql?mode=rawendpoints, thequeryparameter must not be URL-encoded. This endpoint is intended for manual actions using a browser or command line HTTP clients such as curl. It is not recommended to use the/cliendpoint in scripts.
General syntax:
curl "localhost:6780/sql[?mode=raw]&query={URL_ENCODED_QUERY}"curl localhost:6780/sql[?mode=raw] -d "[query={URL_ENCODED_QUERY}|{NOT_URL_ENCODED_QUERY}]"
The /sql endpoint accepts an SQL query via the HTTP JSON interface:
- Without
mode=raw- only SELECTs are allowed, returning the response in JSON format. - With mode=raw - any SQL query is permitted, returning the response in raw format.
The endpoint can handle HTTP requests using either the GET or the POST method. For sending queries, you can:
- Using GET: Include the query in the
queryparameter of the URL, like/sql?query=your_encoded_query_here. It's important to URL encode this parameter to avoid errors, especially if the query includes an=sign, which might be interpreted as part of the URL syntax rather than the query. - Using POST: You can also send the query within the body of a POST request. When using this method:
- If you send the query as a parameter named
query, ensure it is URL encoded. - If you send the query directly as plain text (a raw POST body), do not URL encode it. This is useful when the query is long or complex, or if the query is stored in a file and you want to send it as is by pointing your HTTP client (e.g.,
curl) to it.
- If you send the query as a parameter named
This approach keeps the usage of GET and POST distinct and avoids any confusion about combining methods in a single request.
Without mode=raw the response is a JSON containing information about the hits and the execution time. The response format is the same as the json/search endpoint. Note that the /sql endpoint only supports single search requests. For processing a multi-query, see the section below about the raw mode.
- POST
- POST URL-encoded
- GET URL-encoded
POST /sql
select id,subject,author_id from forum where match('@subject php manticore') group by author_id order by id desc limit 0,5{
"took": 0,
"timed_out": false,
"hits": {
"total": 2,
"total_relation": "eq",
"hits": [
{
"_id": 2,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 12
}
},
{
"_id": 1,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 11
}
}
]
}
}The /sql endpoint also includes a special "raw" mode, which allows you to send any valid SQL queries, including multi-queries. The response is a JSON array containing one or more result sets. You can activate this mode by using the option mode=raw.
- POST
- POST URL-encoded
- POST URL-encoded 2nd way
- GET URL-encoded
- curl examples
POST /sql?mode=raw
desc test[
{
"columns": [
{
"Field": {
"type": "string"
}
},
{
"Type": {
"type": "string"
}
},
{
"Properties": {
"type": "string"
}
}
],
"data": [
{
"Field": "id",
"Type": "bigint",
"Properties": ""
},
{
"Field": "title",
"Type": "text",
"Properties": "indexed"
},
{
"Field": "gid",
"Type": "uint",
"Properties": ""
},
{
"Field": "title",
"Type": "string",
"Properties": ""
},
{
"Field": "j",
"Type": "json",
"Properties": ""
},
{
"Field": "new1",
"Type": "uint",
"Properties": ""
}
],
"total": 6,
"error": "",
"warning": ""
}
]NOTE:
/clirequires Manticore Buddy. If it doesn't work, make sure Buddy is installed.
While the /sql endpoint is useful for controlling Manticore programmatically from your application, there's also the /cli endpoint. This makes it easier to manually maintain a Manticore instance using curl or your browser. It accepts both POST and GET HTTP methods. Everything inputted after /cli? is understood by Manticore, even if it's not manually escaped with curl or automatically encoded by the browser. No query parameter is required. Importantly, the + sign is not changed to a space, eliminating the need for encoding it. For the POST method, Manticore accepts everything exactly as it is, without any changes. The response is in tabular format, similar to an SQL result set you might see in a MySQL client.
- POST
- GET
- Browser
- curl example
POST /cli
desc test
+-------+--------+----------------+
| Field | Type | Properties |
+-------+--------+----------------+
| id | bigint | |
| body | text | indexed stored |
| title | string | |
+-------+--------+----------------+
3 rows in set (0.001 sec)The /cli_json endpoint provides the same functionality as /cli, but the response format is JSON. It includes:
columnssection describing the schema.datasection with the actual data.- Summary section with "total", "error", and "warning".
- POST
- GET
- curl example
POST /cli_json
desc test[
{
"columns":[
{
"Field":{
"type":"string"
}
},
{
"Type":{
"type":"string"
}
},
{
"Properties":{
"type":"string"
}
}
],
"data":[
{
"Field":"id",
"Type":"bigint",
"Properties":""
},
{
"Field":"body",
"Type":"text",
"Properties":"indexed stored"
},
{
"Field":"title",
"Type":"string",
"Properties":""
}
],
"total":3,
"error":"",
"warning":""
}
]HTTP keep-alive is supported (except for the /cli endpoint), which allows for stateful interactions via the HTTP JSON interface as long as the client also supports keep-alive. For instance, using the /cli_json endpoint, you can execute SHOW META after a SELECT command, and it will function similarly to interactions with Manticore through a MySQL client.
You can connect to Manticore Search through HTTP/HTTPS.
By default, Manticore listens for HTTP, HTTPS, and binary requests on ports 9308 and 9312.
In the "searchd" section of your configuration file, you can define the HTTP port using the listen directive as follows:
Both lines are valid and have the same meaning (except for the port number). They both define listeners that will serve all API/HTTP/HTTPS protocols. There are no special requirements, and any HTTP client can be used to connect to Manticore.
- HTTP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9312:http
...
}All HTTP endpoints return application/json content type. For the most part, endpoints use JSON payloads for requests. However, there are some exceptions that use NDJSON or simple URL-encoded payloads.
Currently, there is no user authentication. Therefore, make sure that the HTTP interface is not accessible to anyone outside your network. As Manticore functions like any other web server, you can use a reverse proxy, such as Nginx, to implement HTTP authentication or caching.
The HTTP protocol also supports SSL encryption:
If you specify :https instead of :http only secured connections will be accepted. Otherwise in case of no valid key/certificate provided, but the client trying to connect via https - the connection will be dropped. If you make not HTTPS, but an HTTP request to 9443 it will respond with HTTP code 400.
- HTTPS
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9443:https
...
}Separate HTTP interface can be used for 'VIP' connections. In this case, the connection bypasses a thread pool and always creates a new dedicated thread. This is useful for managing Manticore Search during periods of severe overload when the server might stall or not allow regular port connections.
For more information on the listen directive, see this section.
- VIP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9318:_vip
...
}Endpoints /sql and /cli allow running SQL queries via HTTP.
/sqlendpoint accepts only SELECT statements and returns the response in HTTP JSON format.- The
/sql?mode=rawendpoint accepts any SQL query and returns the response in raw format, similar to what you would receive via mysql. - The
/cliendpoint accepts any SQL query and returns the response in raw format, similar to what you would receive via mysql. Unlike the/sqland/sql?mode=rawendpoints, thequeryparameter must not be URL-encoded. This endpoint is intended for manual actions using a browser or command line HTTP clients such as curl. It is not recommended to use the/cliendpoint in scripts.
General syntax:
curl "localhost:6780/sql[?mode=raw]&query={URL_ENCODED_QUERY}"curl localhost:6780/sql[?mode=raw] -d "[query={URL_ENCODED_QUERY}|{NOT_URL_ENCODED_QUERY}]"
The /sql endpoint accepts an SQL query via the HTTP JSON interface:
- Without
mode=raw- only SELECTs are allowed, returning the response in JSON format. - With mode=raw - any SQL query is permitted, returning the response in raw format.
The endpoint can handle HTTP requests using either the GET or the POST method. For sending queries, you can:
- Using GET: Include the query in the
queryparameter of the URL, like/sql?query=your_encoded_query_here. It's important to URL encode this parameter to avoid errors, especially if the query includes an=sign, which might be interpreted as part of the URL syntax rather than the query. - Using POST: You can also send the query within the body of a POST request. When using this method:
- If you send the query as a parameter named
query, ensure it is URL encoded. - If you send the query directly as plain text (a raw POST body), do not URL encode it. This is useful when the query is long or complex, or if the query is stored in a file and you want to send it as is by pointing your HTTP client (e.g.,
curl) to it.
- If you send the query as a parameter named
This approach keeps the usage of GET and POST distinct and avoids any confusion about combining methods in a single request.
Without mode=raw the response is a JSON containing information about the hits and the execution time. The response format is the same as the json/search endpoint. Note that the /sql endpoint only supports single search requests. For processing a multi-query, see the section below about the raw mode.
- POST
- POST URL-encoded
- GET URL-encoded
POST /sql
select id,subject,author_id from forum where match('@subject php manticore') group by author_id order by id desc limit 0,5{
"took": 0,
"timed_out": false,
"hits": {
"total": 2,
"total_relation": "eq",
"hits": [
{
"_id": 2,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 12
}
},
{
"_id": 1,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 11
}
}
]
}
}The /sql endpoint also includes a special "raw" mode, which allows you to send any valid SQL queries, including multi-queries. The response is a JSON array containing one or more result sets. You can activate this mode by using the option mode=raw.
- POST
- POST URL-encoded
- POST URL-encoded 2nd way
- GET URL-encoded
- curl examples
POST /sql?mode=raw
desc test[
{
"columns": [
{
"Field": {
"type": "string"
}
},
{
"Type": {
"type": "string"
}
},
{
"Properties": {
"type": "string"
}
}
],
"data": [
{
"Field": "id",
"Type": "bigint",
"Properties": ""
},
{
"Field": "title",
"Type": "text",
"Properties": "indexed"
},
{
"Field": "gid",
"Type": "uint",
"Properties": ""
},
{
"Field": "title",
"Type": "string",
"Properties": ""
},
{
"Field": "j",
"Type": "json",
"Properties": ""
},
{
"Field": "new1",
"Type": "uint",
"Properties": ""
}
],
"total": 6,
"error": "",
"warning": ""
}
]NOTE:
/clirequires Manticore Buddy. If it doesn't work, make sure Buddy is installed.
While the /sql endpoint is useful for controlling Manticore programmatically from your application, there's also the /cli endpoint. This makes it easier to manually maintain a Manticore instance using curl or your browser. It accepts both POST and GET HTTP methods. Everything inputted after /cli? is understood by Manticore, even if it's not manually escaped with curl or automatically encoded by the browser. No query parameter is required. Importantly, the + sign is not changed to a space, eliminating the need for encoding it. For the POST method, Manticore accepts everything exactly as it is, without any changes. The response is in tabular format, similar to an SQL result set you might see in a MySQL client.
- POST
- GET
- Browser
- curl example
POST /cli
desc test+-------+--------+----------------+
| Field | Type | Properties |
+-------+--------+----------------+
| id | bigint | |
| body | text | indexed stored |
| title | string | |
+-------+--------+----------------+
3 rows in set (0.001 sec)The /cli_json endpoint provides the same functionality as /cli, but the response format is JSON. It includes:
columnssection describing the schema.datasection with the actual data.- Summary section with "total", "error", and "warning".
- POST
- GET
- curl example
POST /cli_json
desc test[
{
"columns":[
{
"Field":{
"type":"string"
}
},
{
"Type":{
"type":"string"
}
},
{
"Properties":{
"type":"string"
}
}
],
"data":[
{
"Field":"id",
"Type":"bigint",
"Properties":""
},
{
"Field":"body",
"Type":"text",
"Properties":"indexed stored"
},
{
"Field":"title",
"Type":"string",
"Properties":""
}
],
"total":3,
"error":"",
"warning":""
}
]HTTP keep-alive is supported (except for the /cli endpoint), which allows for stateful interactions via the HTTP JSON interface as long as the client also supports keep-alive. For instance, using the /cli_json endpoint, you can execute SHOW META after a SELECT command, and it will function similarly to interactions with Manticore through a MySQL client.