interface SearchApiMultiQueryInterface in Search API Multi-Index Searches 7

Interface representing a search query on multiple Search API indexes.

For discerning from which index a certain field should be used (for filtering or specifying the fulltext fields, for instance), all field identifiers have to be prefixed with their index' machine name, seperated by a colon. For example, to filter on the "author:name" field from the index with the machine name "default_node_index", use "default_node_index:author:name" as the identifier.

Methods not returning something else will return the object itself, so calls can be chained.

Hierarchy

interface \SearchApiMultiQueryInterface

Expanded class hierarchy of SearchApiMultiQueryInterface

All classes that implement SearchApiMultiQueryInterface

File

./search_api_multi.query.inc, line 16

View source

interface SearchApiMultiQueryInterface {

  /**
   * Constructs a new query object.
   *
   * @param array $options
   *   Associative array of options configuring this query. Recognized options
   *   are:
   *   - conjunction: The type of conjunction to use for this query - either
   *     'AND' or 'OR'. 'AND' by default. This only influences the search keys,
   *     filters will always use AND by default.
   *   - 'parse mode': The mode with which to parse the $keys variable, if it
   *     is set and not already an array. See SearchApiMultiQuery::parseModes() for
   *     recognized parse modes.
   *   - languages: The languages to search for, as an array of language IDs.
   *     If not specified, all languages will be searched. Language-neutral
   *     content (LANGUAGE_NONE) is always searched.
   *   - offset: The position of the first returned search results relative to
   *     the whole result on the server.
   *   - limit: The maximum number of search results to return. -1 means no
   *     limit.
   *   - 'filter class': Can be used to change the SearchApiQueryFilterInterface
   *     implementation to use.
   *   - 'search id': A string that will be used as the identifier when storing
   *     this search in the static cache.
   *   All options are optional.
   *
   * @throws SearchApiException
   *   If a search with these options won't be possible.
   */
  public function __construct(array $options = array());

  /**
   * Retrieve a list of all parse modes supported by this query class.
   *
   * @return array
   *   An associative array of parse modes recognized by objects of this class.
   *   The keys are the parse modes' ids, values are associative arrays
   *   containing the following entries:
   *   - name: The translated name of the parse mode.
   *   - description: (optional) A translated text describing the parse mode.
   */
  public function parseModes();

  /**
   * Method for creating a filter to use with this query object.
   *
   * @param string $conjunction
   *   The conjunction to use for the filter - either 'AND' or 'OR'.
   * @param string[] $tags
   *   (Optional) An arbitrary set of tags. Can be used to identify this filter
   *   down the line if necessary. This is primarily used by the facet system
   *   to support OR facet queries.
   *
   * @return SearchApiQueryFilterInterface
   *   A filter object that is set to use the specified conjunction.
   */
  public function createFilter($conjunction = 'AND', array $tags = array());

