[docs] updates to json queries; http api is principal section now

docs/searching/http_protocol.rst → docs/http_reference/json_search.rst

@@ -1,85 +1,19 @@
-.. _http_protocol:
+.. _http_json_search:
 
-HTTP protocol
--------------
-
-Manticore search daemon supports HTTP protocol and can be accessed with
-regular HTTP clients. Available only with ``workers = thread_pool`` (see :ref:`workers`).
-To enabled the HTTP protocol, a :ref:`listen` directive with http specified as a protocol needs to be declared:
-
-.. code-block:: ini
-
-
-    listen = localhost:8080:http
-
-
-.. _http_protocol_sphinxql:
-
-SphinxQL queries via HTTP protocol
-----------------------------------
-
-Supported endpoints:
-
--  / - default response, returns a simple HTML page
-
--  /search - allows a simple full-text search, parameters can be : index
-   (index or list of indexes), match (equivalent of MATCH()), select (as
-   SELECT clause), group (grouping attribute), order (SQL-like sorting),
-   limit (equivalent of LIMIT 0,N)
-
-.. code-block:: bash
-
-       curl -X POST 'http://manticoresearch:9308/search/' 
-       -d 'index=forum&match=@subject php manticore&select=id,subject,author_id&limit=5'
-
--  / sql - allows running a SELECT SphinxQL, set as query parameter
-
-.. code-block:: bash
-
-
-        curl -X POST 'http://manticoresearch:9308/sql/' 
-       -d 'query=select id,subject,author_id  from forum where match('@subject php manticore') group by
-        author_id order by id desc limit 0,5'
-
-The result for /sql/ and /search/ endpoints is an array of attrs,matches
-and meta, same as for SphinxAPI, encoded as a JSON object.
-
-
-.. _http_protocol_json:
-
-JSON queries via HTTP protocol
-------------------------------
-
-**Table of Contents**
-
-1. `Fulltext queries`_
-2. `Bool queries`_
-3. `Filters`_
-4. `Sorting`_
-5. `Expressions`_
-6. `Text highlighting`_
-7. `Result set format`_
-8. `Query profile`_
-
-Manticore allows you to perform searches using queries written as JSON via HTTP protocol. Thus, HTTP protocol must be enabled.
+json/search 
+-----------
 
-Searches are accepted at ``json/search/`` endpoint. Here’s an example of a simple query:
+Searches are accepted at ``/json/search/`` endpoint. Here’s an example of a simple query:
 
 ::
 
-    {
-      "index": "test",
-      "query":
-      {
-        "match": { "title": "keyword" }
-      }
-    }
-
-``"index"`` clause sets the list of indexes to search through. You can specify a single index: ``"index": "test"``
+    curl -X POST 'http://manticoresearch:9308/json/search/' 
+	-d '{"index":"test","query":{"match":{"title":"keyword"}}'
 
-Or a comma-separated list of indexes: ``"index": "test1,test2,test3"``
-
-Or use “\_all" or “\*" to issue the query to all available indexes:
+``"index"`` clause sets the list of indexes to search through. 
+You can specify a single index: ``"index": "test"``, 
+a comma-separated list of indexes: ``"index": "test1,test2,test3"``
+or use ``_all`` or ``*`` to issue the query to all available indexes:
 
 ::
 
@@ -90,14 +24,13 @@ Or use “\_all" or “\*" to issue the query to all available indexes:
 can be used to organize queries and filters into a tree (using the bool
 query).
 
