Метод GetRows запрашивает количество строк (записей) в заданной таблице данных в соответствии с заданными критериями. Этот метод эквивалентен запросу SQL SELECT.

Различные параметры позволяют задавать определенную таблицу, количество возвращенных записей, каким критериям они должны соответствовать, по каким критериям фильтроваться.

Этот метод полезен для отображения выбранных данных в сообщениях или для условного форматирования зависящих данных.

1. Cигнатура метода

rows = GetRows(table, top, columns, filters, order)

Параметры метода

Параметр Тип Описание
table string Обязательное. Название таблицы.
top
int
Необязательное. Максимальное количество запрашиваемых записей. По умолчанию равно 500. Если задано более 500, то будет проигнорировано.
columns
array of string Необязательное. Массив столбцов, которые будут выбраны. По умолчанию все столбцы.
filters array of Filter objects Необязательное. Массив объектов задающих параметры раздела WHERE запроса SELECT. Используйте этот параметр, чтобы ограничить выбранные записи теми, что подходят вашим критериям. Если не задано, критерии не будут применены. Если задано несколько фильтров, возвращенные записи будут соответствовать всем критериям (как при применении логического AND).
order array of Order objects Необязательное. Массив объектов, описывающий сортировку возвращаемых записей (эквивалентен ORDER BY). Если не задан, то сортировки не будет (записи будут возвращены в определенном базой данных порядке). Если заданы несколько объектов сортировки, то таблица будет отсортирована многократно.
filterOperator enumeration Необязательное. Логические операторы, применяемые к фильтрам. Могут быть следующими:
  • AND (filter1 AND filter2 AND filter3...) - "И" значение по умолчанию
  • OR (filter1 OR filter2 OR filter3...) - "ИЛИ"
  • ANDNOT (NOT filter1 AND NOT filter2 AND NOT filter3...) "И НЕ"
rows array of rows Возвращает значение. Массив записей. Каждая запись - это массив пар "ключ => значение" ("имя столбца => значение стобца"). Имя столбца - строка (string). Тип значения столбца зависит от типа базы данных. Массив будет пустым, если в таблице нет данных.
Строки могут быть перечислены через проход массива, например, выведены в виде HTML. Смотрите примеры для дополнительной информации.

Параметры объекта Filter

Параметр Тип Описание
Name string Column name
Modifier enumeration Модификатор операции. Может быть следующим:
  • EQ (равно, "=")
  • GT (больше чем, ">")
  • GE (больше или равно, ">=")
  • LT (меньше чем, "<")
  • LE (меньше или равно, "<=")
  • LIKE (SQL LIKE оператор)
  • NE (не равно, "<>")
Value object Значение столбца. Тип значения зависит от типа столбца, например, когда происходит фильтрация по номеру столбца, должен использоваться тип integer, для текстовых столбцов - string и т.д. Также возможны простые преобразования типов, например, string "123" отображает правильное целое integer значение 123. Это работает для дат, чисел с плавающей запятой и т.д..

Параметры объекта Order:

Параметр Тип Описание
Name
string
Название столбца
Desc
enumeration
Направление сортировки:
  • ASC - по возрастанию, ( например, старейшая первая - для дат, алфавитная сортировка - для текста, наименьшее первое - для чисел и т.д.)
  • DESC - по убыванию (например, новейшая первая - для дат, обратная алфавитная сортировка - для текста, наибольшее первое - для чисел и т.д.)

Важно: Обычно объекты Filter и Order создаются с помощью наиболее подходящих конструкторов. Для дополнительных сведений смотрите примеры.

2. Использование значений, возвращаемых методом GetRows

Значения, возвращаемые методом GetRows, являются массивами (перечисления). То есть это не просто данные, которые можно отобразить (например, как ${SubscriberEmail}), но совокупность данных, которую надо обработать, чтобы получить конкретные значения полей. Есть несколько путей получить значения, обычно это перебор (обход) и прямой доступ по индексу.

2.1. Обход строк и столбцов

Обход осуществляется по всем значениям массива без необходимости знать, как много значений в нем содержится. Это полезно, если, например, мы не знаем, как много записей будет возвращено или как много столбцов в одной записи.

Самый легкий способ обхода массива - это использование атрибута "each". Этот атрибут может быть применен к каждому элементу и будет дублировать его столько раз, сколько элементов содержится в массиве. В случае с GetRows - это количество строк или столбцов в строке.

