StructuredQuery

Firestore 쿼리

쿼리 단계는 1. from 2. 여기서 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)

정확히 1개의 인수를 사용하는 필터입니다.

CompositeFilter

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

JSON 표현 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
필드
op

enum (Operator)

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

object (Filter)

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

요구사항:

  • 필터가 1개 이상 있습니다.

연산자

복합 필터 연산자.

열거형
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는 값이 10개 이하인 비어 있지 않은 ArrayValue입니다.
  • 다른 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)

필수 항목입니다. 검색 중인 쿼리 벡터입니다. 차원이 2,048개를 넘지 않는 벡터여야 합니다.
distanceMeasure

enum (DistanceMeasure)

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

integer

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

거리 측정

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

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