+Fulltext queries
+""""""""""""""""
+
 The following fulltext queries are supported:
 
-* `match`_
-* `match\_phrase`_ 
-* `match\_all`_
+``match``
 
-match
-~~~~~
 
 ``"match"`` is a simple query that matches the specified keywords in the
 specified fields
@@ -147,8 +80,8 @@ By default keywords are combined using the OR operator. However, you can change
 
 ``"operator"`` can be set to ``"or"`` or ``"and"``.
 
-match\_phrase
-~~~~~~~~~~~~~
+``match_phrase``
+
 
 ``"match_phrase"`` is a query that matches the entire phrase. It is similar to a phrase operator in SphinxQL. Here’s an example:
 
@@ -159,8 +92,8 @@ match\_phrase
       "match_phrase": { "_all" : "had grown quite" }
     }
 
-match\_all
-~~~~~~~~~~
+``match_all``
+
 
 ``"match_all"`` is a query that matches all documents. The syntax looks
 like this:
@@ -175,12 +108,12 @@ like this:
 It can be used to create fullscan queries. However, it is not required as you can just specify the filters without a fulltext query.
 
 Bool queries
-------------
+""""""""""""""""
 
 A bool query matches documents matching boolean combinations of other queries and/or filters. Queries and filters must be specified in
 ``"must"``, ``"should"`` or ``"must_not"`` sections. Example:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -198,25 +131,25 @@ A bool query matches documents matching boolean combinations of other queries an
     }
 
 ``"must"``
-~~~~~~~~~~
+
 
 Queries and filters specified in the ``"must"`` section must match the documents. If several fulltext queries or filters are specified, all of them. This is the equivalent of ``AND`` queries in SphinxQL.
 
 ``"should"``
-~~~~~~~~~~~~
+
 
 Queries and filters specified in the ``"should"`` section should match the documents. If some queries are specified in ``"must"`` or
 ``"must_not"``, ``"should"`` queries are ignored. On the other hand, if there are no queries other than ``"should"``, then at least one of these queries must match a document for it to match the bool query. This is the equivalent of ``OR`` queries.
 
 ``"must_not"``
-~~~~~~~~~~~~~~
+
 
 Queries and filters specified in the ``"must_not"`` section must not match the documents. If several queries are specified under
 ``"must_not"``, the document matches if none of them match.
 
 Example:
 
-::
+.. code-block:: json
 
     {
       "index": "test1",
@@ -238,12 +171,12 @@ Example:
     }
 
 Filters
--------
+""""""""""""""""
 
 JSON queries have two distinct entities: fulltext queries and filters. Both can be organised in a tree (using a bool query), but for now
 filters work only for the root element of the query. For example:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -252,7 +185,7 @@ filters work only for the root element of the query. For example:
 
 Here’s an example of several filters in a ``bool`` query:
 
-::
+.. code-block:: json
 
     {
       "index": "test1",
@@ -281,11 +214,9 @@ All of these documents must not have a ``revision`` less than 15
 
 The following types of filters are supported: 
 
-* `range`_
-* `geo\_distance`_
 
-Range filters
-~~~~~~~~~~~~~
+**Range filters**
+
 
 Range filters match documents that have attribute values within a specified range. Example:
 
@@ -307,14 +238,14 @@ Range filters support the following properties:
 * ``lte``: value must be less than or equal to
 * ``lt``: value must be less
 
-Geo distance filters
-~~~~~~~~~~~~~~~~~~~~
+**Geo distance filters**
+
 
 geo\_distance filters are used to filter the documents that are within a specific distance from a geo location.
 
 Example:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -323,19 +254,20 @@ Example:
         "geo_distance":
         {
           "location_anchor": {"lat":49, "lon":15},
-          "location_source":"attr_lat, attr_lon",
+          "location_source": {"attr_lat, attr_lon"},
           "distance_type": "adaptive",
-          "distance":100km
+          "distance":"100 km"
         }
-    }
+	  }
+    }  
 
--  ``location_anchor``: specifies the pin location. Distances are
+-  ``location_anchor``: specifies the pin location, in degrees. Distances are
    calculated from this point.
 -  ``location_source``: specifies the attributes that contain latitude
    and longitude.
 -  ``distance_type``: specifies distance calculation function. Can be
    either ``adaptive`` or ``haversine``. ``adaptive`` is faster and
-   more precise, for more details see GEODIST() function in SphinxQL.
+   more precise, for more details see :ref:`GEODIST() <expr-func-geodist>`.
    Optional, defaults to ``adaptive``.
 -  ``distance``: specifies the maximum distance from the pin locations.
    All documents within this distance match. The distance can be
@@ -362,14 +294,13 @@ following latitude/longitude formats:
 Latitude and longitude are specified in degrees.
 
 Sorting
--------
+""""""""""""""""
 