  /**
   * Sets the keys to search for.
   *
   * If this method is not called on the query before execution, or it is called
   * with NULL, this will be a filter-only query.
   *
   * @param string|array|null $keys
   *   A string with the unparsed search keys, or NULL to use no search keys.
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function keys($keys = NULL);

  /**
   * Sets the fields that will be searched for the search keys.
   *
   * If this method is not called on the query before execution, or it is called
   * with NULL, all fulltext fields should be searched.
   *
   * @param array|null $fields
   *   An array containing fulltext fields that should be searched, or NULL if
   *   all fields should be searched.
   *
   * @throws SearchApiException
   *   If one of the fields isn't of type "text".
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function fields($fields = NULL);

  /**
   * Adds a subfilter to this query's filter.
   *
   * @param SearchApiQueryFilterInterface $filter
   *   A SearchApiQueryFilter object that should be added as a subfilter.
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function filter(SearchApiQueryFilterInterface $filter);

  /**
   * Add a new ($field $operator $value) condition filter.
   *
   * @param string $field
   *   The field to filter on. Either a field specification as detailed in the
   *   class comment, or the special field "search_api_multi_index" which means
   *   a filter on the searched indexes.
   * @param mixed $value
   *   The value the field should have (or be related to by the operator).
   * @param string $operator
   *   The operator to use for checking the constraint. The following operators
   *   are supported for primitive types: "=", "<>", "<", "<=", ">=", ">". They
   *   have the same semantics as the corresponding SQL operators.
   *   If $field is a fulltext field, $operator can only be "=" or "<>", which
   *   are in this case interpreted as "contains" or "doesn't contain",
   *   respectively.
   *   If $value is NULL, $operator also can only be "=" or "<>", meaning the
   *   field must have no or some value, respectively.
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function condition($field, $value, $operator = '=');

  /**
   * Add a sort directive to this search query.
   *
   * If no sort is manually set, the results will be sorted descending by
   * relevance.
   *
   * How sorts on index-specific fields are handled may differ between service
   * backends.
   *
   * @param string $field
   *   The field to sort by. The special fields 'search_api_relevance' (sort by
   *   relevance) and 'search_api_id' (sort by item id) may be used.
   * @param string $order
   *   The order to sort items in - either 'ASC' or 'DESC'.
   *
   * @throws SearchApiException
   *   If the field is multi-valued or of a fulltext type.
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function sort($field, $order = 'ASC');

  /**
   * Adds a range of results to return. This will be saved in the query's
   * options. If called without parameters, this will remove all range
   * restrictions previously set.
   *
   * @param int|null $offset
   *   The zero-based offset of the first result returned.
   * @param int|null $limit
   *   The number of results to return.
   *
   * @return SearchApiMultiQueryInterface
   *   The called object.
   */
  public function range($offset = NULL, $limit = NULL);

  /**
   * Executes this search query.
   *
   * @return array
   *   An associative array containing the search results. The following keys
   *   are standardized:
   *   - 'result count': The overall number of results for this query, without
   *     range restrictions. Might be approximated, for large numbers.
   *   - results: An array of results, ordered as specified. The array keys are
   *     arbitrary unique keys, values are arrays containing the following keys:
   *     - id: The item's ID.
   *     - index_id: The machine name of the index this item was found on.
   *     - score: A float measuring how well the item fits the search.
   *     - fields: (optional) If set, an array containing some field values
   *       already ready-to-use, keyed by their field identifiers (without index
   *       prefix). This allows search engines (or postprocessors) to store
   *       extracted fields so other modules don't have to extract them again.
   *       This fields should always be checked by modules that want to use
   *       field contents of the result items.
   *     - entity (optional): If set, the fully loaded result item. This field
   *       should always be used by modules using search results, to avoid
   *       duplicate item loads.
   *     - excerpt (optional): If set, an HTML text containing highlighted
   *       portions of the fulltext that match the query.
   *   - warnings: A numeric array of translated warning messages that may be
   *     displayed to the user.
   *   - ignored: A numeric array of search keys that were ignored for this
   *     search (e.g., because of being too short or stop words).
   *   - performance: An associative array with the time taken (as floats, in
   *     seconds) for specific parts of the search execution:
   *     - complete: The complete runtime of the query.
   *     - hooks: Hook invocations and other client-side preprocessing.
   *     - preprocessing: Preprocessing of the service class.
   *     - execution: The actual query to the search server, in whatever form.
   *     - postprocessing: Preparing the results for returning.
   *   Additional metadata may be returned in other keys. Only 'result count'
   *   and 'result' always have to be set, all other entries are optional.
   */
  public function execute();

  /**
   * Retrieves the searched indexes.
   *
   * @return SearchApiIndex[]
   *   An array of SearchApiIndex objects representing all indexes that will be
   *   used for this search, keyed by machine names.
   */
  public function getIndexes();

