Super Search 2.x

Legacy documentation for Super Search 2.x.

Super Search makes use of some advanced syntax in the URI to allow for much more flexible and powerful searches. You can search on any combination of fields, categories, channels, statuses, etc. This page serves as a detailed explanation on how to use the Super Search syntax.

Requirements

When generating a search query in the URI, the query must follow this structure:

  • A search segment must always begin with search&
  • Separate multiple vectors with &
  • Separate search fields and values with =
  • Separate multiple terms using +

So to summarize, a typical search query in the URI might look something like this:

/search&keywords=bird+is+the+word&channel=songs&orderby=title+asc

Keywords

When performing keyword searches (searches that check through all custom fields marked as searchable) with the keywords field, syntax works like this:

  • Single Keyword:

    /search&keywords=pickle

    You can simply pass a keyword. Super Search will find entries with pickle somewhere in the title or searchable custom fields. big pickles would return true, as well as picklepants. If you wish to disable the searching of words within words behaviour, you can specify the search_words_within_words parameter with a value of no in the Results tag.

  • Multiple Keywords:

    /search&keywords=pickles+burgers

    This query will find entries that contain both pickles and burgers in the title or searchable custom fields. You can adjust this behaviour by specifying the inclusive_keywords parameter with a value of no in the Results tag.

  • Negated Keywords:

    /search&keywords=pickles+-burgers

    This query will find entries that contain pickles but NOT burgers in the title or searchable custom fields.

Categories

When performing category searches, syntax works like this:

  • Single Category:

    /search&keywords=pickles&category="Fast+Food"

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are assigned to the Fast Food category. By default, category searching is done on category names. If you wish to change this behaviour to category URL titles or ID's, you can specify the category_indicator parameter in the Results tag.

  • Negated Category:

    /search&keywords=pickles&category=-"Fast+Food"

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are NOT assigned to the Fast Food category.

  • Conjoined Category:

    /search&keywords=pickles&category="Fast+Food"&&Healthy

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are assigned to BOTH the Fast Food and Healthy category.

  • Multiple Categories:

    /search&keywords=pickles&category="Fast+Food"+Healthy

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are assigned to EITHER the Fast Food or Healthy category.

  • Loose Category:

    /search&keywords=pickles&category-like=fast"

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are assigned to ANY categories with fast in the name.

  • Loose Negated Category:

    /search&keywords=pickles&category-like=-fast"

    This query will find entries with pickles in the title or searchable custom fields as long as those entries are NOT assigned to ANY categories with fast in the name.

Channels

When performing channel searches, syntax works like this:

  • Single Channel:

    /search&keywords=pickles&channel=articles

    This query will find entries with pickles in the title or searchable custom fields as long as those entries belong to the Articles channel. The channel name should be designated using the channel short name.

Status

When performing status searches, syntax works like this:

  • Single Status:

    /search&keywords=pickles&status=open

    This query will find entries with pickles in the title or searchable custom fields as long as those entries have a status of open.

  • Negated Status:

    /search&keywords=pickles&status=-closed

    This query will find entries with pickles in the title or searchable custom fields as long as those entries do NOT have a status of closed.

  • Multiple Statuses:

    /search&keywords=pickles&status=open+closed

    This query will find entries with pickles in the title or searchable custom fields as long as those entries have a status of either open or closed.

Custom Fields

You can search directly into searchable custom fields (only, or in addition to keywords search). When performing custom field searches, syntax works like this:

  • Value in a Specific Field:

    /search&summary=pickles

    This query will find entries where the summary field contains the word pickles.

  • Multiple Values in a Specific Field:

    /search&summary=pickles+cheese

    This query will find entries where the summary field contains either the word pickles OR cheese.

  • Negated Value in a Specific Field:

    /search&summary=-pickles

    This query will find entries where the summary field does NOT contain the word pickles.

  • Values in Multiple Fields:

    /search&summary=pickles+cheese&body=burger

    This query will find entries where the summary field contains EITHER the word pickles or cheese, AND the body field contains the word burger.

  • Exact Value(s) in a Specific Field:

    /search&summary-exact=bird+is+the+word

    To perform an exact search, append -exact to the name of the field. This query will find entries where the summary field exactly contains the word(s) bird is the word. If the field for example, contains Haven't you heard, that the bird is the word?, it will not be a valid match.

  • Range from a Value in a Specific Field:

    You can search based on a range of data for a specific field. To do this, just append -from (minimum) or -to (maximum) to the name of the field. When using this on a numerical field, you will want to use the Super Search Field Manager utility in the EE control panel to convert your applicable custom field(s) to the proper MySQL data types (ex: Decimal) so that your range searches take place in a numerical fashion rather than textually.

    /search&price-from=20

    This query will find entries where the price field contains a value equal to or greater than 20.

    /search&price-to=100

    This query will find entries where the price field contains a value equal to or less than 100.

    /search&price-from=20&price-to=100

    This query will find entries where the price field contains a value equal to or greater than 20, AND equal to or less than 100.

  • Empty Fields:

    /search&region-empty=y

    To perform search to see if a custom field is empty or not, append -empty to the name of the field. This query will find entries where the region field is empty.

    /search&region-empty=n

    This query will find entries where the region field is NOT empty.