--  `Sorting by attributes`_
--  `Sorting by geo distance`_
+**Sorting by attributes**
 
 Query results can be sorted by one or more attributes. Example:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -422,7 +353,7 @@ Example:
 When sorting on an attribute, match weight (score) calculation is disabled by default (no ranker is used). You can enable weight
 calculation by setting the ``track_scores`` property to true:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -431,13 +362,13 @@ calculation by setting the ``track_scores`` property to true:
       "sort": [ { "gid": { "order":"desc" } } ]
     }
 
-Sorting by geo distance
-~~~~~~~~~~~~~~~~~~~~~~~
+**Sorting by geo distance**
+
 
 Matches can be sorted by their distance from a specified location.
 Example:
 
-::
+.. code-block:: json
 
     {
       "index": "test",
@@ -458,15 +389,14 @@ Example:
 ``location_anchor`` property specifies the pin location,
 ``location_source`` specifies the attributes that contain latitude and
 longitude and ``distance_type`` selects distance computation function
-(optional, defaults to “arc”). For more information, see `Geo distance
-filters`_
+(optional, defaults to “arc”).
 
 Expressions
------------
+""""""""""""""""
 
 Expressions are supported via ``script_fields``:
 
-::
+.. code-block:: json
 
     {
       "index": "test",
@@ -484,11 +414,11 @@ Only ``inline`` expressions are supported for now. The value of ``inline`` prope
 SphinxQL expressions.
 
 Text highlighting
------------------
+"""""""""""""""""
 
 Fulltext query search results can be highlighted on one or more fields. Field contents has to be stored in string attributes (for now). Here’s an example:
 
-::
+.. code-block:: json
 
     {
       "index": "test",
@@ -505,7 +435,7 @@ Fulltext query search results can be highlighted on one or more fields. Field co
 
 As a result of this query, the values of string attributes called ``content`` and ``title`` are highlighted against the query specified in ``query`` clause. Highlighted snippets are added in the ``highlight`` property of the ``hits`` array:
 
-::
+.. code-block:: json
 
     {
       "took":1,
@@ -540,7 +470,7 @@ The following options are supported:
 * ``encoder`` can be set to ``default`` or ``html``. When set to ``html``, retains html markup when highlighting. Works similar to ``html_strip_mode=retain`` in ``CALL SNIPPETS``.
 * ``highlight_query`` makes it possible to highlight against a query other than our search query. Syntax is the same as in the main ``query``:
 
-  ::
+   .. code-block:: json
 
     {
       "index": "test",
@@ -607,11 +537,11 @@ The following options are supported:
 *  ``number_of_fragments``: Limits the maximum number of fragments in a snippet. Just as ``fragment_size``, can be global or per-field. Optional, default is 0 (no limit). Works similar to ``limit_passages`` in ``CALL SNIPPETS``.
 
 Result set format
------------------
+""""""""""""""""""
 
 Query result is sent as a JSON document. Example:
 
-::
+.. code-block:: json
 
     {
       "took":10
@@ -653,7 +583,7 @@ Each match in the ``hits`` array has the following properties:
 You can use the ``_source`` property to select the fields you want to be
 included in the result set. Example:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -679,11 +609,11 @@ while an empty list of excludes does not match anything. If an attribute
 matches both the includes and excludes, then the excludes win.
 
 Query profile
--------------
+""""""""""""""""
 
 You can view the final transformed query tree with all normalized keywords by adding a ``"profile":true`` property:
 
-::
+.. code-block:: json
 
     {
       "index":"test",
@@ -761,23 +691,4 @@ This feature is somewhat similar to ``SHOW PLAN`` statement in SphinxQL. The res
 * ``expanded``: keyword added by prefix expansion. Keyword nodes only.
 * ``field_start``: keyword must occur at the very start of the field. Keyword nodes only.
 * ``field_end``: keyword must occur at the very end of the field. Keyword nodes only.
-* ``boost``: keyword IDF will be multiplied by this. Keyword nodes only.
-
-
-.. _Fulltext queries: #fulltext
-.. _Bool queries: #bool
-.. _Filters: #filters
-.. _Sorting: #sorting
-.. _Expressions: #expressions
-.. _Text highlighting: #highlighting
-.. _Result set format: #result_set
-.. _Query profile: #profile
-.. _match: #match
-.. _match\_phrase: #match_phrase
-.. _match\_all: #match_all
-.. _range: #range
-.. _geo\_distance: #geo_distance
-.. _Sorting by attributes: #sort_attr
-.. _Sorting by geo distance: #sort_geo_distance
-.. _Geo distance filters: #geo_distance
-.. _Query profile: #profile
+* ``boost``: keyword IDF will be multiplied by this. Keyword nodes only.

docs/httpapi_reference.rst

@@ -0,0 +1,125 @@
+.. _httpapi_reference:
+
+HTTP API reference
+===================
+
+Manticore search daemon supports HTTP protocol and can be accessed with
+regular HTTP clients. Available only with ``workers = thread_pool`` (see :ref:`workers`).
+To enabled the HTTP protocol, a :ref:`listen` directive with http specified as a protocol needs to be declared:
+
+.. code-block:: ini
+
+
+    listen = localhost:8080:http
+
+Supported endpoints:
+
+/search API
+-----------
+
+Allows a simple full-text search, parameters can be : 
+* index   (index or list of indexes)
+* match (equivalent of MATCH()) 
+* select (as SELECT clause)
+* group (grouping attribute)
+* order (SQL-like sorting)
+* limit (equivalent of LIMIT 0,N) 
+
+Response is a JSON document containing an array of attrs,matches and meta similar with the SphinxAPI response.
+
+.. code-block:: bash
+
+       curl -X POST 'http://manticoresearch:9308/search/' 
+       -d 'index=forum&match=@subject php manticore&select=id,subject,author_id&limit=5'
+
+.. code-block:: json
+       
+	{
+	   "attrs":[
+		  "forum_id",
+		  "author_id",
+		  "subject",
+		  "id"
+	   ],
+	   "matches":[
+
+	   ],
+	   "meta":{
+		  "total":0,
+		  "total_found":0,
+		  "time":0.000,
+		  "words":[
+			 {
+				"word":"php",
+				"docs":3252,
+				"hits":11166
+			 },
+			 {
+				"word":"manticore",
+				"docs":0,
+				"hits":0
+			 }
+		  ]
+	   }
+	}
+	
+
+/sql API
+--------
+
+Allows running a SELECT SphinxQL, set as query parameter. 
+
+Response is a JSON document containing an array of attrs,matches and meta similar with the SphinxAPI response.
+
+.. code-block:: bash
+
+
+        curl -X POST 'http://manticoresearch:9308/sql/' 
+       -d "query=select id,subject,author_id  from forum where match('@subject php manticore') group by
+        author_id order by id desc limit 0,5"
+
+.. code-block:: json
+  
+	{
+	   "attrs":[
+		  "forum_id",
+		  "author_id",
+		  "subject",
+		  "id",
+		  "@groupby",
+		  "@count"
+	   ],
+	   "matches":[
+
+	   ],
+	   "meta":{
+		  "total":123,
+		  "total_found":123,
+		  "time":0.087,
+		  "words":[
+			 {
+				"word":"php",
+				"docs":3252,
+				"hits":11166
+			 },
+			 {
+				"word":"manticore",
+				"docs":1242,
+				"hits":4352
+			 }
+		  ]
+	   }
+	}
+ 
+ 
+/json API
+---------
+
+This endpoint expects request body with queries defined as JSON document. Responds with JSON documents containing result and/or information about executed query.
+
+
+.. toctree::
+	:maxdepth: 1
+	:glob:
+	
+	http_reference/*

docs/index.rst

@@ -18,6 +18,7 @@
    extending
    command_line_tools_reference
    sphinxql_reference
+   httpapi_reference
    api_reference
    conf_options_reference
    reporting_bugs

docs/searching.rst

@@ -14,7 +14,6 @@ Searching
    searching/distributed_searching
    searching/searchd_query_log_formats
    searching/mysql_protocol_support_and_sphinxql
-   searching/http_protocol
    searching/multi-queries
    searching/collations
    searching/query_cache