StructuredQuery

Một truy vấn trên Firestore.

Các giai đoạn truy vấn được thực hiện theo thứ tự sau: 1. từ 2. trong đó 3. chọn 4. orderBy + startAt + endAt 5. trừ 6. giới hạn

Biểu diễn dưới dạng 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)
  }
}
Trường
select

object (Projection)

Tập hợp con không bắt buộc gồm các trường cần trả về.

Tham số này hoạt động như một DocumentMask trên các tài liệu được trả về từ truy vấn. Khi bạn không đặt chính sách này, hãy giả định rằng phương thức gọi muốn trả về tất cả các trường.
from[]

object (CollectionSelector)

Các tập hợp cần truy vấn.
where

object (Filter)

Bộ lọc để áp dụng.
orderBy[]

object (Order)

Thứ tự áp dụng cho các kết quả truy vấn.

Firestore cho phép người gọi đặt hàng đầy đủ, đặt hàng một phần hoặc không đặt hàng. Trong mọi trường hợp, Firestore đảm bảo thứ tự ổn định thông qua các quy tắc sau:

  • orderBy là bắt buộc để tham chiếu tất cả các trường được dùng với bộ lọc bất đẳng thức.
  • Tất cả các trường bắt buộc phải có trong orderBy nhưng chưa có thì sẽ được nối theo thứ tự từ điển của tên trường.
  • Nếu bạn không chỉ định đơn đặt hàng trên __name__, đơn đặt hàng sẽ được thêm vào theo mặc định.

Các trường được nối với cùng hướng sắp xếp như thứ tự gần đây nhất được chỉ định hoặc "DỰA VÀO" nếu không có đơn đặt hàng nào được chỉ định. Ví dụ:

  • ORDER BY a trở thành ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC trở thành ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 trở thành WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 trở thành WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object (Cursor)

Tiền tố tiềm năng của vị trí trong tập hợp kết quả để bắt đầu truy vấn.

Thứ tự của nhóm kết quả dựa trên mệnh đề ORDER BY của truy vấn ban đầu.

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

Kết quả của truy vấn này được sắp xếp theo (b ASC, __name__ ASC).

Con trỏ có thể tham chiếu thứ tự đầy đủ hoặc tiền tố của vị trí, mặc dù con trỏ không thể tham chiếu nhiều trường hơn những trường có trong ORDER BY được cung cấp.

Tiếp tục ví dụ trên, việc đính kèm các con trỏ bắt đầu sau đây sẽ có tác động khác nhau:

  • START BEFORE (2, /k/123): bắt đầu truy vấn ngay trước a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): bắt đầu truy vấn ngay sau a = 1 AND b > 10.

Không giống như OFFSET yêu cầu quét qua N kết quả đầu tiên để bỏ qua, con trỏ bắt đầu cho phép truy vấn bắt đầu tại vị trí logic. Vị trí này không bắt buộc phải khớp với kết quả thực tế, nó sẽ quét phía trước từ vị trí này để tìm tài liệu tiếp theo.

Yêu cầu:

  • Số lượng giá trị không được lớn hơn số lượng trường được chỉ định trong mệnh đề ORDER BY.
endAt

object (Cursor)

Tiền tố tiềm năng của vị trí trong kết quả được đặt để kết thúc truy vấn tại.

Hàm này tương tự như START_AT nhưng với việc kiểm soát vị trí kết thúc thay vì vị trí bắt đầu.

Yêu cầu:

  • Số lượng giá trị không được lớn hơn số lượng trường được chỉ định trong mệnh đề ORDER BY.
offset

integer

Số tài liệu cần bỏ qua trước khi trả về kết quả đầu tiên.

Điều này áp dụng sau các quy tắc ràng buộc do WHERE, START AT và END AT nhưng trước mệnh đề LIMIT.

Yêu cầu:

  • Giá trị phải lớn hơn hoặc bằng 0 nếu được chỉ định.
limit

integer

Số lượng kết quả tối đa cần trả về.

Áp dụng sau mọi quy tắc ràng buộc khác.

Yêu cầu:

  • Giá trị phải lớn hơn hoặc bằng 0 nếu được chỉ định.
findNearest

object (FindNearest)

Không bắt buộc. Một người hàng xóm gần nhất có thể đang tìm kiếm.

Áp dụng sau tất cả các bộ lọc và thứ tự khác.

Tìm các vectơ nhúng gần nhất với vectơ truy vấn đã cho.

Dự đoán

Phép chiếu các trường của tài liệu cần trả về.

Biểu diễn dưới dạng JSON 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
Trường
fields[]

object (FieldReference)

Các trường cần trả về.

Nếu trống, tất cả các trường sẽ được trả về. Để chỉ trả về tên của tài liệu, hãy sử dụng ['__name__'].

Bộ chọn bộ sưu tập

Một lựa chọn trong một tập hợp, chẳng hạn như messages as m1.

Biểu diễn dưới dạng JSON 
{
  "collectionId": string,
  "allDescendants": boolean
}
Trường
collectionId

string

Mã bộ sưu tập. Khi đặt giá trị này, chỉ chọn các bộ sưu tập có mã nhận dạng này.
allDescendants

boolean

Khi đặt là false, chỉ chọn các tập hợp là con trực tiếp của parent được chỉ định trong vùng chứa RunQueryRequest. Khi giá trị là true, sẽ chọn tất cả các tập hợp con.

Bộ lọc

Bộ lọc.

Biểu diễn dưới dạng 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.
}
Trường
Trường kết hợp filter_type. Loại bộ lọc. filter_type chỉ có thể là một trong những trạng thái sau đây:
compositeFilter

object (CompositeFilter)

Bộ lọc tổng hợp.
fieldFilter

object (FieldFilter)

