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__']

CollectionSelector

คอลเล็กชันที่เลือก เช่น 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)

ตัวกรองที่ใช้อาร์กิวเมนต์เพียงรายการเดียว

CompositeFilter

ตัวกรองที่ผสานตัวกรองอื่นๆ หลายรายการโดยใช้โอเปอเรเตอร์ที่กำหนด

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

enum (Operator)

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

object (Filter)

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

ข้อกำหนด

  • มีตัวกรองอย่างน้อยหนึ่งรายการ

ผู้ประกอบธุรกิจ

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

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

FieldFilter

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

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

UnaryFilter

ตัวกรองที่มีตัวถูกดำเนินการเดี่ยว

การแสดง 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 มากไปน้อย

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

ต้องระบุ จำนวนเพื่อนบ้านที่ใกล้ที่สุดที่จะส่งคืน ต้องเป็นจำนวนเต็มบวกที่ไม่เกิน 1000

DistanceMeasure

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

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