:orphan:

.. role:: json(code)
   :language: json

.. role:: python(code)
   :language: python


Search API
==========

.. contents:: :depth: 3

Endpoints
#########


Get Indexes
-----------

.. code::

    GET /core/v1/search/indexes

200 OK
******

.. code:: json

    {
      "indexes": [
        {
          "slug": "my-first-index",
          "title": "My First Index",
          "status": "created",
          "mapping": <index mapping>
      ]
    }

Hints:

* <index mapping> (see: `Mappings`_)


Create/Modify Index
-------------------

.. code::

    PUT /core/v1/search/indexes/<index slug>

.. code:: json

    {
      "commands": [
        <command description>,
        <command description>,
        ...
      ]
    }

200 OK
******

.. code:: json

    {
      "indexes": [
        {
          "slug": "my-second-index",
          "title": "My Second Index",
          "status": "created",
          "mapping": <index mapping>
      ]
    }

Hints:

- <command description> (see: `Commands`_)
- <index mapping> (see: `Mappings`_)


Fill Index with Data
--------------------

.. code::

    POST /core/v1/search/indexes/my-second-index/index-posts

.. code::

    POST /core/v1/search/indexes/my-second-index/index-users

.. code::

    GET /core/v1/search/indexes/my-second-index/index-posts?task_id=38e9eea7-fc5b-4373-90f0-cb2d59109113

.. code::

    GET /core/v1/search/indexes/my-second-index/index-users?task_id=38e9eea7-fc5b-4373-90f0-cb2d59109113

200 OK
******

.. code:: json

    {
      "task": {
        "id": "38e9eea7-fc5b-4373-90f0-cb2d59109113",
        "is_ready": true,
        "progress": null,  // or same as "response"
        "response": {
          "entities": {
            "total_count": 12343,
            "indexed_count": 12343
          }
        },
        "exception": null
    }


Find records count
------------------

.. code::

    POST core/v1/search/indexes/my-second-index/find-count

.. code:: json

    {
      "filters": [
        <filter>,
        <filter>,
        ...
      ]
    }

200 OK
******

.. code:: json

    {
      "records_count": 41234
    }

Hints:

- <filter> (see: `Filters`_)


Find records
------------

.. code::

    POST core/v1/search/indexes/my-second-index/find

.. code:: json

    {
      "filters": [
        <filter>,
        <filter>,
        ...
      ],
      "chunk": {
        "order": <order>,
        "limit": 10,
        "offset": 0,
        "cursor": <null or cursor>
      }
    }

200 OK
******

.. code:: json

    {
      "records": [
        {"id": <taxonomy guid>, "cursor": "cursor-1"},
        {"id": <taxonomy guid>, "cursor": "cursor-2"},
        ...
      ]
    }

Hints:

- <filter> (see: `Filters`_)
- <order> (see: `Orders`_)
- <taxonomy guid> (see: :ref:`taxonomy-entity-guids`)


Commands
########

The commands allow to navigate an index through its lifecycle:

#. Create index
    * Update index title
        :json:`{"set-title": "My Second Index"}`
    * Update index mapping:
        :json:`{"set-mapping": <index mapping>}`

#. Start index. It’s not possible to change the mapping after an index is started
    :json:`{"start": {}}`

    * Fill the index with data

#. Activate index. It makes it available for reads
    :json:`{"activate": {}}`

    * Use index for searching

#. Stop index. It’s not possible to read or write from it anymore but the data is still stored
    :json:`{"stop": {}}`

#. Remove index. It removes the index with all its data
    :json:`{"remove": {}}`

Hints:

- <index mapping> (see: `Mappings`_)


Mappings
########

.. code:: json

    {
      "root": <taxonomy entity type>,
      "texts": [
        {
          "weight": 8,
          "analyzer": <text analyzer configuration>,
          "extractor": <text extractor configuration>,
        },
        ...
      ],
      "values":[
        {"type": <value type>, "field": <taxonomy field>},
        {"type": <value type>, "field": <taxonomy field>},
        ...
      ],
      "labels": [
        {"field": <taxonomy field>},
        {"field": <taxonomy field>},
        ...
      ]
    }


Hints:

- <taxonomy entity type> (see: :ref:`taxonomy-entity-types`)
- <text analyzer configuration> (see: `Text Analyzers`_)
- <text extractor configuration> (see: `Text Extractors`_)
- <value type> (see: `Value Types`_)
- <taxonomy field> (see: :ref:`taxonomy-entity-fields`)


Text Analyzers
--------------

Text analysis is the process of converting unstructured text, like the body
of an email or a product description, into a structured format that’s optimized
for search.


- For full-text search
    :json:`{"unicode": {}}`
- For full-text search by English words
    :json:`{"english": {}}`
- For exact case-insensitive search by words
    :json:`{"keyword": {"normalizers": [{"lowercase": {}}]}}`
- For search by a case-insensitive substring with the length at least of 3 symbols (tri-gram tokens)
    :json:`{"ngram": {"size": 3, "normalizers": [{"uppercase": {}}]}}`


Text Extractors
---------------

Text extraction is the process of retrieving and combining texts from indexed
entities. This text then goes through text analysis process before being stored
in the index.

- Take an entity text as it is
    :json:`{"basic": {"field": <taxonomy field>}}`

- Combine text from a sequence of sub-extractors
    .. code:: json

        {
          "composite": {
            "extractors": [
              <text extractor>,
              <text extractor>,
              ...
            ],
          }
        }

- Extract text based on a condition
    .. code:: json

        {
          "conditioned": {
            "condition": {"taxonomy": {"filters": [
              <taxonomy filter>,
              <taxonomy filter>,
              ...
            ]}},
            "then_extractor": <text extractor or null>,
            "else_extractor": <text extractor or null>
          }
        }


Hints:

- <taxonomy field> (see: :ref:`taxonomy-entity-fields`)
- <taxonomy filter> (see: :ref:`taxonomy-filters`)


Value Types
-----------

Value fields used for both sorting results as well as filtering by range.
Therefore, it can only support some simple types:

- Strings
    :json:`"str"`
- Numbers
    :json:`"int"`
- Numbers with floating point
    :json:`"float"`


Filters
#######

- Include only records that match the phrase with default syntax and text weights
    .. code:: json

        {
          "phrase": {
            "phrase": "Hello World"
          }
        }

- Include only records that match the `strict syntax <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html>`_ query only in the 2nd text field
    .. code:: json

        {
          "phrase": {
            "phrase": "\"Hello World\"",
            "syntax": {"strict": {}},
            "weights": [0, 10, 0]
          }
        }

- Include only records that match labels and ranges
    .. code:: json

        {
          "taxonomy": <taxonomy filter>
        }

Hints:

- <taxonomy filter> (see: :ref:`taxonomy-filters`)


Orders
######

- Sort by one of the value fields
    :json:`{"value": {"field": <taxonomy field>, "reverse": true}}`
- Sort by relevance to the phrase
    :json:`{"relevance": {}}`
- Sort by relevance to the phrase penalizing "older" records relevance score 
    :json:`{"relevance": {"decay": {"field": <timestamp taxonomy field>}}}`

Hints:

- <taxonomy field> (see: :ref:`taxonomy-entity-fields`)