Views: 306
Last Modified: 21.03.2022

All parameters for getList, getRow as well as others are passed jointly, executing the query and returning the result: all is done in a single call. However, there is an alternative method of query configuration and execution oversight: the object Entity\Query:

// gets data using getList
$result = BookTable::getList(array(
	'select' => array('ISBN', 'TITLE', 'PUBLISH_DATE')
	'filter' => array('=ID' => 1)

// similar method using Entity\Query
$q = new Entity\Query(BookTable::getEntity());
$q->setSelect(array('ISBN', 'TITLE', 'PUBLISH_DATE'));
$q->setFilter(array('=ID' => 1));
$result = $q->exec();

Such approach can be convenient, when you need flexibility in building a query. For example, when query parameters are not known beforehand and are software-generated, you can use a single Query object instead of several various arguments. This object accumulates query parameters:

$query = new Entity\Query(BookTable::getEntity());
$result = $query->exec();

function attachSelect(Entity\Query $query)
	if (...)

function attachOthers(Entity\Query $query)
	if (...)
	if (...)

Also the Entity\Query object allows to build a query without executing it. This can be useful for executing subqueries or simply for getting query text and subsequent use:

$q = new Entity\Query(BookTable::getEntity());
$q->setFilter(array('=PUBLISH_DATE' => new Type\Date('2014-12-13', 'Y-m-d')));
$sql = $q->getQuery();

file_put_contents('/tmp/today_books.sql', $sql);

// as a result, the query "SELECT ID FROM my_book WHERE PUBLISH_DATE='2014-12-31'" will be saved into file, but not executed.

Full list of Entity\Query methods for implementing options described above:

select, group:

  • setSelect, setGroup - sets array with field names
  • addSelect, addGroup - adds field name
  • getSelect, getGroup - returns array with field names


  • setFilter - sets a single- or multidimensional array with filter description
  • addFilter - adds a single filter parameter with a value
  • getFilter - returns current filter description


  • setOrder - sets array with field names and sort order
  • addOrder - adds a single field with sort order
  • getOrder - returns current sort description


  • setLimit, setOffset - sets value
  • getLimit, getOffset - returns current value

runtime fields:

  • registerRuntimeField - registers new temporary field for original entity

The Query Object is the key element in data retrieval; its also used inside the standard method getList. That's why re-defining getList methods is ineffective: calling a corresponding single method is OK, but with similar query directly via Query is not.

Courses developed by Bitrix24