Skip to content

Commit 7fe7279

Browse files
PLNechPLNech
authored
Merge pull request #170 from algoliareadmebot/master
Update README
2 parents 027b224 + d53a820 commit 7fe7279

File tree

1 file changed

+94
-67
lines changed

1 file changed

+94
-67
lines changed

‎README.md‎

Lines changed: 94 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,74 @@
1-
<!--NO_HTML-->
2-
Algolia Search for Django
3-
==================
4-
<!--/NO_HTML-->
1+
# Algolia Search API Client for Django
2+
3+
[Algolia Search](https://www.algolia.com) is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.
4+
5+
[![Build Status](https://travis-ci.org/algolia/algoliasearch-django.svg?branch=master)](https://travis-ci.org/algolia/algoliasearch-django)
6+
[![Coverage Status](https://coveralls.io/repos/algolia/algoliasearch-django/badge.svg?branch=master)](https://coveralls.io/r/algolia/algoliasearch-django)
7+
[![PyPI version](https://badge.fury.io/py/algoliasearch-django.svg?branch=master)](http://badge.fury.io/py/algoliasearch-django)
8+
59

610
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.
711

812
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)
913

10-
Compatible with **Python 2.7**, **Python 3.2+** and **Django 1.7+**
1114

12-
[![Build Status](https://travis-ci.org/algolia/algoliasearch-django.svg?branch=master)](https://travis-ci.org/algolia/algoliasearch-django)
13-
[![Coverage Status](https://coveralls.io/repos/algolia/algoliasearch-django/badge.svg?branch=master)](https://coveralls.io/r/algolia/algoliasearch-django)
14-
[![PyPI version](https://badge.fury.io/py/algoliasearch-django.svg?branch=master)](http://badge.fury.io/py/algoliasearch-django)
1515

16-
<!--NO_HTML-->
17-
Table of Content
18-
-------------
1916

20-
1. [Install](#install)
21-
1. [Setup](#setup)
22-
1. [Quick Start](#quick-start)
23-
1. [Commands](#commands)
24-
1. [Search](#search)
25-
1. [Geo-search](#geo-search)
26-
1. [Tags](#tags)
27-
1. [Options](#options)
28-
1. [Run Tests](#run-tests)
17+
## API Documentation
2918

30-
<!--/NO_HTML-->
19+
You can find the full reference on [Algolia's website](https://www.algolia.com/doc/api-client/django/).
3120

32-
## Setup
3321

34-
### Install
22+
## Table of Contents
23+
24+
25+
1. **[Setup](#setup)**
26+
27+
* [Install](#install)
28+
* [Setup](#setup)
29+
* [Quick Start](#quick-start)
30+
31+
1. **[Commands](#commands)**
32+
33+
* [Commands](#commands)
34+
35+
1. **[Search](#search)**
36+
37+
* [Search](#search)
38+
39+
1. **[Geo-Search](#geo-search)**
40+
41+
* [Geo-Search](#geo-search)
42+
43+
1. **[Tags](#tags)**
44+
45+
* [Tags](#tags)
46+
47+
1. **[Options](#options)**
48+
49+
* [Custom `objectID`](#custom-objectid)
50+
* [Custom index name](#custom-index-name)
51+
* [Index settings](#index-settings)
52+
* [Restrict indexing to a subset of your data](#restrict-indexing-to-a-subset-of-your-data)
53+
54+
1. **[Tests](#tests)**
55+
56+
* [Run Tests](#run-tests)
57+
58+
59+
60+
61+
# Setup
62+
63+
64+
65+
## Install
3566

3667
```sh
3768
pip install algoliasearch-django
3869
```
3970

40-
### Setup
71+
## Setup
4172

4273
In your Django settings, add `django.contrib.algoliasearch` to `INSTALLED_APPS` and add these two settings:
4374

@@ -54,8 +85,7 @@ There are two optional settings:
5485
* `INDEX_SUFFIX`: suffix all indexes. Use it to differenciate development and production environment, like `Location_dev` and `Location_prod`.
5586
* `AUTO_INDEXING`: automatically synchronize the models with Algolia (default to **True**).
5687

57-
58-
### Quick Start
88+
## Quick Start
5989

6090
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/)
6191

@@ -85,25 +115,32 @@ from django.contrib.algoliasearch import AlgoliaIndex
85115
class YourModelIndex(AlgoliaIndex):
86116
fields = ('name', 'date')
87117
geo_field = 'location'
88-
settings = {'attributesToIndex': ['name']}
118+
settings = {'searchableAttributes': ['name']}
89119
index_name = 'my_index'
90120
```
91121

92122
And then replace `algoliasearch.register(YourModel)` with `algoliasearch.register(YourModel, YourModelIndex)`.
93123

94-
## Commands
95124

96-
### Commands
125+
# Commands
126+
127+
128+
129+
## Commands
97130

98131
* `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.
99132
* you can pass ``--model`` parameter to reindex a given model
100133
* `python manage.py algolia_applysettings`: (re)apply the index settings.
101134
* `python manage.py algolia_clearindex`: clear the index
102135

136+
137+
# Search
138+
139+
140+
103141
## Search
104-
### Search
105142

106-
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.
143+
We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-javascript) to perform queries directly from the end-user browser without going through your server.
107144

108145
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.
109146

@@ -114,8 +151,12 @@ params = { "hitsPerPage": 5 }
114151
raw_search(Contact, "jim", params)
115152
```
116153

154+
155+
# Geo-Search
156+
157+
158+
117159
## Geo-Search
118-
### Geo-Search
119160

120161
Use the `geo_field` attribute to localize your record. `geo_field` should be a callable that returns a tuple (latitude, longitude).
121162

@@ -128,42 +169,19 @@ class Contact(models.model):
128169
def location(self):
129170
return (self.lat, self.lng)
130171

131-
132172
class ContactIndex(AlgoliaIndex):
133173
fields = 'name'
134174
geo_field = 'location'
135175

136-
137176
algoliasearch.register(Contact, ContactIndex)
138177
```
139-
Multiple geolocations are supported, for instance:
140178

141-
```python
142-
class Location(models.Model):
143-
lat = models.FloatField()
144-
lng = models.FloatField()
145179

146-
class Contact(models.Model):
147-
name = models.CharField(max_lenght=20)
148-
locations = models.ManyToManyField('Location')
180+
# Tags
149181

150-
def geolocations(self):
151-
return [
152-
{'lat': location.lat, 'lng': location.lng}
153-
for location in self.locations.all()
154-
]
155182

156183

157-
class ContactIndex(AlgoliaIndex):
158-
fields = 'name'
159-
geo_field = 'geolocations'
160-
161-
162-
algoliasearch.register(Contact, ContactIndex)
163-
```
164-
165184
## Tags
166-
### Tags
167185

168186
Use the `tags` attributes to add tags to your record. It can be a field or a callable.
169187

@@ -174,9 +192,12 @@ class ArticleIndex(AlgoliaIndex):
174192

175193
At query time, specify `{ tagFilters: 'tagvalue' }` or `{ tagFilters: ['tagvalue1', 'tagvalue2'] }` as search parameters to restrict the result set to specific tags.
176194

177-
## Options
178195

179-
### Custom `objectID`
196+
# Options
197+
198+
199+
200+
## Custom `objectID`
180201

181202
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.
182203

@@ -185,7 +206,7 @@ class ArticleIndex(AlgoliaIndex):
185206
custom_objectID = 'post_id'
186207
```
187208

188-
### Custom index name
209+
## Custom index name
189210

190211
You can customize the index name. By default, the index name will be the name of the model class.
191212

@@ -194,19 +215,20 @@ class ContactIndex(algoliaindex):
194215
index_name = 'Enterprise'
195216
```
196217

197-
### Index settings
218+
## Index settings
198219

199-
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).
220+
We provide many ways to configure your index allowing you to tune your overall index relevancy.
221+
All the configuration is explained on [our doc](https://www.algolia.com/doc/api-client/python/parameters/).
200222

201223
```python
202224
class ArticleIndex(AlgoliaIndex):
203225
settings = {
204-
'attributesToIndex': ['name', 'description', 'url'],
226+
'searchableAttributes': ['name', 'description', 'url'],
205227
'customRanking': ['desc(vote_count)', 'asc(name)']
206228
}
207229
```
208230

209-
### Restrict indexing to a subset of your data
231+
## Restrict indexing to a subset of your data
210232

211233
You can add constraints controlling if a record must be indexed or not. `should_index` should be a callable that returns a boolean.
212234

@@ -222,13 +244,18 @@ class ContactIndex(AlgoliaIndex):
222244
should_index = 'is_adult'
223245
```
224246

225-
<!--NO_HTML-->
226-
## Tests
227-
### Run Tests
247+
248+
# Tests
249+
250+
251+
252+
## Run Tests
228253

229254
To run the tests, first find your Algolia application id and Admin API key (found on the Credentials page).
230255

231256
```shell
232257
ALGOLIA_APPLICATION_ID={APPLICATION_ID} ALGOLIA_API_KEY={ADMIN_API_KEY} tox
233258
```
234-
<!--/NO_HTML-->
259+
260+
261+

0 commit comments

Comments
 (0)