Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 112 lines (84 sloc) 4.555 kb
135b649 @erwaller change from rdoc to markdown
erwaller authored
1 Soulmate
2 ========
34a0801 @erwaller Initial commit to soulmate.
erwaller authored
3
fcbfabc @erwaller more doc tweaks
erwaller authored
4 Soulmate is a tool to help solve the common problem of developing a fast autocomplete feature. It uses Redis's sorted sets to build an index of partially completed words and the corresponding top matching items, and provides a simple sinatra app to query them. Soulmate finishes your sentences.
5
6 Soulmate was designed to be simple and fast, and offers the following:
7
8 * Provide suggestions for multiple types of items in a single query (at SeatGeek we're autocompleting for performers, events, and venues)
9 * Results are ordered by a user-specified score
10 * Arbitrary metadata for each item (at SeatGeek we're storing both a url and a subtitle)
98f34e1 @erwaller starting the docs
erwaller authored
11
d5ef330 @erwaller more doc tweaks
erwaller authored
12 An item is a simple JSON object that looks like:
98f34e1 @erwaller starting the docs
erwaller authored
13
04e99c0 @erwaller indent more
erwaller authored
14 {
15 "id": 3,
16 "term": "Citi Field",
17 "score": 81,
18 "data": {
19 "url": "/citi-field-tickets/",
20 "subtitle": "Flushing, NY"
21 }
fac359f @erwaller does this work?
erwaller authored
22 }
98f34e1 @erwaller starting the docs
erwaller authored
23
24 Where `id` is a unique identifier (within the specific type), `term` is the phrase you wish to provide completions for, `score` is a user-specified ranking metric (redis will order things lexigraphically for items with the same score), and `data` is an optional container for metadata you'd like to return when this item is matched (at SeatGeek we're including a url for the item as well as a subtitle for when we present it in an autocomplete dropdown).
25
8ede26a @erwaller more doc tweaks
erwaller authored
26 See Soulmate in action at <a href="http://seatgeek.com/">SeatGeek</a>.
27
135b649 @erwaller change from rdoc to markdown
erwaller authored
28 Getting Started
29 ---------------
30
8ede26a @erwaller more doc tweaks
erwaller authored
31 As always, kick things off with a `gem install`:
32
33 gem install soulmate
34
35 ### Loading Items
98f34e1 @erwaller starting the docs
erwaller authored
36
8c23e4f @erwaller more doc tweaks
erwaller authored
37 You can load data into Soulmate by piping items the JSON lines format into `soulmate load`.
38
39 Here's a sample `venues.json` (one JSON item per line):
98f34e1 @erwaller starting the docs
erwaller authored
40
04e99c0 @erwaller indent more
erwaller authored
41 {"id":1,"term":"Dodger Stadium","score":85,"data":{"url":"\/dodger-stadium-tickets\/","subtitle":"Los Angeles, CA"}}
42 {"id":28,"term":"Angel Stadium","score":85,"data":{"url":"\/angel-stadium-tickets\/","subtitle":"Anaheim, CA"}}
43 {"id":30,"term":"Chase Field ","score":85,"data":{"url":"\/chase-field-tickets\/","subtitle":"Phoenix, AZ"}}
44 {"id":29,"term":"Sun Life Stadium","score":84,"data":{"url":"\/sun-life-stadium-tickets\/","subtitle":"Miami, FL"}}
45 {"id":2,"term":"Turner Field","score":83,"data":{"url":"\/turner-field-tickets\/","subtitle":"Atlanta, GA"}}
fac359f @erwaller does this work?
erwaller authored
46
8c23e4f @erwaller more doc tweaks
erwaller authored
47 And here's the load command (Soulmate assumes redis is running locally on the default port, or you can specify a redis connection string with the `--redis` argument):
fac359f @erwaller does this work?
erwaller authored
48
04e99c0 @erwaller indent more
erwaller authored
49 $ soulmate load venue --redis=redis://localhost:6379/0 < venues.json
fac359f @erwaller does this work?
erwaller authored
50
8ede26a @erwaller more doc tweaks
erwaller authored
51 ### Querying for Data
52
fac359f @erwaller does this work?
erwaller authored
53 Once it's loaded, we can query this data by starting `soulmate-web`:
54
8c23e4f @erwaller more doc tweaks
erwaller authored
55 $ soulmate-web --foreground --no-launch --redis=redis://localhost:6379/0
fac359f @erwaller does this work?
erwaller authored
56
135b649 @erwaller change from rdoc to markdown
erwaller authored
57 And viewing the service in your browser: <a href="http://localhost:5678/search?types[]=venue&term=stad">http://localhost:5678/search?types[]=venue&term=stad</a>. You should see something like:
58
04e99c0 @erwaller indent more
erwaller authored
59 {
60 "term": "stad",
61 "results": {
62 "venue": [
63 {
64 "id": 28,
65 "term": "Angel Stadium",
66 "score": 85,
67 "data": {
68 "url": "/angel-stadium-tickets/",
69 "subtitle": "Anaheim, CA"
70 }
71 },
72 {
73 "id": 1,
74 "term": "Dodger Stadium",
75 "score": 85,
76 "data": {
77 "url": "/dodger-stadium-tickets/",
78 "subtitle": "Los Angeles, CA"
79 }
80 },
81 {
82 "id": 29,
83 "term": "Sun Life Stadium",
84 "score": 84,
85 "data": {
86 "url": "/sun-life-stadium-tickets/",
87 "subtitle": "Miami, FL"
88 }
135b649 @erwaller change from rdoc to markdown
erwaller authored
89 }
04e99c0 @erwaller indent more
erwaller authored
90 ]
91 }
135b649 @erwaller change from rdoc to markdown
erwaller authored
92 }
34a0801 @erwaller Initial commit to soulmate.
erwaller authored
93
8ede26a @erwaller more doc tweaks
erwaller authored
94 The `/search` method supports multiple `types` as well as an optional `limit`. For example: `http://localhost:5678/search?types[]=event&types[]=venue&types[]=performer&limit=3&term=yank`.
95
8c23e4f @erwaller more doc tweaks
erwaller authored
96 Contributing to soulmate
97 ------------------------
34a0801 @erwaller Initial commit to soulmate.
erwaller authored
98
99 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
100 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
101 * Fork the project
102 * Start a feature/bugfix branch
103 * Commit and push until you are happy with your contribution
104 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
105
8c23e4f @erwaller more doc tweaks
erwaller authored
106 Copyright
107 ---------
34a0801 @erwaller Initial commit to soulmate.
erwaller authored
108
109 Copyright (c) 2011 Eric Waller. See LICENSE.txt for
110 further details.
111
Something went wrong with that request. Please try again.