StructuredQuery

Запрос Firestore.

Этапы запроса выполняются в следующем порядке: 1. из 2. где 3. выбрать 4. orderBy + startAt + endAt 5. смещение 6. предел

JSON-представление 
{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}
Поля
select

object ( Projection )

Необязательный подмножество возвращаемых полей.

Это действует как DocumentMask для документов, возвращаемых по запросу. Если не установлено, предполагается, что вызывающая сторона хочет вернуть все поля.

from[]

object ( CollectionSelector )

Коллекции для запроса.

where

object ( Filter )

Фильтр, который нужно применить.

orderBy[]

object ( Order )

Порядок применения к результатам запроса.

Firestore позволяет вызывающим абонентам обеспечить полный заказ, частичный заказ или отсутствие заказа вообще. Во всех случаях Firestore гарантирует стабильный заказ, соблюдая следующие правила:

  • orderBy необходим для ссылки на все поля, используемые с фильтром неравенства.
  • Все поля, которые должны присутствовать в orderBy , но еще не присутствуют, добавляются в лексикографическом порядке имени поля.
  • Если заказ на __name__ не указан, он добавляется по умолчанию.

Поля добавляются в том же направлении сортировки, что и последний указанный порядок, или «ПО ВОСХОЖДЕНИЮ», если порядок не был указан. Например:

  • ORDER BY a становится ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC становится ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 становится WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 становится WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object ( Cursor )

Потенциальный префикс позиции в наборе результатов, с которой начинается запрос.

Порядок набора результатов основан на предложении ORDER BY исходного запроса.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

Результаты этого запроса упорядочены по (b ASC, __name__ ASC) .

Курсоры могут ссылаться либо на полный порядок, либо на префикс местоположения, однако они не могут ссылаться на большее количество полей, чем указано в предоставленном ORDER BY .

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

  • START BEFORE (2, /k/123) : начать запрос непосредственно перед a = 1 AND b > 2 AND __name__ > /k/123 .
  • START AFTER (10) : начать запрос сразу после a = 1 AND b > 10 .

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

Требует:

  • Количество значений не может превышать количество полей, указанных в предложении ORDER BY .
endAt

object ( Cursor )

Потенциальный префикс позиции в наборе результатов, на которой завершается запрос.

Это похоже на START_AT , но контролирует конечную позицию, а не начальную.

Требует:

  • Количество значений не может превышать количество полей, указанных в предложении ORDER BY .
offset

integer

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

Это применяется после ограничений, указанных в WHERE , START AT и END AT , но до предложения LIMIT .

Требует:

  • Значение должно быть больше или равно нулю, если оно указано.
limit

integer

Максимальное количество возвращаемых результатов.

Применяется после всех остальных ограничений.

Требует:

  • Значение должно быть больше или равно нулю, если оно указано.
findNearest

object ( FindNearest )

Необязательный. Поиск потенциальных ближайших соседей.

Применяется после всех остальных фильтров и упорядочения.

Находит ближайшие векторные внедрения к заданному вектору запроса.

Проекция

Проекция возвращаемых полей документа.

JSON-представление 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
Поля
fields[]

object ( FieldReference )

Поля для возврата.

Если пусто, возвращаются все поля. Чтобы вернуть только имя документа, используйте ['__name__'] .

Селектор коллекций

Выбор коллекции, например messages as m1 .

JSON-представление 
{
  "collectionId": string,
  "allDescendants": boolean
}
Поля
collectionId

string

Идентификатор коллекции. Если установлено, выбираются только коллекции с этим идентификатором.

allDescendants

boolean

Если установлено значение false, выбираются только коллекции, которые являются непосредственными дочерними элементами parent , указанного в содержащем RunQueryRequest . Если установлено значение true, выбираются все коллекции-потомки.

Фильтр

Фильтр.

JSON-представление 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
Поля
Поле объединения filter_type . Тип фильтра. filter_type может быть только одним из следующих:
compositeFilter

object ( CompositeFilter )

Составной фильтр.

fieldFilter

object ( FieldFilter )

Фильтр по полю документа.

unaryFilter

object ( UnaryFilter )

Фильтр, который принимает ровно один аргумент.

КомпозитныйФильтр

Фильтр, который объединяет несколько других фильтров с помощью данного оператора.

JSON-представление 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
Поля
op

enum ( Operator )

Оператор объединения нескольких фильтров.

filters[]

object ( Filter )

Список фильтров для объединения.

Требует:

  • Имеется хотя бы один фильтр.

Оператор

Оператор составного фильтра.

Перечисления
OPERATOR_UNSPECIFIED Не указано. Это значение нельзя использовать.
AND Документы должны соответствовать всем комбинированным фильтрам.
OR Документы должны соответствовать хотя бы одному из комбинированных фильтров.

ФилдФильтр

Фильтр по определенному полю.

JSON-представление 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
Поля
field

object ( FieldReference )

