Синтаксис AQL¶

Типы запросов¶

Запрос AQL должен либо возвращать результат (на что указывает использование ключевого слова RETURN), либо выполнять операцию модификации данных (на что указывает использование одного из ключевых слов INSERT, UPDATE, REPLACE, REMOVE или UPSERT). Синтаксический анализатор AQL вернет ошибку, если обнаружит более одной операции модификации данных в одном запросе или не сможет определить, предназначен ли запрос для извлечения данных или для операции модификации.

AQL допускает только один запрос в одной строке запроса; таким образом, точки с запятой для обозначения конца одного запроса и разделения нескольких запросов (как это видно в SQL) не допускаются.

Пробелы¶

Пробелы (пробелы, возврат каретки, перевод строки и табуляция) могут использоваться в тексте запроса для повышения его удобочитаемости. Токены должны быть разделены любым количеством пробелов. Пробелы в строках или именах должны быть заключены в кавычки.

Комментарии¶

Комментарии могут быть внедрены в любом месте запроса. Текст, содержащийся в комментарии, игнорируется синтаксическим анализатором AQL.

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

AQL поддерживает два типа комментариев:

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

/* this is a comment */ RETURN 1
/* these */ RETURN /* are */ 1 /* multiple */ + /* comments */ 1
/* this is
   a multi line
   comment */
// a single line comment

Ключевые слова¶

На верхнем уровне AQL предлагает следующие высокоуровневые операции:

Операция	Описание
`FOR`	Итерация массива
`RETURN`	Возращаемый результат
`FILTER`	Фильтрация результатов без просмотра
`SEARCH`	Просмотр результатов фильтрации
`SORT`	Сортировка результатов
`LIMIT`	Ограничение результатов
`LET`	Назначение переменной
`COLLECT`	Группировка результатов
`WINDOW`	Агрегации по связанным строкам
`INSERT`	Вставка новых документов
`UPDATE`	(Частичное) обновление существующих документов
`REPLACE`	Замена существующих документов
`REMOVE`	Удаление существующих документов
`UPSERT`	Вставка новых или обновление существующих документов
`WITH`	Декларация о коллекции

Каждая из вышеперечисленных операций может быть инициирована в запросе с помощью ключевого слова с тем же именем. Запрос AQL может (и обычно состоит) состоять из нескольких вышеперечисленных операций.

Пример запроса AQL может выглядеть следующим образом:

FOR u IN users
  FILTER u.type == "newbie" && u.active == true
  RETURN u.name

В этом примере запроса термины FOR, FILTER и RETURN инициируют операцию более высокого уровня в соответствии с их именем. Эти термины также являются ключевыми словами, что означает, что они имеют особое значение в языке.

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

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

Ключевые слова нечувствительны к регистру, то есть в запросах их можно указывать в нижнем, верхнем или смешанном регистре. В этой документации все ключевые слова написаны в верхнем регистре, чтобы их можно было отличить от других частей запроса.

Есть еще несколько ключевых слов в дополнение к ключевым словам операций более высокого уровня. Дополнительные ключевые слова могут быть добавлены в будущих версиях ArangoDB. Полный список ключевых слов на данный момент:

AGGREGATE
ALL
AND
ANY
ASC
COLLECT
DESC
DISTINCT
FALSE
FILTER
FOR
GRAPH
IN
INBOUND
INSERT
INTO
K_PATHS
K_SHORTEST_PATHS
LET
LIKE
LIMIT
NONE
NOT
NULL
OR
OUTBOUND
REMOVE
REPLACE
RETURN
SHORTEST_PATH
SORT
TRUE
UPDATE
UPSERT
WITH
WINDOW

Кроме того, в языковых конструкциях используется несколько слов, которые не являются зарезервированными ключевыми словами. Таким образом, их можно использовать в качестве имен коллекций или атрибутов без кавычек или экранирования. Анализатор запросов может идентифицировать их как ключевые слова в зависимости от контекста:

KEEP – COLLECT операция
COUNT (WITH COUNT INTO) – COLLECT вариант операции
OPTIONS – FOR / Обход графа / SEARCH / COLLECT / INSERT / UPDATE / REPLACE / UPSERT / REMOVE операция
PRUNE – Обход графа, FOR операция
SEARCH – SEARCH операция
TO – Кратчайший путь / Все кратчайшие пути / k кратчайших путей / k путей обход графа

И последнее, но не менее важное: существуют специальные переменные, которые доступны в определенных контекстах. В отличие от ключевых слов, они чувствительны к регистру:

CURRENT – доступно в инлайновых выражениях с массивом
NEW – доступно после INSERT / UPDATE / REPLACE / UPSERT операций
OLD – доступно после UPDATE / REPLACE / UPSERT / REMOVE операций

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

Имена¶

Как правило, имена используются для идентификации следующих вещей в запросах AQL:

коллекции
атрибуты
переменные
функции

Имена в AQL всегда чувствительны к регистру. Максимальная поддерживаемая длина имен коллекций/представлений составляет 256 байт. Имена переменных могут быть длиннее, но это не рекомендуется.

Ключевые слова не должны использоваться в качестве имен. Если зарезервированное ключевое слово должно использоваться в качестве имени, имя должно быть заключено в обратные или прямые кавычки.

FOR doc IN `filter`
  RETURN doc.`sort`

Из-за обратных кавычек filter и sort здесь интерпретируются как имена, а не как ключевые слова.

В качестве альтернативы пример можно записать так:

FOR f IN ´filter´
  RETURN f.´sort´

Вместо галочек вы можете использовать скобки для доступа к атрибуту:

FOR f IN `filter`
  RETURN f["sort"]

sort является строковым литералом в кавычках в этой альтернативе и, таким образом, не конфликтует с зарезервированным словом.

Экранирование также требуется, если в имени содержатся специальные символы, такие как дефис минус (-):

FOR doc IN `my-coll`
  RETURN doc

Коллекция my-coll имеет тире в названии, но - это арифметический оператор вычитания в AQL. Обратные кавычки экранируют имя коллекции, чтобы правильно ссылаться на коллекцию. Обратите внимание, что заключение имени в кавычки с помощью " или ' невозможно для коллекций.

Названия коллекций¶

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

Пожалуйста, обратитесь к соглашениям об именах в ArangoDB о соглашениях об именах коллекций.

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

Имена атрибутов¶

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

Пожалуйста, обратитесь к соглашениям об именах в ArangoDB для получения дополнительной информации о соглашениях об именах атрибутов.

FOR u IN users
  FOR f IN friends
    FILTER u.active == true && f.active == true && u.id == f.userId
    RETURN u.name

В приведенном выше примере имена атрибутов active, name, id и userId уточняются с использованием имен коллекций, к которым они принадлежат (u и f соответственно).

Имена переменных¶

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

FOR u IN users
  LET friends = u.friends
  RETURN { "name" : u.name, "friends" : friends }

В приведенном выше запросе users — это имя коллекции, а u и friends — имена переменных. Это связано с тем, что операциям FOR и LET нужны целевые переменные для хранения промежуточных результатов.

Допустимыми символами в именах переменных являются буквы от a до z (как в нижнем, так и в верхнем регистре), цифры от 0 до 9, символ подчеркивания (_) и знак доллара ($). Имя переменной не должно начинаться с цифры. Если имя переменной начинается с одного или нескольких символов подчеркивания, за символами подчеркивания должна следовать хотя бы одна буква (a-z или A-Z). Знак доллара можно использовать только в качестве самого первого символа в имени переменной, за ним должна следовать буква.