/**
* Lets modules alter a search query before executing it.
*
* @param SearchApiQueryInterface $query
* The search query being executed.
*/
function hook_search_api_query_alter(SearchApiQueryInterface $query)
{
// Exclude entities with ID 0. (Assume the ID field is always indexed.)
if ($query->getIndex()->getEntityType()) {
$info = entity_get_info($query->getIndex()->getEntityType());
$query->condition($info['entity keys']['id'], 0, '<>');
}
}
/**
* Executes a search on the server represented by this object.
*
* If the service class supports facets, it should check for an additional
* option on the query object:
* - search_api_facets: An array of facets to return along with the results
* for this query. The array is keyed by an arbitrary string which should
* serve as the facet's unique identifier for this search. The values are
* arrays with the following keys:
* - field: The field to construct facets for.
* - limit: The maximum number of facet terms to return. 0 or an empty
* value means no limit.
* - min_count: The minimum number of results a facet value has to have in
* order to be returned.
* - missing: If TRUE, a facet for all items with no value for this field
* should be returned (if it conforms to limit and min_count).
* - operator: (optional) If the service supports "OR" facets and this key
* contains the string "or", the returned facets should be "OR" facets. If
* the server doesn't support "OR" facets, this key can be ignored.
*
* The basic principle of facets is explained quite well in the
* @link http://en.wikipedia.org/wiki/Faceted_search Wikipedia article on
* "Faceted search" @endlink. Basically, you should return for each field
* filter values which would yield some results when used with the search.
* E.g., if you return for a field $field the term $term with $count results,
* the given $query along with
* $query->condition($field, $term)
* should yield exactly (or about) $count results.
*
* For "OR" facets, all existing filters on the facetted field should be
* ignored for computing the facets.
*
* @param $query
* The SearchApiQueryInterface object to execute.
*
* @return array
* An associative array containing the search results, as required by
* SearchApiQueryInterface::execute().
* In addition, if the "search_api_facets" option is present on the query,
* the results should contain an array of facets in the "search_api_facets"
* key, as specified by the option. The facets array should be keyed by the
* facets' unique identifiers, and contain a numeric array of facet terms,
* sorted descending by result count. A term is represented by an array with
* the following keys:
* - count: Number of results for this term.
* - filter: The filter to apply when selecting this facet term. A filter is
* a string of one of the following forms:
* - "VALUE": Filter by the literal value VALUE (always include the
* quotes, not only for strings).
* - [VALUE1 VALUE2]: Filter for a value between VALUE1 and VALUE2. Use
* parantheses for excluding the border values and square brackets for
* including them. An asterisk (*) can be used as a wildcard. E.g.,
* (* 0) or [* 0) would be a filter for all negative values.
* - !: Filter for items without a value for this field (i.e., the
* "missing" facet).
*
* @throws SearchApiException
* If an error prevented the search from completing.
*/
public function search(SearchApiQueryInterface $query)
{
// We assume here that we have an AI search which understands English
// commands.
// First, create the normal search query, without facets.
$search = new SuperCoolAiSearch($query->getIndex());
$search->cmd('create basic search for the following query', $query);
$ret = $search->cmd('return search results in Search API format');
// Then, let's see if we should return any facets.
if ($facets = $query->getOption('search_api_facets')) {
// For the facets, we need all results, not only those in the specified
// range.
$results = $search->cmd('return unlimited search results as a set');
foreach ($facets as $id => $facet) {
$field = $facet['field'];
$limit = empty($facet['limit']) ? 'all' : $facet['limit'];
$min_count = $facet['min_count'];
$missing = $facet['missing'];
$or = isset($facet['operator']) && $facet['operator'] == 'or';
// If this is an "OR" facet, existing filters on the field should be
// ignored for computing the facets.
// You can ignore this if your service class doesn't support the
// "search_api_facets_operator_or" feature.
if ($or) {
// We have to execute another query (in the case of this hypothetical
// search backend, at least) to get the right result set to facet.
$tmp_search = new SuperCoolAiSearch($query->getIndex());
$tmp_search->cmd('create basic search for the following query', $query);
$tmp_search->cmd("remove all conditions for field {$field}");
$tmp_results = $tmp_search->cmd('return unlimited search results as a set');
} else {
// Otherwise, we can just use the normal results.
$tmp_results = $results;
}
$filters = array();
if ($search->cmd("{$field} is a date or numeric field")) {
// For date, integer or float fields, range facets are more useful.
$ranges = $search->cmd("list {$limit} ranges of field {$field} in the following set", $tmp_results);
foreach ($ranges as $range) {
if ($range->getCount() >= $min_count) {
// Get the lower and upper bound of the range. * means unlimited.
$lower = $range->getLowerBound();
$lower = $lower == SuperCoolAiSearch::RANGE_UNLIMITED ? '*' : $lower;
$upper = $range->getUpperBound();
$upper = $upper == SuperCoolAiSearch::RANGE_UNLIMITED ? '*' : $upper;
// Then, see whether the bounds are included in the range. These
// can be specified independently for the lower and upper bound.
// Parentheses are used for exclusive bounds, square brackets are
// used for inclusive bounds.
$lowChar = $range->isLowerBoundInclusive() ? '[' : '(';
$upChar = $range->isUpperBoundInclusive() ? ']' : ')';
// Create the filter, which separates the bounds with a single
// space.
$filter = "{$lowChar}{$lower} {$upper}{$upChar}";
$filters[$filter] = $range->getCount();
}
}
} else {
// Otherwise, we use normal single-valued facets.
$terms = $search->cmd("list {$limit} values of field {$field} in the following set", $tmp_results);
foreach ($terms as $term) {
if ($term->getCount() >= $min_count) {
// For single-valued terms, we just need to wrap them in quotes.
$filter = '"' . $term->getValue() . '"';
$filters[$filter] = $term->getCount();
}
}
}
// If we should also return a "missing" facet, compute that as the
// number of results without a value for the facet field.
if ($missing) {
$count = $search->cmd("return number of results without field {$field} in the following set", $tmp_results);
if ($count >= $min_count) {
$filters['!'] = $count;
}
}
// Sort the facets descending by result count.
arsort($filters);
// With the "missing" facet, we might have too many facet terms (unless
// $limit was empty and is therefore now set to "all"). If this is the
// case, remove those with the lowest number of results.
while (is_numeric($limit) && count($filters) > $limit) {
array_pop($filters);
}
// Now add the facet terms to the return value, as specified in the doc
// comment for this method.
foreach ($filters as $filter => $count) {
$ret['search_api_facets'][$id][] = array('count' => $count, 'filter' => $filter);
}
}
}
// Return the results, which now also includes the facet information.
return $ret;
}