SearchAPI

Proposed API for Calagator Search / Filter

**Labels:**Phase-Design,Phase-Implementation

Do not rely on this. It was just a discussion draft. It will (and already has) changed while being implemented.

Proposed generalized event search / filter API for Calagator

Do not rely on this. It was just a discussion draft. It will (and already has) changed while being implemented.

Proposed generalized event search / filter API for Calagator

• Parameters
• Examples
• Notes
• Other References

Describes a proposed API for a generalized search/filter for events.

Parameters

type => specifies a type of text search. The type can be a fuzzy search in all fields (including tag), an exact filter on tags, combinations of those two, or none. If the type parameter is omitted, Calagator will check if one of query or tag is present, and if so, perform that type of search. Values:

• string - fuzzy filter on +query+ for all fields (including tags). Internally uses find_by_solr.
• tag_all - exact search for events that have all tag(s) included in +tag+. Internally uses tagged_with. (not yet implemented)
• tag_any - (not yet implemented) exact search for events that have any tag included in +tag+.
• string_and_tag - (not yet implemented) intersection of +query+ and +tag+ results
• string_or_tag - (not yet implemented)
• nil - no text filter. Internally uses find.

query => a string specifying words / phrases for +string+-type (fuzzy) search. Mandatory if typeincludes "string". Internally uses find_by_solr.

tag => string of tags for +tag+-type search. Mandatory if type includes "tags". Internally uses tagged_with.

date[start] => return only events occurring on or after this date

date[end] => return only events occurring on or before this date

skip_old => Return old entries? Defaults to false if type includes query or tag, otherwise defaults to true. Values:

• 1 - synonym for true
• false - return old events
• true - do not return old events

current - shortcut for skip_old=true

order => How to order the entries. Defaults to score if type==tags_all or tags_any; to date if type==nil or no type. Values:

• date - chronological order
• score - sort with most relevant matches first. The default fortype==tags_all and for type==tags_any.
• name - synonym for title
• title - sort by event title
• venue - sort by venue title

limit => positive integer that is maximum number of entries to return. If type includes tag, defaults to internal constant SOLR_SEARCH_MATCHES(currently set to 50) for the tag portion of the search. There probably should be a default limit for other types.

group => how to group the events.

• currency - grouped by currency, See example above. This is the default if type includes query or tag.

Examples

http://calagator.org/events/search
  => all events in the database (sorted chronologically)

http://calagator.org/events/search?skip_old=1
  or
http://calagator.org/events/search?&current
  => all current events (events occurring today or later)

http://calagator.org/events/search?date[start]=2009-01-01&date[end]=2009-01-31
  => all events occurring January 2009

http://calagator.org/events/search?date[start]=2009-01-02&date[end]=2009-12-31&order=venue
  => all events occurring in 2009, sorted by venue title

http://calagator.org/events/search?date[start]=2009-01-01
  => all events occurring on or after January 1, 2009

http://calagator.org/events/search?date[end]=2009-12-31
  => all events occurring 2009 or earlier

http://calagator.org/events/search?query=ruby
  => (up to 50) events matching fuzzy search for "ruby" (grouped by currency)

http://calagator.org/events/search?query=ruby&group=false
  => (up to 50) events matching fuzzy search for "ruby", ungrouped

http://calagator.org/events/search?query=ruby&skip_old=1
  => (up to 50) current events matching fuzzy search for "ruby"

http://calagator.org/events/search?tag=ruby
  => all events tagged with "ruby", grouped by currency

http://calagator.org/events/search?tag=ruby&skip_old=1
  => all current events tagged with "ruby"

http://calagator.org/events/search?tag=ruby&skip_old=1&limit=10
  => first 10 current events tagged with "ruby"

Notes

A top-level method generally will parallel the API. The top-level method returns an Array or Hash of non-duplicate Event instances matching the parameters; that method will return an Array, except when a valid +group+ is specified, in which case it returns a Hash like:

 
{ :current => [ my_current_event, my_other_current_event ], :past => [ my_past_event ], } 

Other References

• Advanced Search UI that parallels this API
• Searching, tags and JSON PDX Tech Calendar Discussion
• Wire frames for temporary Search UI PDX Tech Calendar Discussion