Relationship Fields

Super Search supports the native ExpressionEngine Relationship fieldtype.

In brief, you can search on specific relationship fields using loose or exact searching. Broad keyword searching is ignored across relationship fields due to the performance problems and confusion that would be experienced.

When performing relationship field searches, syntax works like this:

  • Value in a Specific Relationship Field Title:

    /search&related_news=pick

    This query will find entries where the related_news relationship field contains at least 1 related child entry with a title that contains the word pick.

  • Exact Value(s) in a Specific Relationship Field Title:

    /search&related_news-exact=pickles

    To perform an exact relationship field search, append -exact to the name of the field. This query will find entries where the related_news relationship field contains at least 1 related child entry with a title that exactly contains the word pickles. If the title for example, contains Dill Pickles, it will not be a valid match.

Grid Fields

Super Search supports the native ExpressionEngine Grid fieldtype. This documentation section also applies to the Pixel & Tonic Matrix fieldtype, as they are very similar in how they work.

In brief, you can search on specific Grid fields or Grid field columns like you would any other regular custom field - this includes range, exact, empty syntax as well.

When performing Grid field searches, syntax works like this:

  • Value in an entire Grid field:

    /search&grid_field=apple+pie

    This query will find entries where the grid_field Grid field contains any row of data with a value that contains either the word apple OR pie.

  • Value in a specific column of a Grid field:

    /search&grid_field:col_2=cheesies

    This query will find entries where the col_2 column of the grid_field Grid field contains any row of data with a value that contains the word cheesies.

  • Exact Value(s) in Grid field columns:

    /search&grid_field:col_2=monkey

    Exact searching on Grid fields works just like regular custom field Exact searches. Due to the nature of grid fields and the data they contain, Exact searches are pointless to perform on a whole Grid field, but it is available for searching on rows of data in specific columns. Simply append -exact to the column name in the field. This query will find entries where the col_2 column of the grid_field Grid field contains at least 1 row of data with a value that exactly contains the word monkey. If a row for example, contains monkey pants, it will not be a valid match.

  • Range from a Value in Grid field columns:

    Range searching on Grid fields works just like regular custom field Range searches. Due to the nature of grid fields and the data they contain, Range searches are pointless to perform on a whole Grid field, but it is available for searching on rows of data in specific columns. Range searcing allows you to search based on a range of data for a Grid field column. To do this, just append -from (minimum) or -to (maximum) to the column name in the field.

    /search&product:price-from=20

    This query will find entries where the price column in the product field contains a value equal to or greater than 20.

    /search&product:price-to=100

    This query will find entries where the price column in the product field contains a value equal to or less than 100.

    /search&product:price-from=20&price-to=100

    This query will find entries where the price column in the product field contains a value equal to or greater than 20, AND equal to or less than 100.

  • Empty Fields:

    Empty searching on Grid fields works just like regular custom field Empty searches. Due to the nature of grid fields and the data they contain, Empty searches are pointless to perform on a whole Grid field, but it is available for searching on rows of data in specific columns.

    /search&meal:supper-empty=y

    To perform search to see if any rows for a specific column in a custom field are empty or not, append -empty to the column name in the field. This query will find entries where the supper column in the meal field is empty.

    /search&meal:supper-empty=n

    This query will find entries where the supper column in the meal field is NOT empty.

Ordering & Sorting

Ordering and sorting entries can be done in a couple of ways:

  • URI or POST:

    /search&keywords=apple&orderby=title+desc+entry_date+summary+desc

    This query will find entries where the title or searchable custom fields contain apple. The entries will be ordered by title in descending order, then by entry_date in ascending order, then by summary in descending order. Note: if a desc or asc flag does not follow a field name, sort order will default to ascending (as it did for entry_date in the example above). URI and POST orderby strings will always override the orderby template parameter in Results tag.

  • Template Parameter: orderby="title+desc+entry_date+summary+desc"  Just supply the orderby parameter in your Results tag and give it a string of order rules just as you would in the URI.