Bộ lọc trên một trường tài liệu.
unaryFilter

object (UnaryFilter)

Bộ lọc nhận đúng một đối số.

Bộ lọc tổng hợp

Bộ lọc hợp nhất nhiều bộ lọc khác bằng toán tử cho trước.

Biểu diễn dưới dạng JSON 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
Trường
op

enum (Operator)

Toán tử để kết hợp nhiều bộ lọc.
filters[]

object (Filter)

Danh sách bộ lọc cần kết hợp.

Yêu cầu:

  • Có ít nhất một bộ lọc.

Toán tử

Toán tử bộ lọc tổng hợp.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
AND Giấy tờ phải đáp ứng tất cả các bộ lọc kết hợp.
OR Giấy tờ phải đáp ứng ít nhất một trong các bộ lọc kết hợp.

Bộ lọc trường

Bộ lọc trên một trường cụ thể.

Biểu diễn dưới dạng JSON 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
Trường
field

object (FieldReference)

Trường để lọc theo.
op

enum (Operator)

Toán tử bạn muốn lọc theo.
value

object (Value)

Giá trị cần so sánh.

Toán tử

Một toán tử lọc trường.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
LESS_THAN

field đã cho nhỏ hơn value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở orderBy.
LESS_THAN_OR_EQUAL

field đã cho nhỏ hơn hoặc bằng value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở orderBy.
GREATER_THAN

field đã cho lớn hơn value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở orderBy.
GREATER_THAN_OR_EQUAL

field đã cho lớn hơn hoặc bằng value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở orderBy.
EQUAL field đã cho bằng với value đã cho.
NOT_EQUAL

field đã cho không bằng value đã cho.

Yêu cầu:

  • Không có NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN nào khác.
  • field đó đứng đầu trong orderBy.
ARRAY_CONTAINS field đã cho là một mảng chứa value đã cho.
IN

field đã cho bằng ít nhất một giá trị trong mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống và phải tuân theo giới hạn phân tách.
  • Không có bộ lọc NOT_IN nào trong cùng một truy vấn.
ARRAY_CONTAINS_ANY

field đã cho là một mảng chứa bất kỳ giá trị nào trong các mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống và phải tuân theo giới hạn phân tách.
  • Không có bộ lọc ARRAY_CONTAINS_ANY nào khác trong cùng phân tách.
  • Không có bộ lọc NOT_IN nào trong cùng một truy vấn.
NOT_IN

Giá trị của field không nằm trong mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống có tối đa 10 giá trị.
  • Không có OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL hoặc IS_NOT_NAN khác.
  • field đó đứng đầu trong orderBy.

Bộ lọc đơn sắc

Một bộ lọc có một toán hạng duy nhất.

Biểu diễn dưới dạng 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.
}
Trường
op

enum (Operator)

Toán tử một ngôi để áp dụng.
Trường kết hợp operand_type. Đối số cho bộ lọc. operand_type chỉ có thể là một trong những trạng thái sau đây:
field

object (FieldReference)

Trường mà bạn muốn áp dụng toán tử.

Toán tử

Một toán tử đơn phân.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
IS_NAN field đã cho bằng NaN.
IS_NULL field đã cho bằng NULL.
IS_NOT_NAN

field đã cho không bằng NaN.

Yêu cầu:

  • Không có NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN nào khác.
  • field đó đứng đầu trong orderBy.
IS_NOT_NULL

field đã cho không bằng NULL.

Yêu cầu:

  • Một NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN.
  • field đó đứng đầu trong orderBy.

Gọi món

Thứ tự trên một trường.

Biểu diễn dưới dạng JSON 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
Trường
field

object (FieldReference)

Trường để sắp xếp thứ tự.
direction

enum (Direction)

Hướng dẫn sắp xếp thứ tự. Giá trị mặc định là ASCENDING.

Hướng

Hướng sắp xếp.

Enum
DIRECTION_UNSPECIFIED Không xác định.
ASCENDING Tăng dần.
DESCENDING Giảm dần.

Tìm gần nhất

Cấu hình tìm kiếm lân cận gần nhất.

Biểu diễn dưới dạng JSON 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
Trường
vectorField

object (FieldReference)

Bắt buộc. Trường vectơ được lập chỉ mục để tìm kiếm. Chỉ có thể trả về các tài liệu chứa vectơ có kích thước phù hợp với queryVector.
queryVector

object (Value)

Bắt buộc. Vectơ truy vấn mà chúng ta đang tìm kiếm. Phải là vectơ có không quá 2048 chiều.
distanceMeasure

enum (DistanceMeasure)

Bắt buộc. Số đo khoảng cách cần sử dụng, bắt buộc.
limit

integer

Bắt buộc. Số người lân cận gần nhất để trả về. Phải là một số nguyên dương không quá 1000.

Đo khoảng cách

Phép đo khoảng cách cần sử dụng khi so sánh các vectơ.

Enum
DISTANCE_MEASURE_UNSPECIFIED Không nên đặt.
EUCLIDEAN Đo khoảng cách EUCLIDEAN giữa các vectơ. Xem Euclide để tìm hiểu thêm
COSINE So sánh các vectơ dựa trên góc giữa chúng, cho phép bạn đo được sự tương đồng không dựa trên độ lớn của vectơ. Chúng tôi khuyên bạn nên sử dụng DOT_PRODUCT với vectơ chuẩn hoá đơn vị thay vì khoảng cách cosINE, tương đương về mặt toán học với hiệu suất tốt hơn. Xem phần Tính tương tự Cosine để tìm hiểu thêm.
DOT_PRODUCT Tương tự như cosin nhưng bị ảnh hưởng bởi độ lớn của vectơ. Xem Dot Product để tìm hiểu thêm.