Пример - простая таблица, которая содержит запись из базы данных. <tr> элементы создаются из перечисления строк, <td> - из перечисления столбцов каждой строки.

<table>
  <tr each="var row in GetRows('MyTable')">
    <td each="var column in row">
      ${column.Value}
    </td>
  </tr>
</table>

2.2 Прямой доступ к столбцам и строкам

Доступ к столбцам и строкам можно осуществлять напрямую через индексы массива. Строки проиндексированы числами (начиная с 0), а столбцы проиндексированы по их названиям. Метод подразумевает, что вы знаете содержание возвращаемого массива. Если используется неверный индекс (например, название столбца с опечаткой, или номер строки вне пределов), то в результате получим ошибку.

Пример - вывод содержимого трёх строк из базы данных. Возвращаемое GetRows значение хранится в переменной, а доступ к каждой строке осуществляется по индексу.

<var rows="GetRows('MyTable', 3)"/>

<div>Row no 1: ${rows[0]['MyColumn']}</div>
<div>Row no 2: ${rows[1]['MyColumn']}</div>
<div>Row no 3: ${rows[2]['MyColumn']}</div>

2.3. Метод смешанного доступа.

Оба вышеперечисленных метода могут быть использованы вместе при необходимости.

Пример - списки с содержимым из базы данных. <li> элементы создаются обходом строк, каждая строка создается доступом к столбцу по его названию.

<ul>
  <li each="var row in GetRows('MyTable')">
    <a href="mailto: ${row['Email']}">${row['Firstname']} ${row['Lastname']}</a>
  </li>
</ul>

3. Использование параметров GetRows для более сложных запросов

Ниже есть несколько примеров использования метода GetRows c дополнительными параметрами. Эти вызовы могут быть подставлены в вышестоящие примеры, чтобы получить законченные шаблоны сообщений.

Пример 1 - самый простой вызов:

GetRows('MyTable')

Это эквивалентно SQL-запросу:

SELECT * FROM MyTable

Пример 2 - выбор не более пяти записей из определенных столбцов:

GetRows('MyTable', 5, new [] {'Firstname', 'Lastname', 'Email'})

Это эквивалентно SQL-запросу:

SELECT TOP 5 Firstname, Lastname, Email FROM MyTable

Пример 3 - выбор всех строк, соответствующих определенному критерию. Например, все записи, связанные с покупателем с заданным ID:

GetRows('MyTable', null, null, new [] {new Filter('CustomerId', EQ, 1234)})

SELECT * FROM MyTable WHERE CustomerId = 1234

Пример 4 - использование двух дополнительных фильтров:

GetRows('MyTable', null, null, new [] {new Filter('CustomerId', EQ, 1234), new Filter('Price', GT, 24.99)})

Это эквивалентно SQL-запросу:

SELECT * FROM MyTable WHERE CustomerId = 1234 AND Price > 24.99

Пример 5 - использование полей подписчика в качестве фильтра:

GetRows('MyTable', null, null, new [] {new Filter('CustomerId', EQ, SubscriberProperty('customer_id'))})

Это эквивалентно SQL-запросу:

SELECT * FROM MyTable WHERE CustomerId = @customer_id

Важно: @customer_id - это параметр, который будет заменен актуальным значением поля подписчика (плейсхолдер).

Пример 6 - используя filterOperator:

GetRows('MyTable', null, null, new [] {new Filter('Color', EQ, 'red'), new Filter('Color', EQ, 'blue')}, null, OR)

Это эквивалентно SQL-запросу:

SELECT * FROM MyTable WHERE Color = 'red' OR Color = 'blue'

Пример 7 - выборка последних 10 записей (сортируются по дате):

GetRows('MyTable', 10, null, null, new [] {new Order('CreationDate', DESC)})

Это эквивалентно SQL-запросу:

SELECT TOP 10 * FROM MyTable ORDER BY CreationDate DESC

Пример 8 - мультисортировка:

GetRows('MyTable', null, null, null, new [] {new Order('CreationDate', DESC), new Order('ProductName', ASC)})

Это эквивалентно SQL-запросу:

SELECT * FROM MyTable ORDER BY CreationDate DESC, ProductName ASC