Поле для фильтрации.

op

enum ( Operator )

Оператор для фильтрации.

value

object ( Value )

Значение для сравнения.

Оператор

Оператор фильтра поля.

Перечисления
OPERATOR_UNSPECIFIED Не указано. Это значение нельзя использовать.
LESS_THAN

Данное field меньше заданного value .

Требует:

  • Это field стоит первым в orderBy .
LESS_THAN_OR_EQUAL

Данное field меньше или равно заданному value .

Требует:

  • Это field стоит первым в orderBy .
GREATER_THAN

Данное field больше заданного value .

Требует:

  • Это field стоит первым в orderBy .
GREATER_THAN_OR_EQUAL

Данное field больше или равно заданному value .

Требует:

  • Это field стоит первым в orderBy .
EQUAL Данное field равно данному value .
NOT_EQUAL

Данное field не равно данному value .

Требует:

  • Никаких других NOT_EQUAL , NOT_IN , IS_NOT_NULL или IS_NOT_NAN .
  • Это field идет первым в orderBy .
ARRAY_CONTAINS Данное field представляет собой массив, содержащий заданное value .
IN

Данное field равно хотя бы одному значению в данном массиве.

Требует:

  • Это value является непустым ArrayValue с учетом ограничений дизъюнкции.
  • В одном запросе нет фильтров NOT_IN .
ARRAY_CONTAINS_ANY

Данное field представляет собой массив, содержащий любые значения данного массива.

Требует:

  • Это value является непустым ArrayValue с учетом ограничений дизъюнкции.
  • Никаких других фильтров ARRAY_CONTAINS_ANY в пределах того же дизъюнкция.
  • В одном запросе нет фильтров NOT_IN .
NOT_IN

Значение field отсутствует в данном массиве.

Требует:

  • Это value представляет собой непустое ArrayValue , содержащее не более 10 значений.
  • Никаких других OR , IN , ARRAY_CONTAINS_ANY , NOT_IN , NOT_EQUAL , IS_NOT_NULL или IS_NOT_NAN .
  • Это field идет первым в orderBy .

УнарныйФильтр

Фильтр с одним операндом.

JSON-представление 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
Поля
op

enum ( Operator )

Унарный оператор, который нужно применить.

Поле operand_type . Аргумент фильтра. operand_type может быть только одним из следующих:
field

object ( FieldReference )

Поле, к которому применяется оператор.

Оператор

Унарный оператор.

Перечисления
OPERATOR_UNSPECIFIED Не указано. Это значение нельзя использовать.
IS_NAN Данное field равно NaN .
IS_NULL Данное field равно NULL .
IS_NOT_NAN

Данное field не равно NaN .

Требует:

  • Никаких других NOT_EQUAL , NOT_IN , IS_NOT_NULL или IS_NOT_NAN .
  • Это field стоит первым в orderBy .
IS_NOT_NULL

Данное field не равно NULL .

Требует:

  • Одиночный NOT_EQUAL , NOT_IN , IS_NOT_NULL или IS_NOT_NAN .
  • Это field стоит первым в orderBy .

Заказ

Порядок на поле.

JSON-представление 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
Поля
field

object ( FieldReference )

Поле для заказа.

direction

enum ( Direction )

Направление заказа. По умолчанию — ПО ASCENDING .

Направление

Направление сортировки.

Перечисления
DIRECTION_UNSPECIFIED Не указано.
ASCENDING По возрастанию.
DESCENDING По убыванию.

Найти ближайший

Конфигурация поиска ближайших соседей.

JSON-представление 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
Поля
vectorField

object ( FieldReference )

Необходимый. Индексированное векторное поле для поиска. Могут быть возвращены только документы, содержащие векторы, размерность которых соответствует queryVector.

queryVector

object ( Value )

Необходимый. Вектор запроса, по которому мы ищем. Должен быть вектором не более 2048 измерений.

distanceMeasure

enum ( DistanceMeasure )

Необходимый. Требуемая мера расстояния.

limit

integer

Необходимый. Число ближайших соседей для возврата. Должно быть целым положительным числом не более 1000.

РасстояниеМера

Мера расстояния, используемая при сравнении векторов.

Перечисления
DISTANCE_MEASURE_UNSPECIFIED Не следует устанавливать.
EUCLIDEAN Измеряет ЕВКЛИДОВОЕ расстояние между векторами. См. Евклид, чтобы узнать больше.
COSINE Сравнивает векторы на основе угла между ними, что позволяет измерить сходство, не основанное на величине векторов. Мы рекомендуем использовать DOT_PRODUCT с единичными нормализованными векторами вместо расстояния COSINE, что математически эквивалентно и обеспечивает лучшую производительность. См. раздел «Косинусное сходство» , чтобы узнать больше.
DOT_PRODUCT Аналогично косинусу, но на него влияет величина векторов. См. «Скалярное произведение» , чтобы узнать больше.