Algolia Search integration for Django
Project description
.. raw:: html
<!--NO_HTML-->
Algolia Search for Django
=========================
.. raw:: html
<!--/NO_HTML-->
This package lets you easily integrate the Algolia Search API to your
`Django <https://www.djangoproject.com/>`__ project. It's based on the
`algoliasearch-client-python <https://github.com/algolia/algoliasearch-client-python>`__
package.
You might be interested in this sample Django application providing a
typeahead.js based auto-completion and Google-like instant search:
`algoliasearch-django-example <https://github.com/algolia/algoliasearch-django-example>`__
Compatible with **Python 2.7**, **Python 3.2+** and **Django 1.7+**
|Build Status| |Coverage Status| |PyPI version|
.. raw:: html
<!--NO_HTML-->
Table of Content
----------------
1. `Install <#install>`__
2. `Setup <#setup>`__
3. `Quick Start <#quick-start>`__
4. `Commands <#commands>`__
5. `Search <#search>`__
6. `Geo-search <#geo-search>`__
7. `Tags <#tags>`__
8. `Options <#options>`__
9. `Run Tests <#run-tests>`__
.. raw:: html
<!--/NO_HTML-->
Install
=======
.. code:: sh
pip install algoliasearch-django
Setup
=====
In your Django settings, add ``django.contrib.algoliasearch`` to
``INSTALLED_APPS`` and add these two settings:
.. code:: python
ALGOLIA = {
'APPLICATION_ID': 'MyAppID',
'API_KEY': 'MyApiKey'
}
There are two optional settings:
- ``INDEX_PREFIX``: prefix all indexes. Use it to separate different
applications, like ``site1_Products`` and ``site2_Products``.
- ``INDEX_SUFFIX``: suffix all indexes. Use it to differenciate
development and production environment, like ``Location_dev`` and
``Location_prod``.
- ``AUTO_INDEXING``: automatically synchronize the models with Algolia
(default to **True**).
Quick Start
===========
Simply call ``AlgoliaSearch.register()`` for each of the models you want
to index. A good place to do this is in your application's AppConfig
(generally named ``apps.py``). More info in the
`documentation <https://docs.djangoproject.com/en/1.8/ref/applications/>`__
.. code:: python
from django.apps import AppConfig
from django.contrib import algoliasearch
class YourAppConfig(AppConfig):
name = 'your_app'
def ready(self):
YourModel = self.get_model('your_model')
algoliasearch.register(YourModel)
And then, don't forget the line below in the ``__init__.py`` file of
your Django application.
.. code:: python
default_app_config = 'your_django_app.apps.YourAppConfig'
By default, all the fields of your model will be used. You can configure
the index by creating a subclass of ``AlgoliaIndex``. A good place to do
this is in a separate file, like ``index.py``.
.. code:: python
from django.contrib.algoliasearch import AlgoliaIndex
class YourModelIndex(AlgoliaIndex):
fields = ('name', 'date')
geo_field = 'location'
settings = {'attributesToIndex': ['name']}
index_name = 'my_index'
And then replace ``algoliasearch.register(YourModel)`` with
``algoliasearch.register(YourModel, YourModelIndex)``.
Commands
========
- ``python manage.py algolia_reindex``: reindex all the registered
models. This command will first send all the record to a temporary
index and then moves it.
- you can pass ``--model`` parameter to reindex a given model
- ``python manage.py algolia_applysettings``: (re)apply the index
settings.
- ``python manage.py algolia_clearindex``: clear the index
Search
======
We recommend the usage of our `JavaScript API
Client <https://github.com/algolia/algoliasearch-client-js>`__ to
perform queries directly from the end-user browser without going through
your server.
However, if you want to search from your backend you can use the
``raw_search(YourModel, 'yourQuery', params)`` method. It retrieves the
raw JSON answer from the API.
.. code:: python
from django.contrib.algoliasearch import raw_search
params = { "hitsPerPage": 5 }
raw_search(Contact, "jim", params)
Geo-Search
==========
Use the ``geo_field`` attribute to localize your record. ``geo_field``
should be a callable that returns a tuple (latitude, longitude).
.. code:: python
class Contact(models.model):
name = models.CharField(max_lenght=20)
lat = models.FloatField()
lng = models.FloatField()
def location(self):
return (self.lat, self.lng)
class ContactIndex(AlgoliaIndex):
fields = 'name'
geo_field = 'location'
algoliasearch.register(Contact, ContactIndex)
Tags
====
Use the ``tags`` attributes to add tags to your record. It can be a
field or a callable.
.. code:: python
class ArticleIndex(AlgoliaIndex):
tags = 'category'
At query time, specify ``{ tagFilters: 'tagvalue' }`` or
``{ tagFilters: ['tagvalue1', 'tagvalue2'] }`` as search parameters to
restrict the result set to specific tags.
Options
=======
Custom ``objectID``
-------------------
You can choose which field will be used as the ``objectID``. The field
should be unique and can be a string or integer. By default, we use the
``pk`` field of the model.
.. code:: python
class ArticleIndex(AlgoliaIndex):
custom_objectID = 'post_id'
Custom index name
-----------------
You can customize the index name. By default, the index name will be the
name of the model class.
.. code:: python
class ContactIndex(algoliaindex):
index_name = 'Entreprise'
Index settings
--------------
We provide many ways to configure your index allowing you to tune your
overall index relevancy. All the configuration is explained on `our
website <https://www.algolia.com/doc/python#Settings>`__.
.. code:: python
class ArticleIndex(AlgoliaIndex):
settings = {
'attributesToIndex': ['name', 'description', 'url'],
'customRanking': ['desc(vote_count)', 'asc(name)']
}
Restrict indexing to a subset of your data
------------------------------------------
You can add constraints controlling if a record must be indexed or not.
``should_index`` should be a callable that returns a boolean.
.. code:: python
class Contact(models.model):
name = models.CharField(max_lenght=20)
age = models.IntegerField()
def is_adult(self):
return (self.age >= 18)
class ContactIndex(AlgoliaIndex):
should_index = 'is_adult'
.. raw:: html
<!--NO_HTML-->
Run Tests
=========
To run the tests, first find your Algolia application id and Admin API
key (found on the Credentials page).
.. code:: shell
ALGOLIA_APPLICATION_ID={APPLICATION_ID} ALGOLIA_API_KEY={ADMIN_API_KEY} tox
.. raw:: html
<!--/NO_HTML-->
.. |Build Status| image:: https://travis-ci.org/algolia/algoliasearch-django.svg?branch=master
:target: https://travis-ci.org/algolia/algoliasearch-django
.. |Coverage Status| image:: https://coveralls.io/repos/algolia/algoliasearch-django/badge.svg?branch=master
:target: https://coveralls.io/r/algolia/algoliasearch-django
.. |PyPI version| image:: https://badge.fury.io/py/algoliasearch-django.svg?branch=master
:target: http://badge.fury.io/py/algoliasearch-django
<!--NO_HTML-->
Algolia Search for Django
=========================
.. raw:: html
<!--/NO_HTML-->
This package lets you easily integrate the Algolia Search API to your
`Django <https://www.djangoproject.com/>`__ project. It's based on the
`algoliasearch-client-python <https://github.com/algolia/algoliasearch-client-python>`__
package.
You might be interested in this sample Django application providing a
typeahead.js based auto-completion and Google-like instant search:
`algoliasearch-django-example <https://github.com/algolia/algoliasearch-django-example>`__
Compatible with **Python 2.7**, **Python 3.2+** and **Django 1.7+**
|Build Status| |Coverage Status| |PyPI version|
.. raw:: html
<!--NO_HTML-->
Table of Content
----------------
1. `Install <#install>`__
2. `Setup <#setup>`__
3. `Quick Start <#quick-start>`__
4. `Commands <#commands>`__
5. `Search <#search>`__
6. `Geo-search <#geo-search>`__
7. `Tags <#tags>`__
8. `Options <#options>`__
9. `Run Tests <#run-tests>`__
.. raw:: html
<!--/NO_HTML-->
Install
=======
.. code:: sh
pip install algoliasearch-django
Setup
=====
In your Django settings, add ``django.contrib.algoliasearch`` to
``INSTALLED_APPS`` and add these two settings:
.. code:: python
ALGOLIA = {
'APPLICATION_ID': 'MyAppID',
'API_KEY': 'MyApiKey'
}
There are two optional settings:
- ``INDEX_PREFIX``: prefix all indexes. Use it to separate different
applications, like ``site1_Products`` and ``site2_Products``.
- ``INDEX_SUFFIX``: suffix all indexes. Use it to differenciate
development and production environment, like ``Location_dev`` and
``Location_prod``.
- ``AUTO_INDEXING``: automatically synchronize the models with Algolia
(default to **True**).
Quick Start
===========
Simply call ``AlgoliaSearch.register()`` for each of the models you want
to index. A good place to do this is in your application's AppConfig
(generally named ``apps.py``). More info in the
`documentation <https://docs.djangoproject.com/en/1.8/ref/applications/>`__
.. code:: python
from django.apps import AppConfig
from django.contrib import algoliasearch
class YourAppConfig(AppConfig):
name = 'your_app'
def ready(self):
YourModel = self.get_model('your_model')
algoliasearch.register(YourModel)
And then, don't forget the line below in the ``__init__.py`` file of
your Django application.
.. code:: python
default_app_config = 'your_django_app.apps.YourAppConfig'
By default, all the fields of your model will be used. You can configure
the index by creating a subclass of ``AlgoliaIndex``. A good place to do
this is in a separate file, like ``index.py``.
.. code:: python
from django.contrib.algoliasearch import AlgoliaIndex
class YourModelIndex(AlgoliaIndex):
fields = ('name', 'date')
geo_field = 'location'
settings = {'attributesToIndex': ['name']}
index_name = 'my_index'
And then replace ``algoliasearch.register(YourModel)`` with
``algoliasearch.register(YourModel, YourModelIndex)``.
Commands
========
- ``python manage.py algolia_reindex``: reindex all the registered
models. This command will first send all the record to a temporary
index and then moves it.
- you can pass ``--model`` parameter to reindex a given model
- ``python manage.py algolia_applysettings``: (re)apply the index
settings.
- ``python manage.py algolia_clearindex``: clear the index
Search
======
We recommend the usage of our `JavaScript API
Client <https://github.com/algolia/algoliasearch-client-js>`__ to
perform queries directly from the end-user browser without going through
your server.
However, if you want to search from your backend you can use the
``raw_search(YourModel, 'yourQuery', params)`` method. It retrieves the
raw JSON answer from the API.
.. code:: python
from django.contrib.algoliasearch import raw_search
params = { "hitsPerPage": 5 }
raw_search(Contact, "jim", params)
Geo-Search
==========
Use the ``geo_field`` attribute to localize your record. ``geo_field``
should be a callable that returns a tuple (latitude, longitude).
.. code:: python
class Contact(models.model):
name = models.CharField(max_lenght=20)
lat = models.FloatField()
lng = models.FloatField()
def location(self):
return (self.lat, self.lng)
class ContactIndex(AlgoliaIndex):
fields = 'name'
geo_field = 'location'
algoliasearch.register(Contact, ContactIndex)
Tags
====
Use the ``tags`` attributes to add tags to your record. It can be a
field or a callable.
.. code:: python
class ArticleIndex(AlgoliaIndex):
tags = 'category'
At query time, specify ``{ tagFilters: 'tagvalue' }`` or
``{ tagFilters: ['tagvalue1', 'tagvalue2'] }`` as search parameters to
restrict the result set to specific tags.
Options
=======
Custom ``objectID``
-------------------
You can choose which field will be used as the ``objectID``. The field
should be unique and can be a string or integer. By default, we use the
``pk`` field of the model.
.. code:: python
class ArticleIndex(AlgoliaIndex):
custom_objectID = 'post_id'
Custom index name
-----------------
You can customize the index name. By default, the index name will be the
name of the model class.
.. code:: python
class ContactIndex(algoliaindex):
index_name = 'Entreprise'
Index settings
--------------
We provide many ways to configure your index allowing you to tune your
overall index relevancy. All the configuration is explained on `our
website <https://www.algolia.com/doc/python#Settings>`__.
.. code:: python
class ArticleIndex(AlgoliaIndex):
settings = {
'attributesToIndex': ['name', 'description', 'url'],
'customRanking': ['desc(vote_count)', 'asc(name)']
}
Restrict indexing to a subset of your data
------------------------------------------
You can add constraints controlling if a record must be indexed or not.
``should_index`` should be a callable that returns a boolean.
.. code:: python
class Contact(models.model):
name = models.CharField(max_lenght=20)
age = models.IntegerField()
def is_adult(self):
return (self.age >= 18)
class ContactIndex(AlgoliaIndex):
should_index = 'is_adult'
.. raw:: html
<!--NO_HTML-->
Run Tests
=========
To run the tests, first find your Algolia application id and Admin API
key (found on the Credentials page).
.. code:: shell
ALGOLIA_APPLICATION_ID={APPLICATION_ID} ALGOLIA_API_KEY={ADMIN_API_KEY} tox
.. raw:: html
<!--/NO_HTML-->
.. |Build Status| image:: https://travis-ci.org/algolia/algoliasearch-django.svg?branch=master
:target: https://travis-ci.org/algolia/algoliasearch-django
.. |Coverage Status| image:: https://coveralls.io/repos/algolia/algoliasearch-django/badge.svg?branch=master
:target: https://coveralls.io/r/algolia/algoliasearch-django
.. |PyPI version| image:: https://badge.fury.io/py/algoliasearch-django.svg?branch=master
:target: http://badge.fury.io/py/algoliasearch-django
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for algoliasearch-django-1.2.4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 355a93f5a220f676c0f3d884697b25cadf0719587d8c4287c52d16be365633eb |
|
MD5 | 0c76e740bfb5743bae651fcc700c5eff |
|
BLAKE2b-256 | d3cf9f7e45082e9398486bab13ffb46aa1e4a76194ce6905ec904e03deea0ec8 |
Close
Hashes for algoliasearch_django-1.2.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63b479abec4cb6793c283a973736cb99006d0438aa0345673b844576769d7695 |
|
MD5 | c9b0df20fba9bb7efb1d2e1f7f34a151 |
|
BLAKE2b-256 | 7c4d4775c5203ea7dc2ca3ffc2d0dd3565882409d75efdacd19a239e2995f60f |