Metadata-Version: 2.0
Name: kinto-algolia
Version: 0.2.0
Summary: Index and search records using Algolia.
Home-page: https://github.com/Kinto/kinto-algolia
Author: Rémy Hubscher
Author-email: hubscher.remy@gmail.com
License: Apache License (2.0)
Description-Content-Type: UNKNOWN
Keywords: kinto algolia index
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: algoliasearch
Requires-Dist: kinto

Kinto Algolia
#############

.. image:: https://img.shields.io/travis/Kinto/kinto-algolia.svg
        :target: https://travis-ci.org/Kinto/kinto-algolia

.. image:: https://img.shields.io/pypi/v/kinto-algolia.svg
        :target: https://pypi.python.org/pypi/kinto-algolia

.. image:: https://coveralls.io/repos/Kinto/kinto-algolia/badge.svg?branch=master
        :target: https://coveralls.io/r/Kinto/kinto-algolia

**kinto-algolia** forwards the records to Algolia and provides a ``/search``
endpoint to query the indexed data.


Install
=======

::

    pip install kinto-algolia


Setup
=====

In the `Kinto <http://kinto.readthedocs.io/>`_ settings:

.. code-block :: ini

    kinto.includes = kinto_algolia
    kinto.algolia.application_id = YourApplicationID
    kinto.algolia.api_key = YourAPIKey

By default, indices names are prefixed with ``kinto-``. You change this with:

.. code-block :: ini

    kinto.algolia.index_prefix = myprefix


Usage
=====

Create a new record:

::

    $ echo '{"data":
        {"id": "1008855320",
         "last_modified": 1523349594783,
         "title": "kinto",
         "description": "A database for the web",
         "_geoloc": {"lng": -73.778925, "lat": 40.639751}}' | \
        http POST http://localhost:8888/v1/buckets/example/collections/notes/records \
            --auth token:alice-token


It should now be possible to search for it using the `Algolia API <https://www.elastic.co/guide/en/algolia/reference/current/index.html>`_.

For example, using a quick querystring search:

::

    $ http "http://localhost:8888/v1/buckets/example/collections/notes/search?query=kinto+database" \
        --auth token:alice-token


Or an advanced search using request body:

::

    $ echo '{"insideBoundingBox": "46.650828100116044,7.123046875,45.17210966999772,1.009765625"}' | \
        http POST http://localhost:8888/v1/buckets/example/collections/notes/search \
            --auth token:alice-token

.. code-block:: http

    HTTP/1.1 200 OK
    Access-Control-Expose-Headers: Retry-After, Content-Length, Alert, Backoff
    Content-Length: 333
    Content-Type: application/json; charset=UTF-8
    Date: Wed, 20 Jan 2016 12:02:05 GMT
    Server: waitress

    {
      "hits": [
        {
           "_geoloc": {
               "lat": 40.639751,
               "lng": -73.778925
           },
           "_highlightResult": {
               "title": {
                   "matchLevel": "none",
                   "matchedWords": [],
                   "value": "Kinto"
               }
           },
           "last_modified": 1523349594783,
           "title": "Kinto",
           "description": "A database for the web",
           "objectID": "1008855320"
        }
      ],
      "hitsPerPage": 1000,
      "nbHits": 1,
      "nbPages": 1,
      "page": 0,
      "params": "insideBoundingBox=42.124710287101955%2C9.335632324218752%2C41.47360232634395%2C14.403076171875002&hitsPerPage=10000&query=",
      "processingTimeMS": 2,
      "query": ""
    }


Custom index settings
---------------------

By default, Algolia infers the data types from the indexed records.

But it's possible to define the index mappings (ie. schema) from the collection metadata,
in the ``algolia:settings`` property:

.. code-block:: bash

    $ echo '{
      "attributesToIndex": ["title", "description"]
    }' | http PATCH "http://localhost:8888/v1/buckets/blog/collections/builds" \
        --auth token:admin-token --verbose

Refer to `Algolia official documentation <https://www.algolia.com/doc/api-reference/api-methods/get-settings/?language=python#response>`_ for more information about settings.


Running the tests
=================

::

  $ make tests


Changelog
=========

0.2.0 (2018-07-18)
------------------

**Bug fixes**

- Update algolia settings.


0.1.1 (2018-06-06)
------------------

**Bug fixes**

- Fix reindex command.


0.1.0 (2018-04-12)
------------------

**New features**

- Flush indices when server is flushed
- Perform insertions and deletion in bulk for better efficiency
- Add heartbeat
- Delete indices when buckets and collections are deleted
- Support quick search from querystring
- Support defining mapping from the ``algolia:settings`` property in the collection metadata

**Bug fixes**

- Only index records if the storage transaction is committed
- Do not allow to search if no read permission on collection or bucket
- Fix empty results response when plugin was enabled after collection creation

**Internal changes**

- Create index when collection is created


