You are here

Home » API reference » Search API 8 » QueryInterface.php

interface QueryInterface in Search API 8

Represents a search query on a Search API index.

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

Hierarchy

Expanded class hierarchy of QueryInterface

All classes that implement QueryInterface

33 files declare their use of QueryInterface
BackendPluginBase.php in src/Backend/BackendPluginBase.php
BackendPluginBaseTest.php in tests/src/Unit/BackendPluginBaseTest.php
BackendSpecificInterface.php in src/Backend/BackendSpecificInterface.php
BackendTest.php in modules/search_api_db/tests/src/Kernel/BackendTest.php
BackendTestBase.php in tests/src/Kernel/BackendTestBase.php

... See full list

File

src/Query/QueryInterface.php, line 14

Namespace

Drupal\search_api\Query
View source 
interface QueryInterface extends ConditionSetInterface {

  /**
   * Constant representing ascending sorting.
   */
  const SORT_ASC = 'ASC';

  /**
   * Constant representing descending sorting.
   */
  const SORT_DESC = 'DESC';

  /**
   * Constant representing a completely unprocessed search.
   *
   * No processors or hooks will be invoked for searches with this processing
   * level.
   */
  const PROCESSING_NONE = 0;

  /**
   * Constant representing a search with only basic processing.
   *
   * Hook implementations or processors adding extra functionality, not
   * necessary for a basic search, should ignore searches with this level.
   *
   * Typical examples for such "extra functionality" would be facets,
   * spellchecking or highlighting.
   */
  const PROCESSING_BASIC = 1;

  /**
   * Constant representing a search with normal/full processing.
   *
   * This is the default for queries where no processing level has been
   * explicitly set.
   */
  const PROCESSING_FULL = 2;

  /**
   * Instantiates a new instance of this query class.
   *
   * @param \Drupal\search_api\IndexInterface $index
   *   The index for which the query should be created.
   * @param array $options
   *   (optional) The options to set for the query.
   *
   * @return static
   *   A query object to use.
   *
   * @throws \Drupal\search_api\SearchApiException
   *   Thrown if a search on that index (or with those options) won't be
   *   possible.
   */
  public static function create(IndexInterface $index, array $options = []);

  /**
   * Retrieves the search ID.
   *
   * @param bool $generate
   *   (optional) If TRUE and no search ID was set yet for this query, generate
   *   one automatically. If FALSE, NULL will be returned in this case.
   *
   * @return string|null
   *   The search ID, or NULL if none was set yet and $generate is FALSE.
   */
  public function getSearchId($generate = TRUE);

  /**
   * Sets the search ID.
   *
   * The search ID is a freely-chosen machine name identifying this search query
   * for purposes of identifying the query later in the page request. It will be
   * used, amongst other things, to identify the query in the search results
   * cache service.
   *
   * If the set ID is the same as a display plugin ID, this will also
   * automatically set that display plugin for this query. Queries for the same
   * display or search page should therefore usually use the same search ID.
   *
   * @param string $search_id
   *   The new search ID.
   *
   * @return $this
   *
   * @see \Drupal\search_api\Query\QueryInterface::getDisplayPlugin()
   * @see \Drupal\search_api\Query\ResultsCacheInterface
   */
  public function setSearchId($search_id);

  /**
   * Retrieves the search display associated with this query (if any).
   *
   * If the search ID set for this query corresponds to a display plugin ID,
   * that display will be returned. Otherwise, NULL is returned.
   *
   * @return \Drupal\search_api\Display\DisplayInterface|null
   *   The search display associated with this query, if any; NULL otherwise.
   */
  public function getDisplayPlugin();

  /**
   * Retrieves the parse mode.
   *
   * @return \Drupal\search_api\ParseMode\ParseModeInterface
   *   The parse mode.
   */
  public function getParseMode();

  /**
   * Sets the parse mode.
   *
   * @param \Drupal\search_api\ParseMode\ParseModeInterface $parse_mode
   *   The parse mode.
   *
   * @return $this
   */
  public function setParseMode(ParseModeInterface $parse_mode);

  /**
   * Retrieves the languages that will be searched by this query.
   *
   * @return string[]|null
   *   The language codes of languages that will be searched by this query, or
   *   NULL if there shouldn't be any restriction on the language.
   */
  public function getLanguages();

  /**
   * Sets the languages that should be searched by this query.
   *
   * @param string[]|null $languages
   *   The language codes to search for, or NULL to not restrict the query to
   *   specific languages.
   *
   * @return $this
   */
  public function setLanguages(array $languages = NULL);