  /**
   * Retrieves the search keys.
   *
   * @return array|string|null
   *   This object's search keys - either a string or an array specifying a
   *   complex search expression.
   *   An array will contain a '#conjunction' key specifying the conjunction
   *   type, and search strings or nested expression arrays at numeric keys.
   *   Additionally, a '#negation' key might be present, which means – unless it
   *   maps to a FALSE value – that the search keys contained in that array
   *   should be negated, i.e. not be present in returned results.
   */
  public function &getKeys();

  /**
   * Retrieves the original, unprocessed search keys.
   *
   * @return array|string|null
   *   The unprocessed search keys, exactly as passed to this object. Has the
   *   same format as getKeys().
   */
  public function getOriginalKeys();

  /**
   * Retrieves the searched fulltext fields.
   *
   * @return array|null
   *   An array containing the fields that should be searched for the search
   *   keys.
   */
  public function &getFields();

  /**
   * Retrieves the query's filter object.
   *
   * @return SearchApiQueryFilterInterface
   *   This object's associated filter object.
   */
  public function getFilter();

  /**
   * Retrieves the set sorts.
   *
   * @return array
   *   An array specifying the sort order for this query. Array keys are the
   *   field names in order of importance, the values are the respective order
   *   in which to sort the results according to the field.
   */
  public function &getSort();

  /**
   * Retrieves a single option.
   *
   * @param string $name
   *   The name of an option.
   * @param mixed $default
   *   The default in case the option isn't set.
   *
   * @return mixed
   *   The value of the option with the specified name, if set; $default
   *   otherwise.
   */
  public function getOption($name, $default = NULL);

  /**
   * Sets an option.
   *
   * @param string $name
   *   The name of an option.
   * @param mixed $value
   *   The new value of the option.
   *
   * @return mixed
   *   The option's previous value.
   */
  public function setOption($name, $value);

  /**
   * Retrieves all options for this query.
   *
   * @return array
   *   An associative array of query options.
   */
  public function &getOptions();

}

Members

Name	Modifiers	Type	Description	Overrides
SearchApiMultiQueryInterface::condition	public	function	Add a new ($field $operator $value) condition filter.	1
SearchApiMultiQueryInterface::createFilter	public	function	Method for creating a filter to use with this query object.	1
SearchApiMultiQueryInterface::execute	public	function	Executes this search query.	1
SearchApiMultiQueryInterface::fields	public	function	Sets the fields that will be searched for the search keys.	1
SearchApiMultiQueryInterface::filter	public	function	Adds a subfilter to this query's filter.	1
SearchApiMultiQueryInterface::getFields	public	function	Retrieves the searched fulltext fields.	1
SearchApiMultiQueryInterface::getFilter	public	function	Retrieves the query's filter object.	1
SearchApiMultiQueryInterface::getIndexes	public	function	Retrieves the searched indexes.	1
SearchApiMultiQueryInterface::getKeys	public	function	Retrieves the search keys.	1
SearchApiMultiQueryInterface::getOption	public	function	Retrieves a single option.	1
SearchApiMultiQueryInterface::getOptions	public	function	Retrieves all options for this query.	1
SearchApiMultiQueryInterface::getOriginalKeys	public	function	Retrieves the original, unprocessed search keys.	1
SearchApiMultiQueryInterface::getSort	public	function	Retrieves the set sorts.	1
SearchApiMultiQueryInterface::keys	public	function	Sets the keys to search for.	1
SearchApiMultiQueryInterface::parseModes	public	function	Retrieve a list of all parse modes supported by this query class.	1
SearchApiMultiQueryInterface::range	public	function	Adds a range of results to return. This will be saved in the query's options. If called without parameters, this will remove all range restrictions previously set.	1
SearchApiMultiQueryInterface::setOption	public	function	Sets an option.	1
SearchApiMultiQueryInterface::sort	public	function	Add a sort directive to this search query.	1
SearchApiMultiQueryInterface::__construct	public	function	Constructs a new query object.	1

You are here

interface SearchApiMultiQueryInterface in Search API Multi-Index Searches 7

Hierarchy

File

Members

API Navigation