StructuredQuery

Firestore 쿼리

쿼리 단계는 다음 순서로 실행됩니다. 1. 2에서 3. 3. 4. orderBy + startAt + endAt 5. offset 6. limit

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__의 주문을 지정하지 않으면 기본적으로 추가됩니다.

필드는 마지막에 지정된 순서와 같은 정렬 방향으로 추가되거나 순서가 지정되지 않은 경우 'ASCENDING'입니다. 예를 들면 다음과 같습니다.

  • 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 바로 뒤에 쿼리를 시작합니다.

건너뛰려면 처음 N개의 결과를 스캔해야 하는 OFFSET와 달리, 시작 커서를 사용하면 쿼리를 논리적 위치에서 시작할 수 있습니다. 이 위치는 실제 결과와 일치하지 않아도 되며 이 위치부터 앞으로 스캔하여 다음 문서를 찾습니다.

요구사항:

  • 값의 수는 ORDER BY 절에 지정된 필드의 수보다 클 수 없습니다.
endAt

object (Cursor)

결과 집합에서 쿼리를 종료할 위치의 잠재적 접두사입니다.

START_AT와 유사하지만 시작 위치가 아닌 종료 위치를 제어한다는 점이 다릅니다.

요구사항:

  • 값의 수는 ORDER BY 절에 지정된 필드의 수보다 클 수 없습니다.
offset

integer

첫 번째 결과를 반환하기 전에 건너뛸 문서 수입니다.

이는 WHERE, START AT, END AT로 지정된 제약 조건 이후, LIMIT 절 앞에 적용됩니다.

요구사항:

  • 지정된 경우 이 값은 0 이상이어야 합니다.
limit

integer

반환할 최대 결과 수입니다.

다른 모든 제약조건 후에 적용됩니다.

요구사항:

  • 지정된 경우 이 값은 0 이상이어야 합니다.
findNearest

object (FindNearest)

선택사항입니다. 잠재적 가장 가까운 이웃 검색입니다.

다른 모든 필터 및 정렬 후에 적용됩니다.

지정된 쿼리 벡터에 가장 가까운 벡터 임베딩을 찾습니다.

투영

반환할 문서 필드의 프로젝션입니다.

JSON 표현 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
입력란
fields[]

object (FieldReference)

반환할 필드입니다.

비어 있으면 모든 필드가 반환됩니다. 문서 이름만 반환하려면 ['__name__']를 사용하세요.

CollectionSelector

컬렉션의 선택입니다(예: messages as m1).

JSON 표현 
{
  "collectionId": string,
  "allDescendants": boolean
}
입력란
collectionId

string

컬렉션 ID입니다. 설정하면 이 ID가 있는 컬렉션만 선택합니다.
allDescendants

boolean

false인 경우 포함된 RunQueryRequest에 지정된 parent의 직계 하위 컬렉션만 선택합니다. 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)

정확히 하나의 인수를 사용하는 필터.

CompositeFilter

지정된 연산자를 사용하여 여러 다른 필터를 병합하는 필터입니다.

JSON 표현 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
입력란
op

enum (Operator)

여러 필터를 결합하는 연산자입니다.
filters[]

object (Filter)

결합할 필터의 목록입니다.

요구사항:

  • 필터가 하나 이상 존재합니다.

운영자

복합 필터 연산자

열거형
OPERATOR_UNSPECIFIED 지정되지 않았습니다. 이 값은 사용할 수 없습니다.
AND 문서는 결합된 모든 필터를 충족해야 합니다.
OR 문서가 결합된 필터 중 하나 이상을 충족해야 합니다.

FieldFilter

특정 필드의 필터입니다.

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는 값이 최대 10개인 비어 있지 않은 ArrayValue입니다.
  • 다른 OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL 또는 IS_NOT_NAN가 없습니다.
  • 해당 field가 orderBy에서 가장 먼저 나옵니다.

UnaryFilter

피연산자가 1개인 필터

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 내림차순입니다.

FindNearest

가장 가까운 이웃 검색 구성입니다.

JSON 표현 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
입력란
vectorField

object (FieldReference)

필수 항목입니다. 검색할 색인이 생성된 벡터 필드입니다. 차원이 queryVector와 일치하는 벡터가 포함된 문서만 반환할 수 있습니다.
queryVector

object (Value)

필수 항목입니다. 검색 중인 쿼리 벡터입니다. 2,048차원 이하의 벡터여야 합니다.
distanceMeasure

enum (DistanceMeasure)

필수 항목입니다. 사용할 거리 측정입니다(필수).
limit

integer

필수 항목입니다. 반환할 최근접 이웃 수입니다. 1,000 이하의 양의 정수여야 합니다.

DistanceMeasure

벡터를 비교할 때 사용할 거리 측정값입니다.

열거형
DISTANCE_MEASURE_UNSPECIFIED 설정하면 안 됩니다.
EUCLIDEAN 벡터 간의 EUCLIDEAN 거리를 측정합니다. 자세한 내용은 유클리드를 참고하세요.
COSINE 벡터 사이의 각도를 기준으로 벡터를 비교하므로 벡터 크기를 기반으로 하지 않는 유사성을 측정할 수 있습니다. COSINE 거리 대신 단위 정규화된 벡터와 함께 DOT_PRODUCT를 사용하는 것이 좋습니다. 이는 수학적으로 동일하며 성능이 더 뛰어납니다. 자세한 내용은 코사인 유사성을 참조하세요.
DOT_PRODUCT 코사인과 비슷하지만 벡터 크기의 영향을 받습니다. 자세한 내용은 Dot Product를 참고하세요.