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__ จะมีการต่อท้ายโดยค่าเริ่มต้น

ช่องจะต่อท้ายด้วยทิศทางการจัดเรียงเดียวกันกับลำดับสุดท้ายที่ระบุ หรือ "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

เคอร์เซอร์เริ่มต้นจะทำให้การค้นหาเริ่มต้นในตำแหน่งที่เป็นตรรกะ ซึ่งต่างจาก OFFSET ที่ต้องสแกนผลการค้นหา N รายการแรกเพื่อข้าม ตำแหน่งนี้ไม่จำเป็นต้องตรงกับผลลัพธ์จริง แต่จะสแกนไปข้างหน้าจากตำแหน่งนี้เพื่อหาเอกสารถัดไป

ข้อกำหนด

  • จำนวนค่าต้องไม่มากกว่าจำนวนช่องที่ระบุในวรรค 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__']

ตัวเลือกคอลเล็กชัน

คอลเล็กชันที่เลือก เช่น messages as m1

การแสดง JSON 
{
  "collectionId": string,
  "allDescendants": boolean
}
ช่อง
collectionId

string

รหัสคอลเล็กชัน เมื่อตั้งค่าแล้ว ระบบจะเลือกเฉพาะคอลเล็กชันที่มีรหัสนี้
allDescendants

boolean

เมื่อเป็นเท็จ เลือกเฉพาะคอลเล็กชันที่เป็นรายการย่อยของ parent ที่ระบุไว้ใน RunQueryRequest ที่มี เมื่อเป็น "จริง" เลือกคอลเล็กชันองค์ประกอบสืบทอดทั้งหมด

กรอง

ตัวกรอง

การแสดง 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 รายการ

ตัวกรองผสม

ตัวกรองที่รวมตัวกรองอื่นๆ หลายรายการโดยใช้โอเปอเรเตอร์ที่ระบุ

การแสดง JSON 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
ช่อง
op

enum (Operator)

โอเปอเรเตอร์สำหรับการรวมตัวกรองหลายรายการ
filters[]

object (Filter)

รายการตัวกรองที่จะรวม

ข้อกำหนด

  • ใช้ตัวกรองอยู่อย่างน้อย 1 รายการ

โอเปอเรเตอร์

โอเปอเรเตอร์ตัวกรองแบบผสม

Enum
OPERATOR_UNSPECIFIED ไม่ระบุ ต้องไม่ใช้ค่านี้
AND ต้องใช้เอกสารตามตัวกรองที่รวมกันทั้งหมด
OR ต้องใช้เอกสารเพื่อใช้ตัวกรองรวมกันอย่างน้อย 1 รายการ

ตัวกรองฟิลด์

ตัวกรองในช่องที่เจาะจง

การแสดง JSON 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
ช่อง
field

object (FieldReference)

ช่องที่ใช้กรอง
op

enum (Operator)

โอเปอเรเตอร์ที่ใช้กรอง
value

object (Value)

ค่าที่จะเปรียบเทียบ

โอเปอเรเตอร์

โอเปอเรเตอร์ตัวกรองช่อง

Enum
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 ที่ระบุเท่ากับอย่างน้อย 1 ค่าในอาร์เรย์ที่ระบุ

ข้อกำหนด

  • 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)

ฟิลด์ที่จะใช้โอเปอเรเตอร์

โอเปอเรเตอร์

โอเปอเรเตอร์แบบเอกภาค

Enum
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

ทิศทาง

ทิศทางการจัดเรียง

Enum
DIRECTION_UNSPECIFIED ไม่ระบุ
ASCENDING จากน้อยไปมาก
DESCENDING มากไปน้อย

ค้นหาที่ใกล้เคียงที่สุด

การกำหนดค่าการค้นหา Neighbor ที่ใกล้ที่สุด

การแสดง 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

การวัดระยะทาง

การวัดระยะทางที่จะใช้เมื่อเปรียบเทียบเวกเตอร์

Enum
DISTANCE_MEASURE_UNSPECIFIED ไม่ควรตั้งค่า
EUCLIDEAN วัดระยะห่าง EUCLIDEAN ระหว่างเวกเตอร์ ดู Euclidean เพื่อเรียนรู้เพิ่มเติม
COSINE เปรียบเทียบเวกเตอร์โดยอิงตามมุมระหว่างเวกเตอร์ ซึ่งจะช่วยให้คุณวัดความคล้ายคลึงกันที่ไม่ได้อิงตามขนาดของเวกเตอร์ได้ เราขอแนะนำให้ใช้ DOT_PRODUCT กับหน่วยเวกเตอร์มาตรฐานแทนระยะทาง COSINE ซึ่งเทียบเท่าทางคณิตศาสตร์และเพิ่มประสิทธิภาพที่ดีกว่า ดูข้อมูลเพิ่มเติมได้ที่ความคล้ายคลึงกันของโคไซน์
DOT_PRODUCT คล้ายกับโคไซน์ แต่ได้รับผลกระทบจากขนาดของเวกเตอร์ โปรดดูที่ Dot Product เพื่อเรียนรู้เพิ่มเติม