StructuredQuery

Eine Firestore-Abfrage.

Die Abfragephasen werden in der folgenden Reihenfolge ausgeführt: 1. von 2. wobei 3. 4. orderBy + startAt + endAt 5. offset 6. limit auswählen

JSON-Darstellung
{
  "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)
  }
}
Felder
select

object (Projection)

Optionale Teilmenge der zurückzugebenden Felder.

Sie dient als DocumentMask für die von einer Abfrage zurückgegebenen Dokumente. Wenn dieser Wert nicht festgelegt ist, wird davon ausgegangen, dass der Aufrufer alle Felder zurückgeben möchte.

from[]

object (CollectionSelector)

Die abzufragenden Sammlungen.

where

object (Filter)

Der Filter, der angewendet werden soll.

orderBy[]

object (Order)

Die Reihenfolge, die auf die Abfrageergebnisse angewendet werden soll.

Mit Firestore können Aufrufer eine vollständige, teilweise oder gar keine Sortierung angeben. In allen Fällen garantiert Firestore eine stabile Reihenfolge anhand der folgenden Regeln:

  • Der orderBy ist erforderlich, um auf alle Felder zu verweisen, die mit einem Ungleichheitsfilter verwendet werden.
  • Alle Felder, die im orderBy enthalten sein müssen, aber noch nicht vorhanden sind, werden in lexikografischer Reihenfolge des Feldnamens angehängt.
  • Wenn für __name__ kein Auftrag angegeben ist, wird er standardmäßig angehängt.

Die Felder werden mit derselben Sortierrichtung wie die zuletzt angegebene Reihenfolge oder „ASCENDING“ angehängt, wenn keine Reihenfolge angegeben wurde. Beispiel:

  • ORDER BY a wird zu ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC wird zu ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 wird zu WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 wird zu WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object (Cursor)

Ein potenzielles Präfix einer Position in der Ergebnismenge, an der die Abfrage gestartet werden soll.

Die Reihenfolge der Ergebnisse basiert auf der ORDER BY-Klausel der ursprünglichen Abfrage.

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

Die Ergebnisse dieser Abfrage sind nach (b ASC, __name__ ASC) sortiert.

Cursor können entweder auf die vollständige Reihenfolge oder ein Präfix des Standorts verweisen. Es können jedoch nicht mehr Felder als im angegebenen ORDER BY angegeben werden.

Ausgehend vom obigen Beispiel hat das Anhängen der folgenden Startcursor unterschiedliche Auswirkungen:

  • START BEFORE (2, /k/123): Die Abfrage wird direkt vor a = 1 AND b > 2 AND __name__ > /k/123 gestartet.
  • START AFTER (10): Die Abfrage wird direkt nach a = 1 AND b > 10 gestartet.

Im Gegensatz zu OFFSET, bei dem das Scannen über die ersten N Ergebnisse zum Überspringen erforderlich ist, ermöglicht ein Startcursor die Abfrage an einer logischen Position. Diese Position muss nicht mit einem tatsächlichen Ergebnis übereinstimmen. Von dieser Position aus wird das nächste Dokument vorwärts gespult.

Benötigt:

  • Die Anzahl der Werte darf nicht größer sein als die Anzahl der Felder, die in der ORDER BY-Klausel angegeben sind.
endAt

object (Cursor)

Ein potenzielles Präfix einer Position im Ergebnissatz, bei der die Abfrage beendet werden soll.

Dies ist ähnlich wie START_AT, legt jedoch nicht die Startposition, sondern die Endposition fest.

Benötigt:

  • Die Anzahl der Werte darf nicht größer sein als die Anzahl der Felder, die in der ORDER BY-Klausel angegeben sind.
offset

integer

Die Anzahl der Dokumente, die übersprungen werden sollen, bevor das erste Ergebnis zurückgegeben wird.

Dies gilt nach den von WHERE, START AT und END AT angegebenen Einschränkungen, aber vor der LIMIT-Klausel.

Benötigt:

  • Der Wert muss größer oder gleich null sein, falls angegeben.
limit

integer

Die maximale Anzahl von zurückzugebenden Ergebnissen.

Wird nach allen anderen Einschränkungen angewendet.

Benötigt:

  • Der Wert muss größer oder gleich null sein, falls angegeben.
findNearest

object (FindNearest)

