Выполнить SQL-запрос Connection::query

Модуль: main — подключать отдельно не нужно

Доступно с версии: 14.0.0

Метод Connection::query выполняет SQL-запрос и возвращает объект результата. Аналог в классическом API — CDatabase::Query.

Метод не экранирует значения в тексте запроса. Значения, которые приходят извне, экранируйте через getSqlHelper или подставляйте через объект SqlExpression.

Сигнатура метода в классе Bitrix\Main\DB\Connection:

public function query($sql)

Метод читает аргументы через func_get_args() и принимает их в одном из вариантов.

  • query($sql)
  • query($sql, $limit)
  • query($sql, $offset, $limit)
  • query($sql, $binds)
  • query($sql, $binds, $limit)
  • query($sql, $binds, $offset, $limit)

Если второй аргумент — массив, метод считает его параметром binds.

Параметры

Обязательные параметры обозначены *

Параметр Тип Описание
sql* string Задает текст SQL-запроса
binds array Передает массив значений в сведения о запросе для startTracker. Реализации MySQL и PostgreSQL не подставляют эти значения в текст запроса
offset int Задает число строк, которые нужно пропустить. По умолчанию — 0. Без limit метод не учитывает offset
limit int Задает наибольшее число строк результата. По умолчанию — 0, без ограничения. Метод сам добавляет в запрос ограничение по правилам базы данных

Типы в таблице описывают назначение аргументов. Сигнатура PHP не объявляет их.

Возвращаемое значение

Метод возвращает объект наследника Result, например MysqliResult или PgsqlResult. Строки читают методами fetch и fetchAll. Колонки типа даты и времени результат возвращает объектами Bitrix\Main\Type\Date и Bitrix\Main\Type\DateTime.

Реализация для PostgreSQL приводит ключи строки результата к верхнему регистру.

Метод подключается к базе данных, если подключения еще нет. Если установлен модуль кластера cluster, пул соединений может отправить запрос SELECT или SHOW на реплику. Тогда запрос выполняет и подключается соединение с репликой.

Если выполнение запросов отключено через disableQueryExecuting, метод не обращается к базе данных и сохраняет текст запроса в список getDisabledQueryExecutingDump.

Исключения

Исключение Когда возникает
Bitrix\Main\DB\SqlQueryException База данных вернула ошибку при выполнении запроса
Bitrix\Main\DB\DuplicateEntryException Запрос нарушил уникальность ключа. Класс наследует SqlQueryException
Bitrix\Main\DB\ConnectionException Подключиться к базе данных не удалось

Примеры

Пример. Код выбирает пять активных пользователей. Код экранирует значение Y через SqlHelper:

<?php
use Bitrix\Main\Application;
use Bitrix\Main\UserTable;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$connection = Application::getConnection();
$helper = $connection->getSqlHelper();

$sql = 'SELECT ID, LOGIN FROM ' . $helper->quote(UserTable::getTableName())
    . " WHERE ACTIVE = '" . $helper->forSql('Y') . "' ORDER BY ID";

$result = $connection->query($sql, 5);
while ($row = $result->fetch())
{
    echo $row['ID'] . ' ' . $row['LOGIN'] . PHP_EOL;
}

Пример. Код выполняет тот же запрос через CDatabase::Query. Код задает ограничение по числу строк в тексте запроса в синтаксисе MySQL:

<?php
use Bitrix\Main\UserTable;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

global $DB;

$result = $DB->Query(
    'SELECT ID, LOGIN FROM ' . UserTable::getTableName() . " WHERE ACTIVE = 'Y' ORDER BY ID LIMIT 5"
);
while ($row = $result->Fetch())
{
    echo $row['ID'] . ' ' . $row['LOGIN'] . PHP_EOL;
}

Смотрите также