  /**
   * Creates a new condition group to use with this query object.
   *
   * @param string $conjunction
   *   The conjunction to use for the condition group – either 'AND' or 'OR'.
   * @param string[] $tags
   *   (optional) Tags to set on the condition group.
   *
   * @return \Drupal\search_api\Query\ConditionGroupInterface
   *   A condition group object that is set to use the specified conjunction.
   *
   * @todo Add $add_directly = TRUE parameter.
   */
  public function createConditionGroup($conjunction = 'AND', array $tags = []);

  /**
   * Sets the keys to search for.
   *
   * If this method is not called on the query before execution, this will be a
   * filters-only query.
   *
   * @param string|array|null $keys
   *   A string with the search keys, in one of the formats specified by
   *   getKeys(). A passed string will be parsed according to the set parse
   *   mode. Use NULL to not use any search keys.
   *
   * @return $this
   */
  public function keys($keys = NULL);

  /**
   * Sets the fields that will be searched for the search keys.
   *
   * If this is not called, all fulltext fields will be searched.
   *
   * @param array $fields
   *   An array containing fulltext fields that should be searched.
   *
   * @return $this
   */
  public function setFulltextFields(array $fields = NULL);

  /**
   * Adds a sort directive to this search query.
   *
   * If no sort is manually set, the results will be sorted descending by
   * relevance.
   *
   * @param string $field
   *   The ID of the field to sort by. In addition to all indexed fields on the
   *   index, the following special field IDs may be used:
   *   - search_api_relevance: Sort by relevance.
   *   - search_api_datasource: Sort by datasource.
   *   - search_api_language: Sort by language.
   *   - search_api_id: Sort by item ID.
   * @param string $order
   *   The order to sort items in – one of the SORT_* constants.
   *
   * @return $this
   *
   * @see \Drupal\search_api\Query\QueryInterface::SORT_ASC
   * @see \Drupal\search_api\Query\QueryInterface::SORT_DESC
   */
  public function sort($field, $order = self::SORT_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 $this
   */
  public function range($offset = NULL, $limit = NULL);

  /**
   * Retrieves the processing level for this query.
   *
   * @return int
   *   The processing level of this query, as one of the
   *   \Drupal\search_api\Query\QueryInterface::PROCESSING_* constants.
   *
   * @see \Drupal\search_api\Query\QueryInterface::PROCESSING_NONE
   * @see \Drupal\search_api\Query\QueryInterface::PROCESSING_BASIC
   * @see \Drupal\search_api\Query\QueryInterface::PROCESSING_FULL
   */
  public function getProcessingLevel();

  /**
   * Sets the processing level for this query.
   *
   * @param int $level
   *   The processing level of this query, as one of the
   *   \Drupal\search_api\Query\QueryInterface::PROCESSING_* constants.
   *
   * @return $this
   */
  public function setProcessingLevel($level);

  /**
   * Aborts this query.
   *
   * This will mean that, while the query object otherwise acts normally, it
   * won't be passed to the server and won't return any results.
   *
   * @param \Drupal\Component\Render\MarkupInterface|string|null $error_message
   *   (optional) A translated error message explaining the reason why the
   *   query was aborted.
   *
   * @return $this
   */
  public function abort($error_message = NULL);

  /**
   * Determines whether this query was aborted.
   *
   * @return bool
   *   TRUE if the query was aborted, FALSE otherwise.
   */
  public function wasAborted();

  /**
   * Retrieves the error message explaining why this query was aborted, if any.
   *
   * @return \Drupal\Component\Render\MarkupInterface|string|null
   *   An error message, if set, or NULL if none was set. Please be aware that
   *   a NULL message does not have to mean that the query was not aborted.
   */
  public function getAbortMessage();

  /**
   * Executes this search query.
   *
   * The results of the search will be cached on the query, so subsequent calls
   * of this method will always return the same result set (even if conditions
   * were changed in between). If you want to re-execute a query, use
   * getOriginalQuery().
   *
   * @return \Drupal\search_api\Query\ResultSetInterface
   *   The results of the search.
   *
   * @throws \Drupal\search_api\SearchApiException
   *   Thrown if an error occurred during the search.
   */
  public function execute();

  /**
   * Prepares the query object for the search.
   *
   * This method should always be called by execute() and contain all necessary
   * operations that have to be execute before the query is passed to the
   * server's search() method.
   */
  public function preExecute();

  /**
   * Postprocesses the search results before they are returned.
   *
   * This method should always be called by execute() and contain all necessary
   * operations after the results are returned from the server.
   */
  public function postExecute();

  /**
   * Determines whether this query has been executed already.
   *
   * @return bool
   *   TRUE if this query has been executed already, FALSE otherwise.
   */
  public function hasExecuted();

  /**
   * Retrieves this query's result set.
   *
   * If this query hasn't been executed yet, the results will be incomplete.
   *
   * @return \Drupal\search_api\Query\ResultSetInterface
   *   The results of the search.
   *
   * @see \Drupal\search_api\Query\QueryInterface::hasExecuted()
   */
  public function getResults();

  /**
   * Retrieves the index associated with this search.
   *
   * @return \Drupal\search_api\IndexInterface
   *   The search index this query should be executed on.
   */
  public function getIndex();

  /**
   * Retrieves the search keys for this query.
   *
   * @return array|string|null
   *   This object's search keys, in the format described by
   *   \Drupal\search_api\ParseMode\ParseModeInterface::parseInput(). Or NULL if
   *   the query doesn't have any search keys set.
   *
   * @see keys()
   */
  public function &getKeys();

  /**
   * Retrieves the unparsed search keys for this query as originally entered.
   *
   * @return array|string|null
   *   The unprocessed search keys, exactly as passed to this object. Has the
   *   same format as the return value of QueryInterface::getKeys().
   *
   * @see keys()
   */
  public function getOriginalKeys();

  /**
   * Retrieves the fulltext fields that will be searched for the search keys.
   *
   * @return string[]|null
   *   An array containing the fields that should be searched for the search
   *   keys, or NULL if all indexed fulltext fields should be used.
   *
   * @see setFulltextFields()
   */
  public function &getFulltextFields();

  /**
   * Retrieves the condition group object associated with this search query.
   *
   * @return \Drupal\search_api\Query\ConditionGroupInterface
   *   This object's associated condition group object.
   */
  public function getConditionGroup();

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

  /**
   * Retrieves an option set on this search query.
   *
   * @param string $name
   *   The name of the option.
   * @param mixed $default
   *   (optional) The value to return if the specified option is not 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 for this search query.
   *
   * @param string $name
   *   The name of an option. The following options are recognized by default:
   *   - offset: The position of the first returned search results relative to
   *     the whole result in the index.
   *   - limit: The maximum number of search results to return. -1 means no
   *     limit.
   *   - 'skip result count': If present and set to TRUE, the search's result
   *     count will not be needed. Service classes can check for this option to
   *     possibly avoid executing expensive operations to compute the result
   *     count in cases where it is not needed.
   *   - search_api_access_account: The account which will be used for entity
   *     access checks, if available and enabled for the index.
   *   - search_api_bypass_access: If set to TRUE, entity access checks will be
   *     skipped, even if enabled for the index.
   *   - search_api_retrieved_field_values: A list of IDs of fields whose values
   *     should be returned along with the results by the backend, if possible.
   *     For backends that support retrieving fields values, this allows them to
   *     only retrieve the values that are actually needed.
   *   However, contrib modules might introduce arbitrary other keys with their
   *   own, special meaning. (Usually they should be prefixed with the module
   *   name, though, to avoid conflicts.)
   * @param mixed $value
   *   The new value of the option.
   *
   * @return mixed
   *   The option's previous value, or NULL if none was set.
   */
  public function setOption($name, $value);

  /**
   * Retrieves all options set for this search query.
   *
   * The return value is a reference to the options so they can also be altered
   * this way.
   *
   * @return array
   *   An associative array of query options.
   */
  public function &getOptions();

  /**
   * Sets the given tag on this query.
   *
   * Tags are strings that categorize a query. A query may have any number of
   * tags. Tags are used to mark a query so that alter hooks may decide if they
   * wish to take action. Tags should be all lower-case and contain only
   * letters, numbers, and underscore, and start with a letter. That is, they
   * should follow the same rules as PHP identifiers in general.
   *
   * The call will be ignored if the tag is already set on this query.
   *
   * @param string $tag
   *   The tag to set.
   *
   * @return $this
   *
   * @see hook_search_api_query_TAG_alter()
   */
  public function addTag($tag);

  /**
   * Checks whether a certain tag was set on this search query.
   *
   * @param string $tag
   *   The tag to check for.
   *
   * @return bool
   *   TRUE if the tag was set for this search query, FALSE otherwise.
   */
  public function hasTag($tag);

  /**
   * Determines whether this query has all the given tags set on it.
   *
   * @param string ...
   *   The tags to check for.
   *
   * @return bool
   *   TRUE if all the method parameters were set as tags on this query; FALSE
   *   otherwise.
   */
  public function hasAllTags();

  /**
   * Determines whether this query has any of the given tags set on it.
   *
   * @param string ...
   *   The tags to check for.
   *
   * @return bool
   *   TRUE if any of the method parameters was set as a tag on this query;
   *   FALSE otherwise.
   */
  public function hasAnyTag();

  /**
   * Retrieves the tags set on this query.
   *
   * @return string[]
   *   The tags associated with this search query, as both the array keys and
   *   values. Returned by reference so it's possible, for example, to remove
   *   existing tags.
   */
  public function &getTags();

  /**
   * Retrieves the original version of the query, before preprocessing occurred.
   *
   * Will be a clone of this query if preprocessing has not already run.
   *
   * @return \Drupal\search_api\Query\Query
   *   The original, unpreprocessed version of this query.
   */
  public function getOriginalQuery();

}

Members

Namesort descending Modifiers Type Description Overrides
ConditionSetInterface::addCondition public function Adds a new ($field $operator $value) condition. 2
ConditionSetInterface::addConditionGroup public function Adds a nested condition group. 2
QueryInterface::abort public function Aborts this query. 1
QueryInterface::addTag public function Sets the given tag on this query. 1
QueryInterface::create public static function Instantiates a new instance of this query class. 1
QueryInterface::createConditionGroup public function Creates a new condition group to use with this query object. 1
QueryInterface::execute public function Executes this search query. 1
QueryInterface::getAbortMessage public function Retrieves the error message explaining why this query was aborted, if any. 1
QueryInterface::getConditionGroup public function Retrieves the condition group object associated with this search query. 1
QueryInterface::getDisplayPlugin public function Retrieves the search display associated with this query (if any). 1
QueryInterface::getFulltextFields public function Retrieves the fulltext fields that will be searched for the search keys. 1
QueryInterface::getIndex public function Retrieves the index associated with this search. 1
QueryInterface::getKeys public function Retrieves the search keys for this query. 1
QueryInterface::getLanguages public function Retrieves the languages that will be searched by this query. 1
QueryInterface::getOption public function Retrieves an option set on this search query. 1
QueryInterface::getOptions public function Retrieves all options set for this search query. 1
QueryInterface::getOriginalKeys public function Retrieves the unparsed search keys for this query as originally entered. 1
QueryInterface::getOriginalQuery public function Retrieves the original version of the query, before preprocessing occurred. 1
QueryInterface::getParseMode public function Retrieves the parse mode. 1
QueryInterface::getProcessingLevel public function Retrieves the processing level for this query. 1
QueryInterface::getResults public function Retrieves this query's result set. 1
QueryInterface::getSearchId public function Retrieves the search ID. 1
QueryInterface::getSorts public function Retrieves the sorts set for this query. 1
QueryInterface::getTags public function Retrieves the tags set on this query. 1
QueryInterface::hasAllTags public function Determines whether this query has all the given tags set on it. 1
QueryInterface::hasAnyTag public function Determines whether this query has any of the given tags set on it. 1
QueryInterface::hasExecuted public function Determines whether this query has been executed already. 1
QueryInterface::hasTag public function Checks whether a certain tag was set on this search query. 1
QueryInterface::keys public function Sets the keys to search for. 1
QueryInterface::postExecute public function Postprocesses the search results before they are returned. 1
QueryInterface::preExecute public function Prepares the query object for the search. 1
QueryInterface::PROCESSING_BASIC constant Constant representing a search with only basic processing.
QueryInterface::PROCESSING_FULL constant Constant representing a search with normal/full processing.
QueryInterface::PROCESSING_NONE constant Constant representing a completely unprocessed search.
QueryInterface::range public function Adds a range of results to return. 1
QueryInterface::setFulltextFields public function Sets the fields that will be searched for the search keys. 1
QueryInterface::setLanguages public function Sets the languages that should be searched by this query. 1
QueryInterface::setOption public function Sets an option for this search query. 1
QueryInterface::setParseMode public function Sets the parse mode. 1
QueryInterface::setProcessingLevel public function Sets the processing level for this query. 1
QueryInterface::setSearchId public function Sets the search ID. 1
QueryInterface::sort public function Adds a sort directive to this search query. 1
QueryInterface::SORT_ASC constant Constant representing ascending sorting.
QueryInterface::SORT_DESC constant Constant representing descending sorting.
QueryInterface::wasAborted public function Determines whether this query was aborted. 1