Optional. Eine potenzielle Suche nach den nächstgelegenen Nachbarn.

Wird nach allen anderen Filtern und Sortierungen angewendet.

Findet die Vektoreinbettungen, die dem angegebenen Abfragevektor am nächsten sind.

Projektion

Die Projektion der zurückzugebenden Felder des Dokuments.

JSON-Darstellung
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
Felder
fields[]

object (FieldReference)

Die zurückzugebenden Felder.

Wenn leer, werden alle Felder zurückgegeben. Um nur den Namen des Dokuments zurückzugeben, verwenden Sie ['__name__'].

CollectionSelector

Eine Auswahl aus einer Sammlung, z. B. messages as m1.

JSON-Darstellung
{
  "collectionId": string,
  "allDescendants": boolean
}
Felder
collectionId

string

Die Sammlungs-ID. Wenn festgelegt, werden nur Sammlungen mit dieser ID ausgewählt.

allDescendants

boolean

Bei „false“ werden nur Sammlungen ausgewählt, die der parent, die in der enthaltenden RunQueryRequest angegeben sind, unmittelbar untergeordnet sind. Bei „true“ werden alle untergeordneten Sammlungen ausgewählt.

Filtern

Ein Filter.

JSON-Darstellung
{

  // 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.
}
Felder
Union-Feld filter_type. Der Typ des Filters. Für filter_type ist nur einer der folgenden Werte zulässig:
compositeFilter

object (CompositeFilter)

Zusammengesetzter Filter

fieldFilter

object (FieldFilter)

Ein Filter für ein Dokumentfeld.

unaryFilter

object (UnaryFilter)

Ein Filter, der genau ein Argument annimmt.

CompositeFilter

Ein Filter, der mehrere andere Filter mithilfe des angegebenen Operators zusammenführt.

JSON-Darstellung
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
Felder
op

enum (Operator)

Der Operator zum Kombinieren mehrerer Filter.

filters[]

object (Filter)

Die Liste der zu kombinierenden Filter.

Benötigt:

  • Mindestens ein Filter ist vorhanden.

Operator

Operator für zusammengesetzte Filter

Enums
OPERATOR_UNSPECIFIED Nicht angegeben Dieser Wert darf nicht verwendet werden.
AND Dokumente müssen allen kombinierten Filtern entsprechen.
OR Dokumente müssen mindestens einem der kombinierten Filter entsprechen.

FieldFilter

Ein Filter für ein bestimmtes Feld.

JSON-Darstellung
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
Felder
field

object (FieldReference)

Das Feld, nach dem gefiltert werden soll.

op

enum (Operator)

Operator, nach dem gefiltert werden soll.

value

object (Value)

Wert, mit dem verglichen werden soll

Operator

Ein Feldfilteroperator.

Enums
OPERATOR_UNSPECIFIED Nicht angegeben Dieser Wert darf nicht verwendet werden.
LESS_THAN

Der angegebene field ist kleiner als der angegebene value.

Benötigt:

  • Diese field stehen bei orderBy an erster Stelle.
LESS_THAN_OR_EQUAL

Der angegebene field ist kleiner oder gleich dem angegebenen value.

Benötigt:

  • Diese field stehen bei orderBy an erster Stelle.
GREATER_THAN

Die angegebene field ist größer als die angegebene value.

Benötigt:

  • Diese field stehen bei orderBy an erster Stelle.
GREATER_THAN_OR_EQUAL

Der angegebene field ist größer oder gleich dem angegebenen value.

Benötigt:

  • Diese field stehen bei orderBy an erster Stelle.
EQUAL Die angegebene field ist gleich der angegebenen value.
NOT_EQUAL

Die angegebene field ist nicht gleich der angegebenen value.

Benötigt:

  • Keine anderen NOT_EQUAL, NOT_IN, IS_NOT_NULL oder IS_NOT_NAN.
  • Dieses field steht in der orderBy an erster Stelle.
ARRAY_CONTAINS Die angegebene field ist ein Array, das den angegebenen value enthält.
IN

Die angegebene field ist gleich mindestens ein Wert im angegebenen Array.

Benötigt:

  • Diese value ist eine nicht leere ArrayValue, vorbehaltlich Disjunktionslimits.
  • Keine NOT_IN-Filter in derselben Abfrage.
ARRAY_CONTAINS_ANY

Die angegebene field ist ein Array, das einen der Werte im gegebenen Array enthält.

Benötigt:

  • Diese value ist eine nicht leere ArrayValue, vorbehaltlich Disjunktionslimits.
  • Keine anderen ARRAY_CONTAINS_ANY-Filter in derselben Disjunktion.
  • Keine NOT_IN-Filter in derselben Abfrage.
NOT_IN

Der Wert von field ist nicht im angegebenen Array enthalten.

Benötigt:

  • Diese value ist eine nicht leere ArrayValue mit höchstens 10 Werten.
  • Keine anderen OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL oder IS_NOT_NAN.
  • Dieses field steht in der orderBy an erster Stelle.

UnaryFilter

Ein Filter mit einem einzelnen Operanden.

JSON-Darstellung
{
  "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.
}
Felder
op

enum (Operator)

Der anzuwendende unäre Operator.

Union-Feld operand_type. Das Argument für den Filter. Für operand_type ist nur einer der folgenden Werte zulässig:
field

object (FieldReference)

Das Feld, auf das der Operator angewendet werden soll.

Operator

Ein unärer Operator.

Enums
OPERATOR_UNSPECIFIED Nicht angegeben Dieser Wert darf nicht verwendet werden.
IS_NAN Der angegebene field ist gleich NaN.
IS_NULL Der angegebene field ist gleich NULL.
IS_NOT_NAN

Der angegebene field ist nicht gleich NaN.

Benötigt:

  • Keine anderen NOT_EQUAL, NOT_IN, IS_NOT_NULL oder IS_NOT_NAN.
  • Dieses field steht in der orderBy an erster Stelle.
IS_NOT_NULL

Der angegebene field ist nicht gleich NULL.

Benötigt:

  • Ein einzelnes NOT_EQUAL-, NOT_IN-, IS_NOT_NULL- oder IS_NOT_NAN-Objekt.
  • Dieses field steht in der orderBy an erster Stelle.

Auftrag

Eine Bestellung auf einem Feld.

JSON-Darstellung
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
Felder
field

object (FieldReference)

Das Feld, nach dem sortiert werden soll.

direction

enum (Direction)

Die Richtung, nach der sortiert werden soll. Die Standardeinstellung ist ASCENDING.

Richtung

Eine Sortierrichtung.

Enums
DIRECTION_UNSPECIFIED Nicht angegeben
ASCENDING Aufsteigend.
DESCENDING Absteigend.

FindNearest

Konfiguration für „Nächstgelegene Neighbors“-Suche.

JSON-Darstellung
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
Felder
vectorField

object (FieldReference)

Erforderlich. Ein indexiertes Vektorfeld, nach dem gesucht werden soll. Es können nur Dokumente zurückgegeben werden, die Vektoren enthalten, deren Dimensionalität mit queryVector übereinstimmt.

queryVector

object (Value)

Erforderlich. Der Abfragevektor, nach dem gesucht wird. Darf ein Vektor mit maximal 2.048 Dimensionen sein.

distanceMeasure

enum (DistanceMeasure)

Erforderlich. Die zu verwendende Distanzmessung (erforderlich).

limit

integer

Erforderlich. Die Anzahl der nächsten Nachbarn, die zurückgegeben werden sollen. Muss eine positive Ganzzahl bis 1.000 sein.

DistanceMeasure

Die Entfernungsmessung, die beim Vergleich von Vektoren verwendet werden soll.

Enums
DISTANCE_MEASURE_UNSPECIFIED Sollte nicht festgelegt werden.
EUCLIDEAN Misst die EUCLIDEAN-Entfernung zwischen den Vektoren. Weitere Informationen finden Sie auf der Seite Euklidisch.
COSINE Vergleicht Vektoren basierend auf dem Winkel zwischen ihnen, sodass Sie Ähnlichkeiten messen können, die nicht auf der Größe der Vektoren basieren. Wir empfehlen die Verwendung von DOT_PRODUCT mit normalisierten Vektoren der Einheit anstelle der COSINE-Entfernung, die mathematisch gleichwertig mit einer besseren Leistung ist. Weitere Informationen finden Sie unter Kosinus-Ähnlichkeit.
DOT_PRODUCT Ähnlich wie der Kosinus, wird aber von der Größe der Vektoren beeinflusst. Weitere Informationen finden Sie unter Dot Product.