Ausdrücke, Funktionen und Operatoren

Auf dieser Seite werden SQL-Ausdrücke von Cloud Spanner einschließlich Funktionen und Operatoren erläutert.

Regeln für Funktionsaufrufe

Die folgenden Regeln gelten für alle Funktionen, es sei denn, die Funktionsbeschreibung gibt explizit etwas anderes an:

  • Bei Funktionen, die numerische Typen akzeptieren, wenn ein Operand ein Gleitkomma-Operand und der andere Operand ein anderer numerischer Typ ist, werden beide Operanden in FLOAT64 umgewandelt, bevor die Funktion ausgewertet wird.
  • Ist ein Operand NULL, ist das Ergebnis mit Ausnahme des IS-Operators NULL.
  • Für Funktionen, bei denen die Zeitzone beachtet werden muss (wie in der Funktionsbeschreibung angegeben), wird die Standardzeitzone "America/Los_Angeles" verwendet, wenn keine Zeitzone festgelegt ist.

SAFE.-Präfix

Syntax:

SAFE.function_name()

Beschreibung

Wenn Sie eine Skalarfunktion mit dem Präfix SAFE. beginnen, wird anstelle eines Fehlers NULL zurückgegeben. Das Präfix SAFE. verhindert nur Fehler bei der mit dem Präfix versehenen Funktion selbst. Fehler während der Auswertung von Argumentausdrücken werden damit nicht vermieden. Das Präfix SAFE. verhindert nur Fehler im Zusammenhang mit dem Wert, der für die Funktion eingegeben wird, z. B. Fehler vom Typ "Wert außerhalb des Bereichs". Andere Fehler wie interne Fehler oder Systemfehler können trotzdem auftreten. Wenn die Funktion keinen Fehler zurückgibt, hat SAFE. keine Auswirkungen auf die Ausgabe. Gibt die Funktion nie einen Fehler zurück, wie beispielsweise die Funktion RAND, hat SAFE. ebenfalls keine Auswirkungen.

Operatoren wie + und = unterstützen das Präfix SAFE. nicht. Verwenden Sie SAFE_DIVIDE, um Fehler bei einer Division zu vermeiden. Manche Operatoren wie IN, ARRAY und UNNEST sind Funktionen ähnlich, unterstützen aber das Präfix SAFE. nicht. Die Funktionen CAST und EXTRACT unterstützen das Präfix SAFE. ebenfalls nicht. Verwenden Sie SAFE_CAST, um Fehler bei der Umwandlung zu vermeiden.

Beispiel

Im folgenden Beispiel würde bei der ersten Verwendung der Funktion SUBSTR normalerweise ein Fehler zurückgegeben, weil die Funktion keine Längenargumente mit negativen Werten unterstützt. Das Präfix SAFE. bewirkt jedoch, dass die Funktion stattdessen NULL zurückgibt. Die zweite Verwendung der Funktion SUBSTR führt zur erwarteten Ausgabe: Das Präfix SAFE. hat keine Auswirkung.

SELECT SAFE.SUBSTR('foo', 0, -2) AS safe_output UNION ALL
SELECT SAFE.SUBSTR('bar', 0, 2) AS safe_output;

+-------------+
| safe_output |
+-------------+
| NULL        |
| ba          |
+-------------+

Konversionsregeln

Der Begriff "Konversion" umfasst unter anderem die Prozesse des Umwandelns und Erzwingens.

  • Das Umwandeln ist eine explizite Konversion, für die die Funktion CAST() verwendet wird.
  • Das Erzwingen ist eine implizite Konversion, die von Cloud Spanner SQL unter den unten beschriebenen Bedingungen automatisch ausgeführt wird.
  • Außerdem gibt es eine dritte Gruppe von Konversionsfunktionen, die einen eigenen Funktionsnamen haben, z. B. UNIX_DATE().

In der folgenden Tabelle sind alle verfügbaren Konversionen zum Umwandeln (CAST) und Erzwingen für die Cloud Spanner SQL-Datentypen zusammengefasst. "Erzwingen in" gilt für alle Ausdrücke eines angegebenen Datentyps (z. B. für Spalten).

Von Typ Umwandeln in Erzwingen in
INT64 BOOL
INT64
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
FLOAT64
STRING
BYTES
DATE
TIMESTAMP
 
BYTES BYTES
STRING
 
DATE DATE
STRING
TIMESTAMP
 
TIMESTAMP DATE
STRING
TIMESTAMP
 
ARRAY ARRAY  
STRUCT STRUCT  

Umwandeln

Syntax:

CAST(expr AS typename)

Die Umwandlungssyntax wird in einer Abfrage verwendet, um anzuzeigen, dass der Ergebnistyp eines Ausdrucks in einen anderen Typ umgewandelt werden soll.

Beispiel:

CAST(x=1 AS STRING)

Daraus ergibt sich "true", wenn x gleich 1 ist, "false" für jeden anderen Nicht-NULL-Wert und NULL, wenn x gleich NULL ist.

Umwandlungen von unterstützten Typen, die vom Originalwert nicht erfolgreich der Zieldomain zugeordnet werden können, erzeugen Laufzeitfehler. Zum Beispiel führt das Umwandeln von BYTES in STRING bei nicht gültiger UTF-8-Codierung der Bytesequenz zu einem Laufzeitfehler.

Beim Umwandeln eines Ausdrucks x der folgenden Typen gelten die angegebenen Regeln:

Von Zu Regel(n) beim Umwandeln von x
INT64 FLOAT64 Gibt einen annähernden, aber möglicherweise keinen exakten FLOAT64-Wert zurück.
INT64 BOOL Gibt FALSE zurück, wenn x gleich 0 ist, ansonsten TRUE.
FLOAT64 INT64 Gibt den am nächsten liegenden INT64-Wert zurück.
Halbe Zahlen wie 1,5 oder -0,5 werden von 0 weggerundet.
FLOAT64 STRING Gibt eine ungefähre Stringdarstellung zurück.
BOOL INT64 Gibt 1 zurück, wenn x gleich TRUE ist, ansonsten 0.
BOOL STRING Gibt "true" zurück, wenn x gleich TRUE ist, ansonsten "false".
STRING FLOAT64 Gibt x als einen FLOAT64-Wert zurück und interpretiert diesen als gültiges FLOAT64-Literal.
Unterstützt auch Umwandlungen von "inf", "+inf", "-inf" und "nan".
Bei Konversionen wird die Groß-/Kleinschreibung nicht berücksichtigt.
STRING BOOL Gibt TRUE zurück, wenn x gleich "true" ist, und FALSE, wenn x gleich "false" ist.
Alle anderen Werte von x sind ungültig und erzeugen einen Fehler, statt in BOOL umgewandelt zu werden.
Bei STRING-Werten wird bei der Umwandlung in BOOL die Groß-/Kleinschreibung nicht berücksichtigt.
STRING BYTES STRINGs werden mithilfe der UTF-8-Codierung in BYTES umgewandelt. Der STRING "©" wird beispielsweise bei der Umwandlung in BYTES eine 2-Byte-Sequenz mit den Hex-Werten C2 und A9.
BYTES STRING Gibt x als UTF-8-STRING interpretiert zurück.
Beispiel: Das BYTES-Literal b'\xc2\xa9' wird beim Umwandeln in STRING als UTF-8 interpretiert und zum Unicode-Zeichen "©" konvertiert.
Falls x keine gültige UTF-8-Codierung ist, tritt ein Fehler auf.
ARRAY ARRAY Muss exakt derselbe ARRAY-Typ sein.
STRUCT STRUCT Zulässig, wenn folgende Bedingungen erfüllt sind:
  1. Die beiden STRUCTs haben dieselbe Feldanzahl.
  2. Die ursprünglichen STRUCT-Feldtypen können explizit in die entsprechenden Ziel-STRUCT-Feldtypen (wie nach Feldreihenfolge, nicht nach Feldname definiert) umgewandelt werden.

Sicheres Umwandeln

Bei Verwendung von CAST kann eine Abfrage fehlschlagen, wenn Cloud Spanner SQL die Umwandlung nicht durchführen kann. Die folgende Abfrage erzeugt beispielsweise einen Fehler:

SELECT CAST("apple" AS INT64) AS not_a_number;

Wenn Sie Ihre Abfragen vor diesen Fehlern schützen möchten, können Sie SAFE_CAST verwenden. SAFE_CAST ist mit CAST identisch, allerdings wird Null zurückgegeben und kein Fehler ausgelöst.

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

Zum Umwandeln von Byte in Strings können Sie auch die Funktion SAFE_CONVERT_BYTES_TO_STRING verwenden. Alle ungültigen UTF-8-Zeichen werden durch das Unicode-Ersatzzeichen U+FFFD ersetzt. Weitere Informationen finden Sie unter SAFE_CONVERT_BYTES_TO_STRING.

Hex-Strings in Ganzzahlen umwandeln

Wenn Sie mit Hex-Strings (0x123) arbeiten, können Sie diese in Ganzzahlen umwandeln:

SELECT '0x123' as hex_value, CAST('0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | 291        |
+-----------+------------+

SELECT '-0x123' as hex_value, CAST('-0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| -0x123    | -291       |
+-----------+------------+

Datumstypen umwandeln

Cloud Spanner SQL unterstützt das Umwandeln von Datumstypen in/aus Strings in folgender Form:

CAST(date_expression AS STRING)
CAST(string_expression AS DATE)

Die Umwandlung von einem Datumstyp in einen String ist unabhängig von der Zeitzone und erfolgt in der Form YYYY-MM-DD. Bei der Umwandlung eines Strings in ein Datum muss der String dem unterstützten Datumsliteralformat entsprechen und ist von der Zeitzone unabhängig. Wenn der Stringausdruck ungültig ist oder ein Datum darstellt, das außerhalb des unterstützten Mindest-/Maximalbereichs liegt, wird ein Fehler erzeugt.

Zeitstempeltypen umwandeln

Cloud Spanner SQL unterstützt das Umwandeln von Zeitstempeltypen in/aus Strings wie folgt:

CAST(timestamp_expression AS STRING)
CAST(string_expression AS TIMESTAMP)

Beim Umwandeln von Zeitstempeltypen in Strings wird der Zeitstempel mithilfe der Standardzeitzone "America/Los_Angeles" interpretiert. Wie viele Stellen für Sekundenbruchteile erzeugt werden, hängt von der Anzahl der angehängten Nullen im Sekundenbruchteilbereich ab. Die Funktion CAST schneidet null, drei oder sechs Stellen ab.

Beim Umwandeln von Strings in Zeitstempel muss string_expression den unterstützten Zeitstempel-Literalformaten entsprechen. Ansonsten tritt ein Laufzeitfehler auf. string_expression kann selbst eine time_zone-Zeitzone enthalten. Weitere Informationen finden Sie unter Zeitzonen. Wenn in string_expression eine Zeitzone vorhanden ist, wird diese Zeitzone für die Konversion verwendet, andernfalls gilt die Standardzeitzone "America/Los_Angeles". Hat der String weniger als sechs Stellen, wird er implizit erweitert.

Wenn string_expression ungültig ist, mehr als sechs Stellen im Sekundenbruchteilbereich (also eine höhere Genauigkeit als Mikrosekunden) hat oder eine Zeit außerhalb des unterstützten Zeitstempelbereichs darstellt, wird ein Fehler zurückgegeben.

Zwischen Datums- und Zeitstempeltypen umwandeln

Cloud Spanner SQL unterstützt die Umwandlung zwischen Datums- und Zeitstempeltypen in folgender Form:

CAST(date_expression AS TIMESTAMP)
CAST(timestamp_expression AS DATE)

Bei der Umwandlung eines Datums in einen Zeitstempel wird als Uhrzeit für date_expression Mitternacht (Tagesbeginn) in der Standardzeitzone "America/Los_Angeles" angenommen. Die Umwandlung eines Zeitstempels in ein Datum trennt den Zeitstempel effektiv ab der Standardzeitzone.

Erzwingen

Cloud Spanner SQL erzwingt bei Bedarf das Ändern des Ergebnistyps für einen Ausdruck in einen anderen Typ, um die Funktionssignaturen abzugleichen. Wenn beispielsweise die Funktion "func()" so definiert ist, dass sie ein einziges Argument von Typ INT64 übernimmt, und ein Ausdruck als ein Argument mit einem Ergebnistyp von FLOAT64 verwendet wird, wird vor der Berechnung von "func()" der Typ INT64 für das Ergebnis des Ausdrucks erzwungen.

Zusätzliche Konversionsfunktionen

Cloud Spanner SQL bietet die folgenden zusätzlichen Konversionsfunktionen:

Aggregatfunktionen

Eine Aggregatfunktion ist eine Funktion, die die Zeilen einer Gruppe in einem einzelnen Wert zusammenfasst. Beispiele für Aggregatfunktionen sind COUNT, MIN und MAX.

SELECT COUNT(*) as total_count, COUNT(fruit) as non_null_count,
       MIN(fruit) as min, MAX(fruit) as max
FROM (SELECT NULL as fruit UNION ALL
      SELECT "apple" as fruit UNION ALL
      SELECT "pear" as fruit UNION ALL
      SELECT "orange" as fruit)

+-------------+----------------+-------+------+
| total_count | non_null_count | min   | max  |
+-------------+----------------+-------+------+
| 4           | 3              | apple | pear |
+-------------+----------------+-------+------+

Bei Verwendung in Verbindung mit einer GROUP BY-Klausel haben die zusammengefassten Gruppen normalerweise mindestens eine Zeile. Wenn das zugehörige SELECT keine GROUP BY-Klausel hat oder wenn bestimmte Modifikatoren für Aggregatfunktionen Zeilen aus der zu verdichtenden Gruppe filtern, ist es möglich, dass die Aggregatfunktion eine leere Gruppe verdichten muss. In diesem Fall geben die Funktionen COUNT und COUNTIF 0 zurück, während alle anderen Aggregatfunktionen NULL zurückgeben.

In den folgenden Abschnitten werden die von Cloud Spanner SQL unterstützten Aggregatfunktionen erläutert.

ANY_VALUE

ANY_VALUE(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt für eine aus der Gruppe ausgewählte Zeile expression zurück. Welche Zeile ausgewählt wird, ist unbestimmt und nicht zufällig. Gibt NULL zurück, wenn die Eingabe keine Zeilen erzeugt. Gibt NULL zurück, wenn expression für alle Zeilen in der Gruppe NULL ist.

ANY_VALUE verhält sich so, als wäre IGNORE NULLS angegeben. Zeilen, für die expression den Wert NULL hat, werden nicht berücksichtigt und nicht ausgewählt.

Unterstützte Argumenttypen

Beliebig

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Zurückgegebene Datentypen

Entspricht dem Eingabedatentyp.

Beispiele

SELECT ANY_VALUE(fruit) as any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+-----------+
| any_value |
+-----------+
| apple     |
+-----------+

ARRAY_AGG

ARRAY_AGG([DISTINCT] expression [{IGNORE|RESPECT} NULLS] [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt ein ARRAY von expression-Werten zurück.

Unterstützte Argumenttypen

Alle Datentypen außer ARRAY.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. IGNORE NULLS oder RESPECT NULLS: Wenn IGNORE NULLS angegeben ist, werden die NULL-Werte aus dem Ergebnis ausgeschlossen. Wenn RESPECT NULLS oder kein Wert angegeben ist, werden die NULL-Werte in das Ergebnis eingeschlossen.
  3. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Reihenfolge der Elemente in der Ausgabe

Die Reihenfolge der Elemente in der Ausgabe ist nicht deterministisch. Dies bedeutet, dass Sie bei jeder Nutzung dieser Funktion möglicherweise ein anderes Ergebnis erhalten.

Zurückgegebene Datentypen

ARRAY

Wenn keine Eingabezeilen vorhanden sind, gibt diese Funktion NULL zurück.

Beispiele

SELECT ARRAY_AGG(x) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------------+
| array_agg               |
+-------------------------+
| [2, 1, -2, 3, -2, 1, 2] |
+-------------------------+
SELECT ARRAY_AGG(DISTINCT x) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+---------------+
| array_agg     |
+---------------+
| [2, 1, -2, 3] |
+---------------+
SELECT ARRAY_AGG(x IGNORE NULLS) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [1, -2, 3, -2, 1] |
+-------------------+

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Verkettet Elemente aus expression vom Typ ARRAY und gibt ein einziges ARRAY als Ergebnis zurück. Diese Funktion ignoriert NULL-Eingabe-Arrays, berücksichtigt aber die NULL-Elemente in Nicht-NULL-Eingabe-Arrays.

Unterstützte Argumenttypen

ARRAY

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Reihenfolge der Elemente in der Ausgabe

Die Reihenfolge der Elemente in der Ausgabe ist nicht deterministisch. Dies bedeutet, dass Sie bei jeder Nutzung dieser Funktion möglicherweise ein anderes Ergebnis erhalten.

Zurückgegebene Datentypen

ARRAY

Gibt NULL zurück, wenn keine Eingabezeilen vorhanden sind oder expression für alle Zeilen als NULL ausgewertet wird.

Beispiele

SELECT ARRAY_CONCAT_AGG(x) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
+-----------------------------------+

AVG

AVG([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt den Durchschnitt der Nicht-NULL-Eingabewerte zurück oder NaN, wenn die Eingabe einen NaN-Wert enthält.

Unterstützte Argumenttypen

Jeder numerische Eingabetyp, z. B. INT64. Bitte beachten Sie, dass das zurückgegebene Ergebnis für Gleitkomma-Eingabetypen nicht deterministisch ist, was bedeutet, dass Sie jedes Mal, wenn Sie diese Funktion nutzen, ein anderes Ergebnis erhalten.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Zurückgegebene Datentypen

  • FLOAT64

Beispiele

SELECT AVG(x) as avg
FROM UNNEST([0, 2, 4, 4, 5]) as x;

+-----+
| avg |
+-----+
| 3   |
+-----+
SELECT AVG(DISTINCT x) AS avg
FROM UNNEST([0, 2, 4, 4, 5]) AS x;

+------+
| avg  |
+------+
| 2.75 |
+------+

BIT_AND

BIT_AND([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Führt eine bitweise AND-Operation für expression aus und gibt das Ergebnis zurück.

Unterstützte Argumenttypen

  • INT64

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Zurückgegebene Datentypen

INT64

Beispiele

SELECT BIT_AND(x) as bit_and FROM UNNEST([0xF001, 0x00A1]) as x;

+---------+
| bit_and |
+---------+
| 1       |
+---------+

BIT_OR

BIT_OR([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Führt eine bitweise OR-Operation für expression aus und gibt das Ergebnis zurück.

Unterstützte Argumenttypen

  • INT64

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Zurückgegebene Datentypen

INT64

Beispiele

SELECT BIT_OR(x) as bit_or FROM UNNEST([0xF001, 0x00A1]) as x;

+--------+
| bit_or |
+--------+
| 61601  |
+--------+

BIT_XOR

BIT_XOR([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Führt eine bitweise XOR-Operation für expression aus und gibt das Ergebnis zurück.

Unterstützte Argumenttypen

  • INT64

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Zurückgegebene Datentypen

INT64

Beispiele

SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+
SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 5678    |
+---------+
SELECT BIT_XOR(DISTINCT x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+

COUNT

1. COUNT(*)

2. COUNT([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

  1. Gibt die Anzahl der Zeilen in der Eingabe zurück.
  2. Gibt die Anzahl der Zeilen zurück, in denen expression als beliebiger Wert außer NULL ausgewertet wurde.

Unterstützte Argumenttypen

expression kann ein beliebiger Datentyp sein.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Rückgabedatentypen

INT64

Beispiele

SELECT
  COUNT(*) AS count_star,
  COUNT(DISTINCT x) AS count_dist_x
FROM UNNEST([1, 4, 4, 5]) AS x;

+------------+--------------+
| count_star | count_dist_x |
+------------+--------------+
| 4          | 3            |
+------------+--------------+
SELECT COUNT(*) AS count_star, COUNT(x) AS count_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------------+---------+
| count_star | count_x |
+------------+---------+
| 5          | 4       |
+------------+---------+

COUNTIF

COUNTIF([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt die Anzahl der TRUE-Werte für expression zurück. Gibt 0 zurück, wenn keine Eingabezeilen vorhanden sind oder wenn expression für alle Zeilen als FALSE oder NULL ausgewertet wird.

Unterstützte Argumenttypen

BOOL

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Rückgabedatentypen

INT64

Beispiele

SELECT COUNTIF(x<0) AS num_negative, COUNTIF(x>0) AS num_positive
FROM UNNEST([5, -2, 3, 6, -10, -7, 4, 0]) AS x;

+--------------+--------------+
| num_negative | num_positive |
+--------------+--------------+
| 3            | 4            |
+--------------+--------------+

LOGICAL_AND

LOGICAL_AND(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt das logische AND aller Nicht-NULL-Ausdrücke zurück. Gibt NULL zurück, wenn keine Eingabezeilen vorhanden sind oder expression für alle Zeilen als NULL ausgewertet wird.

Unterstützte Argumenttypen

BOOL

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Rückgabedatentypen

BOOL

Beispiele

SELECT LOGICAL_AND(x) AS logical_and FROM UNNEST([true, false, true]) AS x;

+-------------+
| logical_and |
+-------------+
| false       |
+-------------+

LOGICAL_OR

LOGICAL_OR(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt das logische OR aller Nicht-NULL-Ausdrücke zurück. Gibt NULL zurück, wenn keine Eingabezeilen vorhanden sind oder expression für alle Zeilen als NULL ausgewertet wird.

Unterstützte Argumenttypen

BOOL

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Rückgabedatentypen

BOOL

Beispiele

SELECT LOGICAL_OR(x) AS logical_or FROM UNNEST([true, false, true]) AS x;

+------------+
| logical_or |
+------------+
| true       |
+------------+

MAX

MAX(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt den höchsten Wert der Nicht-NULL-Ausdrücke zurück. Gibt NULL zurück, wenn keine Eingabezeilen vorhanden sind oder expression für alle Zeilen als NULL ausgewertet wird. Gibt NaN zurück, wenn die Eingabe einen NaN-Wert enthält.

Unterstützte Argumenttypen

Alle Datentypen außer: ARRAY STRUCT

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Rückgabedatentypen

Derselbe Datentyp, der als Eingabewert verwendet wird.

Beispiele

SELECT MAX(x) AS max
FROM UNNEST([8, 37, 4, 55]) AS x;

+-----+
| max |
+-----+
| 55  |
+-----+

MIN

MIN(expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt den Mindestwert der Nicht-NULL-Ausdrücke zurück. Gibt NULL zurück, wenn keine Eingabezeilen vorhanden sind oder expression für alle Zeilen als NULL ausgewertet wird. Gibt NaN zurück, wenn die Eingabe einen NaN-Wert enthält.

Unterstützte Argumenttypen

Alle Datentypen außer: ARRAY STRUCT

Optionale Klausel

HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX und HAVING MIN-Klausel.

Rückgabedatentypen

Derselbe Datentyp, der als Eingabewert verwendet wird.

Beispiele

SELECT MIN(x) AS min
FROM UNNEST([8, 37, 4, 55]) AS x;

+-----+
| min |
+-----+
| 4   |
+-----+

STRING_AGG

STRING_AGG([DISTINCT] expression [, delimiter] [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt einen Wert (entweder STRING oder BYTES) zurück, der durch die Verkettung von Nicht-Null-Werten erlangt wird.

Wenn ein delimiter angegeben ist, werden verkettete Werte durch dieses Trennzeichen voneinander getrennt. Andernfalls wird ein Komma als Trennzeichen verwendet.

Unterstützte Argumenttypen

STRING BYTES

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Reihenfolge der Elemente in der Ausgabe

Die Reihenfolge der Elemente in der Ausgabe ist nicht deterministisch. Dies bedeutet, dass Sie bei jeder Nutzung dieser Funktion möglicherweise ein anderes Ergebnis erhalten.

Rückgabedatentypen

STRING BYTES

Beispiele

SELECT STRING_AGG(fruit) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------+
| string_agg             |
+------------------------+
| apple,pear,banana,pear |
+------------------------+
SELECT STRING_AGG(fruit, " & ") AS string_agg
FROM UNNEST(["apple", "pear", "banana", "pear"]) AS fruit;

+------------------------------+
| string_agg                   |
+------------------------------+
| apple & pear & banana & pear |
+------------------------------+
SELECT STRING_AGG(DISTINCT fruit, " & ") AS string_agg
FROM UNNEST(["apple", "pear", "banana", "pear"]) AS fruit;

+-----------------------+
| string_agg            |
+-----------------------+
| apple & pear & banana |
+-----------------------+

SUM

SUM([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt die Summe der Nicht-Null-Werte zurück.

Ist der Ausdruck ein Gleitkommawert, ist die Summe nicht-deterministisch, was bedeutet, dass Sie jedes Mal, wenn Sie diese Funktion nutzen, ein anderes Ergebnis erhalten.

Unterstützte Argumenttypen

Alle unterstützten numerischen Datentypen.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Rückgabedatentypen

  • Gibt INT64 zurück, wenn die Eingabe eine ganze Zahl ist.
  • Gibt FLOAT64 zurück, wenn die Eingabe ein Gleitkommawert ist.

Gibt NULL zurück, wenn die Eingabe nur NULL-Werte enthält.

Gibt NULL zurück, wenn die Eingabe keine Zeilen enthält.

Gibt Inf zurück, wenn die Eingabe Inf enthält.

Gibt -Inf zurück, wenn die Eingabe -Inf enthält.

Gibt NaN zurück, wenn die Eingabe einen NaN-Wert enthält.

Gibt NaN zurück, wenn die Eingabe eine Kombination aus Inf und -Inf enthält.

Beispiele

SELECT SUM(x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 25  |
+-----+
SELECT SUM(DISTINCT x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 15  |
+-----+
SELECT SUM(x) AS sum
FROM UNNEST([]) AS x;

+------+
| sum  |
+------+
| NULL |
+------+

Allgemeine Klauseln

HAVING MAX und HAVING MIN-Klausel

Die meisten Aggregatfunktionen unterstützen zwei optionale Klauseln mit dem Namen HAVING MAX und HAVING MIN, die den Satz von Zeilen, die von einer Funktion zusammengefasst werden, auf Zeilen mit einem Höchst- oder Mindestwert in einer bestimmten Spalte einschränken. Die Syntax sieht im Allgemeinen so aus:

aggregate_function(expression1 [HAVING {MAX | MIN} expression2])
  • HAVING MAX: Beschränkt den Satz von Zeilen, die von der Funktion zusammengefasst werden, auf einen Wert für expression2, der dem Höchstwert für expression2 innerhalb der Gruppe entspricht. Der Höchstwert entspricht dem Ergebnis von MAX(expression2).
  • HAVING MIN: Beschränkt den Satz von Zeilen, die von der Funktion zusammengefasst werden, auf einen Wert für expression2, der dem Mindestwert für expression2 innerhalb der Gruppe entspricht. Der Mindestwert entspricht dem Ergebnis von MIN(expression2).

Diese Klauseln ignorieren NULL-Werte, wenn der Höchst- oder Mindestwert berechnet wird, es sei denn, expression2 ergibt NULL für alle Zeilen.

Diese Klauseln unterstützen die folgenden Datentypen nicht: ARRAY STRUCT

Beispiel

In diesem Beispiel wird der durchschnittliche Niederschlag für das letzte Jahr 2001 zurückgegeben.

WITH Precipitation AS
 (SELECT 2001 as year, 'spring' as season, 9 as inches UNION ALL
  SELECT 2001, 'winter', 1 UNION ALL
  SELECT 2000, 'fall', 3 UNION ALL
  SELECT 2000, 'summer', 5 UNION ALL
  SELECT 2000, 'spring', 7 UNION ALL
  SELECT 2000, 'winter', 2)
SELECT AVG(inches HAVING MAX year) as average FROM Precipitation

+---------+
| average |
+---------+
| 5       |
+---------+

Zuerst ruft die Abfrage die Zeilen mit dem Höchstwert in der Spalte year ab. Es gibt zwei:

+------+--------+--------+
| year | season | inches |
+------+--------+--------+
| 2001 | spring | 9      |
| 2001 | winter | 1      |
+------+--------+--------+

Schließlich ermittelt die Abfrage die Werte in der Spalte inches (9 und 1) mit diesem Ergebnis:

+---------+
| average |
+---------+
| 5       |
+---------+

Statistische Aggregatfunktionen

Cloud Spanner SQL unterstützt die folgenden statistischen Aggregatfunktionen.

STDDEV_SAMP

STDDEV_SAMP([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt die (unverzerrte) Standardabweichung der Werte zurück. Das zurückgegebene Ergebnis liegt zwischen 0 und +Inf.

Diese Funktion ignoriert alle NULL-Eingaben. Wenn weniger als zwei Nicht-NULL-Eingaben vorhanden sind, gibt diese Funktion NULL zurück.

Unterstützte Eingabetypen

FLOAT64

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Rückgabedatentyp

FLOAT64

STDDEV

STDDEV([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Ein Alias von STDDEV_SAMP.

VAR_SAMP

VAR_SAMP([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Gibt die (nicht verzerrte) Stichprobenvarianz der Werte zurück. Das zurückgegebene Ergebnis liegt zwischen 0 und +Inf.

Diese Funktion ignoriert alle NULL-Eingaben. Wenn weniger als zwei Nicht-NULL-Eingaben vorhanden sind, gibt diese Funktion NULL zurück.

Unterstützte Eingabetypen

FLOAT64

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

  1. DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
  2. HAVING MAX oder HAVING MIN: Schränkt die Anzahl der Zeilen ein, die die Funktion durch einen Maximal- oder Minimalwert aggregiert. Weitere Informationen finden Sie unter HAVING MAX- und HAVING MIN-Klausel.

Rückgabedatentyp

FLOAT64

VARIANCE

VARIANCE([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Beschreibung

Ein Alias von VAR_SAMP.

Mathematische Funktionen

Alle mathematischen Funktionen verhalten sich in folgender Weise:

  • Sie geben NULL zurück, wenn einer der Eingabeparameter NULL ist.
  • Sie geben NaN zurück, wenn eines der Argumente NaN ist.

ABS

ABS(X)

Beschreibung

Berechnet den absoluten Wert. Gibt einen Fehler zurück, wenn das Argument eine Ganzzahl ist und der Ausgabewert nicht als der gleiche Typ dargestellt werden kann. Dies geschieht nur mit dem größten negativen Eingabewert, der nicht positiv dargestellt werden kann. Gibt +inf für ein +/-inf-Argument zurück.

SIGN

SIGN(X)

Beschreibung

Gibt -1, 0 oder +1 für negative, Null- bzw. positive Argumente zurück. Bei Gleitkommaargumenten unterscheidet diese Funktion nicht zwischen positiv und negativ null. Gibt NaN für ein NaN-Argument zurück.

IS_INF

IS_INF(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert positiv oder negativ unendlich ist. Gibt NULL für NULL-Eingaben zurück.

IS_NAN

IS_NAN(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert ein NaN-Wert ist. Gibt NULL für NULL-Eingaben zurück.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Beschreibung

Dividiert X durch Y. Diese Funktion schlägt nie fehl. Gibt FLOAT64 zurück. Erzeugt im Gegensatz zum Divisionsoperator (/) keinen Fehler bei der Division durch null oder bei Überlauf.

Sonderfälle:

  • Wenn das Ergebnis überläuft, wird +/-inf zurückgegeben.
  • Wenn Y=0 und X=0, wird NaN zurückgegeben.
  • Wenn Y=0 und X!=0, wird +/-inf zurückgegeben.
  • Wenn X = +/-inf und Y = +/-inf, wird NaN zurückgegeben.

Das Verhalten von IEEE_DIVIDE wird in der nachfolgenden Tabelle weiter veranschaulicht.

Sonderfälle für IEEE_DIVIDE

In der folgenden Tabelle sind Sonderfälle für IEEE_DIVIDE aufgelistet:

Zähler-Datentyp (X) Nenner-Datentyp (Y) Ergebniswert
Alles außer 0 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

SQRT

SQRT(X)

Beschreibung

Berechnet die Quadratwurzel aus X. Generiert einen Fehler, wenn X kleiner als 0 ist. Gibt +inf zurück, wenn X +inf ist.

POW

POW(X, Y)

Beschreibung

Gibt den Wert X zurück, der mit Y potenziert wird. Wenn das Ergebnis unterläuft und nicht darstellbar ist, gibt die Funktion den Wert null zurück. Gibt einen Fehler zurück, wenn eine der folgenden Bedingungen zutrifft:

  • X ist ein endlicher Wert, der kleiner als 0 ist, und Y ist keine ganze Zahl.
  • X ist 0 und Y ist ein endlicher Wert, der kleiner als 0 ist.

Das Verhalten von POW() wird in der nachfolgenden Tabelle weiter veranschaulicht.

POWER

POWER(X, Y)

Beschreibung

Synonym für POW().

Sonderfälle für POW(X, Y) und POWER(X, Y)

Im Folgenden sind Sonderfälle für POW(X, Y) und POWER(X, Y) aufgeführt.

X Y POW(X, Y) oder POWER(X, Y)
1,0 Beliebiger Wert, einschließlich NaN 1,0
Beliebig, einschließlich NaN 0 1,0
-1,0 +/-inf 1,0
ABS (X) < 1 -inf +inf
ABS (X) > 1 -inf 0
ABS (X) < 1 +inf 0
ABS (X) > 1 +inf +inf
-inf Y < 0 0
-inf Y > 0 -inf, wenn Y eine ungerade Ganzzahl ist, sonst +inf
+inf Y < 0 0
+inf Y > 0 +inf

EXP

EXP(X)

Beschreibung

Potenziert e mit X, was auch als natürliche Exponentialfunktion bezeichnet wird. Bei einem Unterlauf des Ergebnisses gibt diese Funktion eine Null zurück. Erzeugt einen Fehler, wenn ein Überlauf des Ergebnisses auftritt. Wenn X +/-inf ist, gibt diese Funktion +inf oder 0 zurück.

LN

LN(X)

Beschreibung

Berechnet den natürlichen Logarithmus von X. Generiert einen Fehler, wenn X kleiner als oder gleich null ist. Wenn X +inf ist, gibt diese Funktion +inf zurück.

LOG

LOG(X [, Y])

Beschreibung

Wenn nur X vorhanden ist, ist LOG ein Synonym für LN. Falls Y ebenfalls vorhanden ist, berechnet LOG den Logarithmus von X zur Basis Y. Erzeugt in folgenden Fällen einen Fehler:

  • X ist kleiner oder gleich null.
  • Y ist 1,0.
  • Y ist kleiner oder gleich null.

Das Verhalten von LOG(X, Y) wird in der nachfolgenden Tabelle weiter veranschaulicht.

Sonderfälle für LOG(X, Y)

X Y LOG(X, Y)
-inf Beliebiger Wert NaN
Beliebiger Wert +inf NaN
+inf 0,0 Y < 1,0 -inf
+inf Y > 1,0 +inf

LOG10

LOG10(X)

Beschreibung

Ähnlich wie bei LOG, berechnet den Logarithmus aber auf Basis 10.

GREATEST

GREATEST(X1,...,XN)

Beschreibung

Gibt NULL zurück, wenn eine der Eingaben NULL ist. NaN wird zurückgegeben, wenn eine der Eingaben NaN ist. Andernfalls wird der größte Wert zwischen X1,..., XN gemäß Kleiner-als-Vergleich (<) zurückgegeben.

LEAST

LEAST(X1,...,XN)

Beschreibung

Gibt NULL zurück, wenn eine der Eingaben NULL ist. NaN wird zurückgegeben, wenn eine der Eingaben NaN ist. Andernfalls wird der kleinste Wert zwischen X1,...,XN gemäß Größer-als-Vergleich (>) zurückgegeben.

DIV

DIV(X, Y)

Beschreibung

Gibt das Ergebnis der Ganzzahldivision von X durch Y zurück. Die Division durch null gibt einen Fehler zurück. Division durch -1 kann überlaufen. Mögliche Ergebnistypen finden Sie in der Tabelle unten.

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Beschreibung

Entspricht dem Divisionsoperator (/), gibt jedoch NULL zurück, wenn ein Fehler auftritt, beispielsweise bei einer Division durch null.

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Beschreibung

Entspricht dem Multiplikationsoperator (*), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

SAFE_NEGATE

SAFE_NEGATE(X)

Beschreibung

Entspricht dem Unäres-Minus-Operator (-), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

SAFE_ADD

SAFE_ADD(X, Y)

Beschreibung

Entspricht dem Additionsoperator (+), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Beschreibung

Entspricht dem Subtraktionsoperator (-), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

MOD

MOD(X, Y)

Beschreibung

Modulo-Funktion: gibt den Rest der Division von X durch Y zurück. Der zurückgegebene Wert hat dasselbe Vorzeichen wie X. Wenn Y gleich 0 ist, wird ein Fehler ausgegeben. Siehe nachfolgende Tabelle für mögliche Ergebnistypen.

ROUND

ROUND(X [, N])

Beschreibung

Wenn nur X vorhanden ist, rundet ROUND X auf die nächste Ganzzahl. Wenn N vorhanden ist, rundet ROUND X auf N-Dezimalstellen nach dem Dezimalzeichen. Wenn N negativ ist, rundet ROUND die Ziffern links vom Dezimalzeichen ab. Rundet halbe Zahlen von null weg. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

TRUNC

TRUNC(X [, N])

Beschreibung

Wenn nur X vorhanden ist, rundet TRUNC X auf die nächste Ganzzahl, deren absoluter Wert nicht größer als der absolute Wert von X ist. Wenn N ebenfalls vorhanden ist, verhält sich TRUNC wie ROUND(X, N), rundet aber immer gegen null und läuft nie über.

CEIL

CEIL(X)

Beschreibung

Gibt den kleinsten Integralwert (mit FLOAT64-Typ) zurück, der nicht kleiner als X ist.

CEILING

CEILING(X)

Beschreibung

Synonym von CEIL(X)

FLOOR

FLOOR(X)

Beschreibung

Gibt den größten Integralwert (mit FLOAT64-Typ) zurück, der nicht größer als X ist.

Beispiel für Verhalten der Rundungsfunktion

Beispiel für das Verhalten der Rundungsfunktionen in der Cloud Spanner SQL:

Eingabe "X" ROUND(X) TRUNC(X) CEIL(X) FLOOR(X)
2,0 2,0 2,0 2,0 2,0
2,3 2,0 2,0 3,0 2,0
2,8 3,0 2,0 3,0 2,0
2,5 3,0 2,0 3,0 2,0
-2,3 -2,0 -2,0 -2,0 -3,0
-2,8 -3,0 -2,0 -2,0 -3,0
-2,5 -3,0 -2,0 -2,0 -3,0
0 0 0 0 0
+/-inf +/-inf +/-inf +/-inf +/-inf
NaN NaN NaN NaN NaN

COS

COS(X)

Beschreibung

Berechnet den Kosinus von X, wobei X als Radiant angegeben wird. Schlägt niemals fehl.

COSH

COSH(X)

Beschreibung

Berechnet den hyperbolischen Kosinus von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

ACOS

ACOS(X)

Beschreibung

Berechnet den Hauptwert des inversen Kosinus von X. Der zurückgegebene Wert liegt im Bereich [0,π]. Erzeugt einen Fehler, wenn X ein Wert außerhalb des Bereichs [-1, 1] ist.

ACOSH

ACOSH(X)

Beschreibung

Berechnet den inversen hyperbolischen Kosinus von X. Erzeugt einen Fehler, wenn X ein Wert kleiner als 1 ist.

SIN

SIN(X)

Beschreibung

Berechnet den Sinus von X, wobei X als Radiant angegeben wird. Schlägt niemals fehl.

SINH

SINH(X)

Beschreibung

Berechnet den hyperbolischen Sinus von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

ASIN

ASIN(X)

Beschreibung

Berechnet den Hauptwert des inversen Sinus von X. Der zurückgegebene Wert liegt im Bereich [-π/2,π/2]. Erzeugt einen Fehler, wenn X außerhalb des Bereichs [-1, 1] liegt.

ASINH

ASINH(X)

Beschreibung

Berechnet den inversen hyperbolischen Sinus von X. Schlägt nie fehl.

TAN

TAN(X)

Beschreibung

Berechnet den Tangens von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn das Ergebnis überläuft.

TANH

TANH(X)

Beschreibung

Berechnet den hyperbolischen Tangens von X, wobei X als Radiant angegeben wird. Schlägt nie fehl.

ATAN

ATAN(X)

Beschreibung

Berechnet den Hauptwert des inversen Tangens von X. Der zurückgegebene Wert liegt im Bereich [-π/2,π/2]. Schlägt nie fehl.

ATANH

ATANH(X)

Beschreibung

Berechnet den inversen hyperbolischen Tangens von X. Erzeugt einen Fehler, wenn X außerhalb des Bereichs [-1, 1] liegt.

ATAN2

ATAN2(Y, X)

Beschreibung

Berechnet den Hauptwert des inversen Tangens von Y/X unter Verwendung der Vorzeichen der beiden Argumente, um den Quadranten zu bestimmen. Der zurückgegebene Wert liegt im Bereich [-π, π]. Das Verhalten dieser Funktion wird in nachfolgender Tabelle weiter veranschaulicht.

Sonderfälle für ATAN2()

Y X ATAN2(Y, X)
NaN Beliebiger Wert NaN
Beliebiger Wert NaN NaN
0 0 0, π oder -π, je nach Vorzeichen von X und Y
Endlicher Wert -inf π oder -π, je nach Vorzeichen von Y
Endlicher Wert +inf 0
+/-inf Endlicher Wert π/2 oder -π/2, je nach Vorzeichen von Y
+/-inf -inf ¾π oder -¾π, je nach Vorzeichen von Y
+/-inf +inf π/4 oder -π/4, je nach Vorzeichen von Y

Sonderfälle für trigonometrische und hyperbolische Rundungsfunktionen

X COS(X) COSH(X) ACOS(X) ACOSH(X) SIN(X) SINH(X) ASIN(X) ASINH(X) TAN(X) TANH(X) ATAN(X) ATANH(X)
+/-inf NaN =+inf NaN =+inf NaN =+inf NaN =+inf NaN =+1,0 π/2 NaN
-inf NaN =+inf NaN NaN NaN -inf NaN -inf NaN -1,0 -π/2 NaN
NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN

Hash-Funktionen

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

Beschreibung

Berechnet den Fingerabdruck der STRING- oder BYTES-Eingabe mit der Funktion Fingerprint64 aus der Open-Source-Bibliothek "FarmHash". Die Ausgabe dieser Funktion für eine bestimmte Eingabe ändert sich nie.

Rückgabetyp

INT64

Beispiele

WITH example AS (
  SELECT 1 AS x, "foo" AS y, true AS z UNION ALL
  SELECT 2 AS x, "apple" AS y, false AS z UNION ALL
  SELECT 3 AS x, "" AS y, true AS z
)
SELECT
  *,
  FARM_FINGERPRINT(CONCAT(CAST(x AS STRING), y, CAST(z AS STRING)))
    AS row_fingerprint
FROM example;
+---+-------+-------+----------------------+
| x | y     | z     | row_fingerprint      |
+---+-------+-------+----------------------+
| 1 | foo   | true  | -1541654101129638711 |
| 2 | apple | false | 2794438866806483259  |
| 3 |       | true  | -4880158226897771312 |
+---+-------+-------+----------------------+

SHA1

SHA1(input)

Beschreibung

Berechnet den Hash der Eingabe mit dem SHA-1-Algorithmus. Die Eingabe kann STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Bytes.

Diese Funktion gibt 20 Bytes zurück.

Rückgabetyp

BYTES

Beispiel

SELECT SHA1("Hello World") as sha1;

-- Note that the result of SHA1 is of type BYTES, displayed as a base64-encoded string.
+------------------------------+
| sha1                         |
+------------------------------+
| Ck1VqNd45QIvq3AZd8XYQLvEhtA= |
+------------------------------+

SHA256

SHA256(input)

Beschreibung

Berechnet den Hash der Eingabe mit dem SHA-256-Algorithmus. Die Eingabe kann STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Bytes.

Diese Funktion gibt 32 Bytes zurück.

Rückgabetyp

BYTES

Beispiel

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

Beschreibung

Berechnet den Hash der Eingabe mit dem SHA-512-Algorithmus. Die Eingabe kann STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Bytes.

Diese Funktion gibt 64 Bytes zurück.

Rückgabetyp

BYTES

Beispiel

SELECT SHA512("Hello World") as sha512;

Stringfunktionen

Diese Stringfunktionen funktionieren mit zwei verschiedenen Werten: STRING- und BYTES-Datentypen. STRING-Werte müssen korrekt in UTF-8 formatiert sein.

Funktionen, die Positionswerte wie STRPOS zurückgeben, codieren diese Positionen als INT64. Der Wert 1 bezieht sich auf das erste Zeichen (oder Byte), 2 bezieht sich auf das zweite und so weiter. Der Wert 0 gibt einen ungültigen Index an. Bei der Bearbeitung von STRING-Typen beziehen sich die zurückgegebenen Positionen auf Zeichenpositionen.

Alle Stringvergleiche werden von Byte zu Byte durchgeführt, ohne Rücksicht auf kanonische Äquivalenz von Unicode.

BYTE_LENGTH

BYTE_LENGTH(value)

Beschreibung

Gibt die Länge des Werts in Bytes zurück, unabhängig davon, ob der Typ des Werts STRING oder BYTES ist.

Rückgabetyp

INT64

Beispiele


WITH example AS
  (SELECT "абвгд" AS characters, b"абвгд" AS bytes)

SELECT
  characters,
  BYTE_LENGTH(characters) AS string_example,
  bytes,
  BYTE_LENGTH(bytes) AS bytes_example
FROM example;

+------------+----------------+-------+---------------+
| characters | string_example | bytes | bytes_example |
+------------+----------------+-------+---------------+
| абвгд      | 10             | абвгд | 10            |
+------------+----------------+-------+---------------+

CHAR_LENGTH

CHAR_LENGTH(value)

Beschreibung

Gibt die Länge des Strings in Zeichen zurück.

Rückgabetyp

INT64

Beispiele


WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHAR_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

Beschreibung

Synonym für CHAR_LENGTH.

Rückgabetyp

INT64

Beispiele


WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHARACTER_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

Beschreibung

Nimmt ein Array von erweiterten ASCII-Codepunkten (ARRAY von INT64) und gibt BYTES zurück.

Informationen zum Umwandeln von BYTES in ein Array von Codepunkten finden Sie unter TO_CODE_POINTS.

Rückgabetyp

BYTES

Beispiele

Nachfolgend ein einfaches Beispiel mit CODE_POINTS_TO_BYTES.

SELECT CODE_POINTS_TO_BYTES([65, 98, 67, 100]) AS bytes;

+-------+
| bytes |
+-------+
| AbCd  |
+-------+

Im folgendem Beispiel wird ein String mit dem ROT13-Algorithmus (Rotiere um 13 Stellen) codiert.

SELECT CODE_POINTS_TO_BYTES(ARRAY(
  (SELECT
      CASE
        WHEN chr BETWEEN b'a' AND b'z'
          THEN TO_CODE_POINTS(b'a')[offset(0)] +
            MOD(code + 13 - TO_CODE_POINTS(b'a')[offset(0)],26)
        WHEN chr BETWEEN b'A' AND b'Z'
          THEN TO_CODE_POINTS(b'A')[offset(0)] +
            MOD(code + 13 - TO_CODE_POINTS(b'A')[offset(0)],26)
        ELSE code
      END
   FROM
     (SELECT code, CODE_POINTS_TO_BYTES(ARRAY[code]) AS chr
      FROM UNNEST(TO_CODE_POINTS(input)) AS code WITH OFFSET
      ORDER BY OFFSET)
   ))) AS encoded_string
FROM UNNEST(ARRAY['Test String!']) AS input;

+----------------+
| encoded_string |
+----------------+
| Grfg Fgevat!   |
+----------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Beschreibung

Nimmt ein Array von Unicode-Codepunkten (ARRAY von INT64) und gibt einen STRING zurück.

Informationen zum Umwandeln eines Strings in ein Array von Codepunkten finden Sie unter TO_CODE_POINTS.

Rückgabetyp

STRING

Beispiel

Ein einfaches Beispiel mit CODE_POINTS_TO_STRING:

SELECT CODE_POINTS_TO_STRING([65, 255, 513, 1024]) AS string;

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+

Häufigkeit der Buchstaben in einer Gruppe von Wörtern berechnen:

WITH Words AS (
  SELECT word
  FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word
)
SELECT
  CODE_POINTS_TO_STRING([code_point]) AS letter,
  COUNT(*) AS letter_count
FROM Words,
  UNNEST(TO_CODE_POINTS(word)) AS code_point
GROUP BY 1
ORDER BY 2 DESC;

+--------+--------------+
| letter | letter_count |
+--------+--------------+
| a      | 5            |
| f      | 3            |
| r      | 2            |
| b      | 2            |
| l      | 2            |
| o      | 2            |
| g      | 1            |
| z      | 1            |
| e      | 1            |
| m      | 1            |
| i      | 1            |
+--------+--------------+

CONCAT

CONCAT(value1[, ...])

Beschreibung

Verkettet einen oder mehrere STRING oder BYTE zu einem einzelnen Ergebnis.

Die Funktion gibt NULL zurück, wenn eines der Eingabeargumente NULL ist.

Rückgabetyp

STRING oder BYTES

Beispiele

SELECT CONCAT("T.P.", " ", "Bar") as author;

+---------------------+
| author              |
+---------------------+
| T.P. Bar            |
+---------------------+

With Employees AS
  (SELECT
    "John" AS first_name,
    "Doe" AS last_name
  UNION ALL
  SELECT
    "Jane" AS first_name,
    "Smith" AS last_name
  UNION ALL
  SELECT
    "Joe" AS first_name,
    "Jackson" AS last_name)

SELECT
  CONCAT(first_name, " ", last_name)
  AS full_name
FROM Employees;

+---------------------+
| full_name           |
+---------------------+
| John Doe            |
| Jane Smith          |
| Joe Jackson         |
+---------------------+

ENDS_WITH

ENDS_WITH(value1, value2)

Beschreibung

Nimmt zwei Werte an. Gibt TRUE zurück, wenn der zweite Wert ein Suffix des ersten Werts ist.

Rückgabetyp

BOOL

Beispiele


WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  ENDS_WITH(item, "e") as example
FROM items;

+---------+
| example |
+---------+
|    True |
|   False |
|    True |
+---------+

FORMAT

Cloud Spanner SQL unterstützt eine FORMAT()-Funktion zum Formatieren von Strings. Diese Funktion entspricht der C-Funktion printf. Sie erzeugt einen STRING aus einem Formatstring, der null oder mehrere Formatspezifizierer enthält, zusammen mit einer Variablenlängenliste mit zusätzlichen Argumenten, die mit den Formatspezifizierern übereinstimmen. Hier einige Beispiele:

Beschreibung Anweisung Ergebnis
Einfache Ganzzahl FORMAT("%d", 10) 10
Ganzzahl mit Leerzeichenausgleich links FORMAT("|%10d|", 11) |           11|
Ganzzahl mit aufgefüllten Nullen links FORMAT("+%010d+", 12) +0000000012+
Ganzzahl mit Kommas FORMAT("%'d", 123456789) 123,456,789
STRING FORMAT("-%s-", 'abcd efg') -abcd efg-
FLOAT64 FORMAT("%f %E", 1.1, 2.2) 1.100000 2.200000E+00
DATE FORMAT("%t", date "2015-09-01") 2015-09-01
TIMESTAMP FORMAT("%t", timestamp "2015-09-01 12:34:56 America/Los_Angeles") 2015‑09‑01 19:34:56+00

Die Funktion FORMAT() bietet weder eine vollständig anpassbare Formatierung für alle Typen und Werte noch eine sprachsensitive Formatierung.

Wenn eine benutzerdefinierte Formatierung für einen Typ erforderlich ist, müssen Sie ihn zuerst mit typspezifischen Formatfunktionen wie FORMAT_DATE() oder FORMAT_TIMESTAMP() formatieren. Beispiel:

SELECT FORMAT("date: %s!", FORMAT_DATE("%B %d, %Y", date '2015-01-02'));

Rückgabe:

date: January 02, 2015!

Syntax

Die Syntax FORMAT() nimmt einen Formatstring sowie eine Argumentliste mit variabler Länge an und gibt ein STRING-Ergebnis zurück:

FORMAT(<format_string>, ...)

Der Ausdruck <format_string> kann null oder mehr Formatspezifizierer enthalten. Jeder Formatspezifizierer wird durch das %-Zeichen eingeführt und muss einem oder mehreren der übrigen Argumente zugeordnet werden. Zum größten Teil ist dies eine Eins-zu-Eins-Zuordnung, außer wenn der *-Spezifizierer vorhanden ist. Zum Beispiel ist %.*i zwei Argumenten zugeordnet – einem Längenargument und einem signierten Ganzzahlenargument. Wenn die Anzahl der Argumente, die sich auf die Formatspezifizierer beziehen, nicht mit der Anzahl der Argumente übereinstimmt, tritt ein Fehler auf.

Unterstützte Formatspezifizierer

Der Formatspezifizierer der Funktion FORMAT() folgt diesem Prototyp:

%[flags][width][.precision]specifier

Die unterstützten Formatspezifizierer sind in der folgenden Tabelle aufgeführt. Abweichungen von printf() sind kursiv gekennzeichnet.

Spezifizierer Beschreibung Beispiele Typen
d oder i Ganze Dezimalzahl 392 INT64
o Oktalzahl 610
INT64*
x Hexadezimale Ganzzahl 7fa
INT64*
X Hexadezimale Ganzzahl (Großbuchstaben) 7FA
INT64*
f Dezimalschreibweise: [-](Ganzzahl).(Bruchteil) für endliche Werte, in Kleinbuchstaben für nicht endliche Werte 392,650000
unendl.
nan

FLOAT64
F Dezimalschreibweise in [-](Ganzzahl),(Bruchteil) für endliche Werte und in Großbuchstaben für nicht endliche Werte 392,650000
UNENDL.
NAN

FLOAT64
e Exponentialschreibweise (Mantisse/Exponent), Kleinbuchstaben 3,926500e+02
unendl.
nan

FLOAT64
E Exponentialschreibweise (Mantisse/Exponent), Großbuchstaben 3,926500E+02
UNENDL.
NAN

FLOAT64
g Entweder Dezimalschreibweise oder wissenschaftliche Schreibweise, abhängig vom Exponenten des Eingabewerts und der angegebenen Genauigkeit. Kleinschreibung. Weitere Informationen finden Sie unter %g- und %G-Verhalten. 392.65
3.9265e+07
inf
nan

FLOAT64
G Entweder Dezimalschreibweise oder wissenschaftliche Schreibweise, abhängig vom Exponenten des Eingabewerts und der angegebenen Genauigkeit. Großschreibung. Weitere Informationen finden Sie unter %g- und %G-Verhalten. 392.65
3.9265E+07
INF
NAN

FLOAT64
s String Beispiel STRING
t Gibt einen druckbaren String zurück, der den Wert darstellt. Ähnelt häufig der Umwandlung des Arguments in STRING. Informationen dazu finden Sie unter %t- und %T-Verhalten. Beispiel
01.01.2014
<beliebig>
T Generiert einen String, der eine gültige Cloud Spanner SQL-Konstante mit dem gleichen Typ wie der Typ des Werts ist (eventuell größer oder ein String). Informationen finden Sie unter Verhalten von %t und %T. 'Beispiel'
b'bytes-Beispiel'
1234
2,3
Datum '01.01.2014'
<beliebig>
% '%%' erzeugt ein einziges '%' %

* Die Spezifizierer %o, %x und %X geben bei negativen Werten einen Fehler aus.

Der Formatspezifizierer kann optional die oben identifizierten Unterspezifizierer im Spezifiziererprototyp enthalten.

Diese Unterspezifizierer müssen folgenden Spezifikationen entsprechen.

Kennzeichnungen
Kennzeichnungen Beschreibung
- Linksbündig innerhalb der vorgegebenen Feldbreite; rechtsbündig ist die Voreinstellung (siehe Unterspezifizierer für die Breite).
+ Erzwingt, dass dem Ergebnis auch bei positiven Zahlen ein Plus- oder Minuszeichen (+ oder -) vorangestellt wird. Standardmäßig werden nur negative Zahlen mit dem Vorzeichen - versehen.
<Leerzeichen> Wird kein Vorzeichen geschrieben, wird vor dem Wert ein Leerzeichen eingefügt.
#
  • Bei "%o", "%x" und "%X" bedeutet dieses Flag, dass dem Wert 0, 0x bzw. 0X vorangestellt wird, wenn er nicht null ist.
  • Bei "%f", "%F", "%e" und "%E" bedeutet dieses Flag, dass das Dezimalzeichen auch dann hinzugefügt wird, wenn kein Bruchteil vorhanden ist, es sei denn, der Wert ist nicht endlich.
  • Bei "%g" und "%G" bedeutet dieses Flag, dass das Dezimalzeichen auch dann hinzugefügt wird, wenn kein Bruchteil vorhanden ist, es sei denn, der Wert ist nicht endlich. Die nachlaufenden Nullen nach dem Dezimalzeichen werden nie entfernt.
0 Füllt die Zahl links mit Nullen (0) statt mit Leerzeichen (0) auf, wenn das Auffüllen spezifiziert ist (siehe Unterspezifizierer für die Breite).
'

Formatiert Ganzzahlen mit dem passenden Gruppierungszeichen. Beispiel:

  • FORMAT("%'d", 12345678) gibt 12,345,678 zurück
  • FORMAT("%'x", 12345678) gibt bc:614e zurück
  • FORMAT("%'o", 55555) gibt 15,4403 zurück
  • Dieses Flag spielt nur für Dezimal-, Hexadezimal- und Oktalwerte eine Rolle.

Flags können in beliebiger Reihenfolge angegeben werden. Doppelte Flags sind kein Fehler. Wenn Flags für einen Elementtyp nicht relevant sind, werden sie ignoriert.

Breite
Breite Beschreibung
<Anzahl> Mindestanzahl der zu druckenden Zeichen. Wenn der zu druckende Wert kürzer als diese Zahl ist, wird das Ergebnis mit Leerzeichen aufgefüllt. Der Wert wird nicht abgeschnitten, auch wenn das Ergebnis größer ist.
* Die Breite wird im Formatstring nicht angegeben, sondern als zusätzliches Ganzzahlwert-Argument vor dem Argument, das formatiert werden muss.
Präzision
Präzision Beschreibung
.<Anzahl>
  • Für die Ganzzahlspezifizierer "%d", "% i", "%o", "%u", "%x" und "%X": Die Genauigkeit gibt die Mindestanzahl der zu schreibenden Ziffern an. Wenn der zu schreibende Wert kürzer als diese Zahl ist, wird das Ergebnis mit nachlaufenden Nullen aufgefüllt. Der Wert wird nicht abgeschnitten, auch wenn das Ergebnis länger ist. Eine Genauigkeit von 0 bedeutet, dass kein Zeichen für den Wert 0 geschrieben wird.
  • Für die Spezifizierer "%a", "%A", "%e", "%E", "%f" und "%F": Dies ist die Anzahl der Ziffern, die nach dem Dezimalzeichen ausgegeben werden sollen. Der Standardwert ist 6.
  • Für die Spezifizierer "%g" und "%G": Das ist die Anzahl von signifikanten Ziffern, die ausgegeben werden sollen, bevor die nachlaufenden Nullen nach dem Dezimalzeichen entfernt werden. Der Standardwert ist 6.
.* Die Präzision wird im Formatstring nicht angegeben, sondern als zusätzliches Ganzzahlwertargument dem Argument, das formatiert werden muss, vorangestellt.

Verhalten von %g und %G

Die Formatspezifizierer %g und %G wenden entweder die Dezimalschreibweise (z. B. %f und %F) oder die wissenschaftliche Schreibweise (z. B. %e und %E) an. Dies ist abhängig vom Exponenten des Eingabewerts und der angegebenen Präzision.

Übernehmen Sie p für die angegebene Genauigkeit. Der Standardwert ist 6, und 1, wenn die angegebene Genauigkeit kleiner als 1 ist. Der Eingabewert wird zuerst in die wissenschaftliche Schreibweise mit der Präzision = (p - 1) umgewandelt. Wenn der resultierende Exponentenanteil x kleiner als -4 oder nicht kleiner als p ist, wird die wissenschaftliche Schreibweise mit der Präzision = (p - 1) verwendet. Andernfalls wird die Dezimalschreibweise mit der Präzision = (p - 1 - x) verwendet.

Sofern kein #-Flag vorhanden ist, werden die nachlaufenden Nullen nach dem Dezimalzeichen entfernt. Das Dezimalzeichen wird ebenfalls entfernt, wenn ihm keine Ziffer folgt.

%t- und %T-Verhalten

Die Formatspezifizierer %t und %T werden für alle Typen definiert. widht, precision und flags funktionieren wie bei %s. width ist die Mindestbreite und der STRING wird auf diese Größe aufgefüllt. precision ist die maximale Breite des Inhalts, der angezeigt werden soll, und der STRING wird vor dem Auffüllen auf die Breite auf diese Größe gekürzt.

Der Spezifizierer %t ist immer eine lesbare Form des Werts.

Der Spezifizierer %T ist immer ein gültiges SQL-Literal eines ähnlichen Typs, z. B. ein breiterer numerischer Typ. Das Literal enthält keine Umwandlungen und keinen Typnamen, mit Ausnahme des Sonderfalls von nicht endlichen Gleitkommazahlenwerten.

Der STRING wird so formatiert:

Typ %t %T
NULL eines beliebigen Typs NULL NULL
INT64
123 123
FLOAT64 123,0 (immer mit ,0)
123e+10
inf
-inf
NaN
123,0 (immer mit ,0)
123e+10
CAST("inf" AS <Typ>)
CAST("-inf" AS <Typ>)
CAST("nan" AS <Typ>)
STRING Stringwert ohne Anführungszeichen String-Literal mit Anführungszeichen
BYTES Escape-Byte ohne Anführungszeichen
z. B. abc\x01\x02
Byte-Literal mit Anführungszeichen
z. B. b"abc\x01\x02"
DATE 03.02.2011 DATE "03.02.2011"
TIMESTAMP 03.02.2011 04:05:06+00 TIMESTAMP "03.02.2011 04:05:06+00"
ARRAY [Wert, Wert, ...]
wobei Werte mit %t formatiert sind
[Wert, Wert, ...]
wobei Werte mit %T formatiert sind

Fehlerbedingungen

Wenn ein Formatspezifizierer ungültig ist oder nicht mit dem zugehörigen Argumenttyp kompatibel ist oder die falsche Nummer oder die falschen Argumente bereitgestellt werden, wird ein Fehler erzeugt. Die folgenden <format_string>-Ausdrücke sind beispielsweise ungültig:

FORMAT('%s', 1)
FORMAT('%')

NULL-Argument-Behandlung

Ein NULL-Formatstring führt zu einem NULL-Ausgabe-STRING. Alle anderen Argumente werden in diesem Fall ignoriert.

Die Funktion erzeugt generell einen NULL-Wert, wenn ein NULL-Argument vorhanden ist. Beispielsweise erzeugt FORMAT('%i', <NULL expression>) einen NULL-STRING als Ausgabe.

Allerdings gibt es einige Ausnahmen: Wenn der Format-Spezifizierer %t oder %T ist (beide erzeugen STRINGs, die effektiv mit CAST und Literalwertsemantik übereinstimmen), erzeugt ein NULL-Wert 'NULL' (ohne die Anführungszeichen) im Ergebnis STRING. Ein Beispiel: Die Funktion

FORMAT('00-%t-00', <NULL expression>);

Rückgabe:

00-NULL-00

Zusätzliche semantische Regeln

FLOAT64-Werte können +/-inf oder NaN sein. Wenn ein Argument einen dieser Werte aufweist, ist das Ergebnis der Formatspezifizierer %f, %F, %e, %E, %g, %G und %t gleich inf, -inf oder nan (oder dasselbe in Großbuchstaben), soweit zutreffend. Dies steht im Einklang damit, wie Cloud Spanner SQL diese Werte in STRING umwandelt. Für %T gibt Cloud Spanner SQL Strings in Anführungszeichen für FLOAT64-Werte zurück, für die keine Nicht-String-Literaldarstellung vorhanden ist.

FROM_BASE64

FROM_BASE64(string_expr)

Beschreibung

Wandelt die base64-codierte Eingabe string_expr in das BYTES-Format um. BYTES kann mithilfe von TO_BASE64 in einen base64-codierten STRING umgewandelt werden.

Rückgabetyp

BYTES

Beispiel

SELECT FROM_BASE64('3q2+7w==') AS byte_data;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| 3q2+7w==  |
+-----------+

FROM_HEX

FROM_HEX(string)

Beschreibung

Wandelt einen hexadezimal codierten STRING in das BYTES-Format um. Gibt einen Fehler zurück, wenn der Eingabe-STRING Zeichen außerhalb des Bereichs (0..9, A..F, a..f) enthält. Die Groß-/Kleinschreibung der Zeichen spielt keine Rolle. Wenn der Eingabe-STRING eine ungerade Anzahl von Zeichen hat, verhält sich die Funktion so, als hätte die Eingabe eine zusätzliche führende 0. BYTES kann mithilfe von TO_HEX in einen hexadezimal codierten STRING umgewandelt werden.

Rückgabetyp

BYTES

Beispiel

WITH Input AS (
  SELECT '00010203aaeeefff' AS hex_str UNION ALL
  SELECT '0AF' UNION ALL
  SELECT '666f6f626172'
)
SELECT hex_str, FROM_HEX(hex_str) AS bytes_str
FROM Input;

-- Note that the result of FROM_HEX is of type BYTES, displayed as a base64-encoded string.
+------------------+--------------+
| hex_str          | bytes_str    |
+------------------+--------------+
| 0AF              | AAECA6ru7/8= |
| 00010203aaeeefff | AK8=         |
| 666f6f626172     | Zm9vYmFy     |
+------------------+--------------+

LENGTH

LENGTH(value)

Beschreibung

Gibt die Länge des Werts zurück. Der Wert wird für STRING-Argumente in Zeichen und für das BYTES-Argument in Byte zurückgegeben.

Rückgabetyp

INT64

Beispiele


WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  LENGTH(characters) AS string_example,
  LENGTH(CAST(characters AS BYTES)) AS bytes_example
FROM example;

+------------+----------------+---------------+
| characters | string_example | bytes_example |
+------------+----------------+---------------+
| абвгд      |              5 |            10 |
+------------+----------------+---------------+

LPAD

LPAD(original_value, return_length[, pattern])

Beschreibung

Gibt einen Wert zurück, der aus original_value mit vorangestelltem pattern besteht. return_length ist ein INT64-Wert, der die Länge des zurückgegebenen Werts angibt. Wenn original_value ein BYTES-Wert ist, dann ist return_length die Anzahl der Bytes. Wenn original_value ein STRING-Wert ist, dann ist return_length die Anzahl der Zeichen.

Der Standardwert von pattern ist ein Leerzeichen.

original_value und pattern müssen denselben Datentyp haben.

Wenn return_length kleiner oder gleich der Länge von original_value ist, gibt diese Funktion den Wert von original_value zurück, gekürzt auf den Wert von return_length. Beispiel: LPAD("hello world", 7); gibt "hello w" zurück.

Wenn original_value, return_length oder pattern NULL ist, gibt diese Funktion NULL zurück.

Diese Funktion gibt einen Fehler zurück, wenn:

  • return_length negativ ist
  • pattern leer ist

Rückgabetyp

STRING oder BYTES

Beispiele

SELECT t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);
t Länge LPAD
abc 5 "  abc"
abc 2 "ab"
例子 4 "  例子"
SELECT t, len, pattern, FORMAT("%T", LPAD(t, len, pattern)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);
t Länge Muster LPAD
abc 8 def "defdeabc"
abc 5 "--abc"
例子 5 中文 "中文中例子"
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);
t Länge LPAD
b"abc" 5 b"  abc"
b"abc" 2 b"ab"
b"\xab\xcd\xef" 4 b" \xab\xcd\xef"
SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", LPAD(t, len, pattern)) AS LPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);
t Länge Muster LPAD
b"abc" 8 b"def" b"defdeabc"
b"abc" 5 b"-" b"--abc"
b"\xab\xcd\xef" 5 b"\x00" b"\x00\x00\xab\xcd\xef"

LOWER

LOWER(value)

Beschreibung

Bei STRING-Argumenten wird der Originalstring mit allen alphabetischen Zeichen in Kleinbuchstaben zurückgegeben. Die Zuordnung zwischen Klein- und Großbuchstaben erfolgt nach der Unicode-Zeichendatenbank, ohne dabei sprachspezifische Zuordnungen zu berücksichtigen.

Bei BYTES-Argumenten wird das Argument als ASCII-Text behandelt, wobei alle Byte größer als 127 intakt bleiben.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT
    "FOO" as item
  UNION ALL
  SELECT
    "BAR" as item
  UNION ALL
  SELECT
    "BAZ" as item)

SELECT
  LOWER(item) AS example
FROM items;

+---------+
| example |
+---------+
| foo     |
| bar     |
| baz     |
+---------+

LTRIM

LTRIM(value1[, value2])

Beschreibung

Identisch mit TRIM, es werden jedoch nur vorangestellte Zeichen entfernt.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", LTRIM(item), "#") as example
FROM items;

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  LTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  LTRIM(item, "xyz") as example
FROM items;

+-----------+
| example   |
+-----------+
| applexxx  |
| bananayyy |
| orangezzz |
| pearxyz   |
+-----------+

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regexp)

Beschreibung

Gibt TRUE zurück, wenn value eine partielle Übereinstimmung mit dem regulären Ausdruck regexp darstellt.

Wenn das Argument regexp ungültig ist, gibt die Funktion einen Fehler zurück.

Sie können auch nach einer vollständigen Übereinstimmung suchen. Dazu verwenden Sie ^ (Anfang des Textes) und $ (Ende des Textes). Aufgrund der Rangfolge der Operatoren für reguläre Ausdrücke empfehlen sich Klammern um alles zwischen ^ und $.

Rückgabetyp

BOOL

Beispiele

SELECT
  email,
  REGEXP_CONTAINS(email, r"@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+") AS is_valid
FROM
  (SELECT
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| foo@example.com | true     |
| bar@example.org | true     |
| www.example.net | false    |
+-----------------+----------+

# Performs a full match, using ^ and $. Due to regular expression operator
# precedence, it is good practice to use parentheses around everything between ^
# and $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^([\w.+-]+@foo\.com|[\w.+-]+@bar\.org)$")
    AS valid_email_address,
  REGEXP_CONTAINS(email, r"^[\w.+-]+@foo\.com|[\w.+-]+@bar\.org$")
    AS without_parentheses
FROM
  (SELECT
    ["a@foo.com", "a@foo.computer", "b@bar.org", "!b@bar.org", "c@buz.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| a@foo.com      | true                | true                |
| a@foo.computer | false               | true                |
| b@bar.org      | true                | true                |
| !b@bar.org     | false               | true                |
| c@buz.net      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regexp)

Beschreibung

Gibt den ersten Teilstring in value zurück, der mit dem regulären Ausdruck regexp übereinstimmt. Gibt NULL zurück, wenn es keine Übereinstimmung gibt.

Wenn der reguläre Ausdruck eine Erfassungsgruppe enthält, gibt die Funktion den Teilstring zurück, der mit dieser Erfassungsgruppe übereinstimmt. Wenn der Ausdruck keine Erfassungsgruppe enthält, gibt die Funktion den gesamten übereinstimmenden Teilstring zurück.

Gibt einen Fehler zurück, wenn:

  • Der reguläre Ausdruck ungültig ist
  • Der reguläre Ausdruck mehr als eine Erfassungsgruppe aufweist

Rückgabetyp

STRING oder BYTES

Beispiele


WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+")
  AS user_name
FROM email_addresses;

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.([a-zA-Z0-9-.]+$)")
  AS top_level_domain
FROM email_addresses;

+------------------+
| top_level_domain |
+------------------+
| com              |
| org              |
| net              |
+------------------+

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regexp)

Beschreibung

Gibt ein Array aller Teilstrings von value zurück, die mit dem regulären Ausdruck regexp übereinstimmen.

Die Funktion REGEXP_EXTRACT_ALL gibt ausschließlich nicht überlappende Übereinstimmungen zurück. Wenn Sie beispielsweise diese Funktion verwenden, um ana aus banana zu extrahieren, wird nur ein Teilstring zurückgegeben, nicht zwei.

Rückgabetyp

Ein ARRAY von entweder STRINGs oder BYTES

Beispiele


WITH code_markdown AS
  (SELECT "Try `function(x)` or `function(y)`" as code)

SELECT
  REGEXP_EXTRACT_ALL(code, "`(.+?)`") AS example
FROM code_markdown;

+----------------------------+
| example                    |
+----------------------------+
| [function(x), function(y)] |
+----------------------------+

REGEXP_REPLACE

REGEXP_REPLACE(value, regexp, replacement)

Beschreibung

Gibt einen STRING zurück, in dem alle Teilstrings von value, die mit dem regulären Ausdruck regexp übereinstimmen, durch replacement ersetzt werden.

Sie können innerhalb des Arguments replacement Escape-Ziffern mit Backslash (\1 bis \9) verwenden, um Text einzufügen, der mit der entsprechenden Klammergruppe im regexp-Muster übereinstimmt. Verwenden Sie \0, um auf den gesamten übereinstimmenden Text zu verweisen.

Durch die Funktion REGEXP_REPLACE werden ausschließlich nicht überlappende Übereinstimmungen ersetzt. Beispielsweise führt das Ersetzen von ana in banana zu nur einer Ersetzung, nicht zwei.

Wenn das Argument regexp kein gültiger regulärer Ausdruck ist, gibt diese Funktion einen Fehler zurück.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH markdown AS
  (SELECT "# Heading" as heading
  UNION ALL
  SELECT "# Another heading" as heading)

SELECT
  REGEXP_REPLACE(heading, r"^# ([a-zA-Z0-9\s]+$)", "<h1>\\1</h1>")
  AS html
FROM markdown;

+--------------------------+
| html                     |
+--------------------------+
| <h1>Heading</h1>         |
| <h1>Another heading</h1> |
+--------------------------+

REPLACE

REPLACE(original_value, from_value, to_value)

Beschreibung

Ersetzt alle Vorkommen von from_value durch to_value in original_value. Wenn from_value leer ist, wird keine Ersetzung vorgenommen.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH desserts AS
  (SELECT "apple pie" as dessert
  UNION ALL
  SELECT "blackberry pie" as dessert
  UNION ALL
  SELECT "cherry pie" as dessert)

SELECT
  REPLACE (dessert, "pie", "cobbler") as example
FROM desserts;

+--------------------+
| example            |
+--------------------+
| apple cobbler      |
| blackberry cobbler |
| cherry cobbler     |
+--------------------+

REPEAT

REPEAT(original_value, repetitions)

Beschreibung

Gibt einen Wert zurück, der aus Wiederholungen von original_value besteht. Der Parameter repetitions gibt die Anzahl der Wiederholungen von original_value an. Gibt NULL zurück, wenn entweder original_value oder repetitions NULL ist.

Diese Funktion gibt einen Fehler zurück, wenn der Wert von repetitions negativ ist.

Rückgabetyp

STRING oder BYTES

Beispiele

SELECT t, n, REPEAT(t, n) AS REPEAT FROM UNNEST([
  STRUCT('abc' AS t, 3 AS n),
  ('例子', 2),
  ('abc', null),
  (null, 3)
]);
t n REPEAT
abc 3 abcabcabc
例子 2 例子例子
abc NULL NULL
NULL 3 NULL

REVERSE

REVERSE(value)

Beschreibung

Gibt die Umkehrung des eingegebenen STRING- oder BYTES-Werts zurück.

Rückgabetyp

STRING oder BYTES

Beispiele

WITH example AS (
  SELECT "foo" AS sample_string, b"bar" AS sample_bytes UNION ALL
  SELECT "абвгд" AS sample_string, b"123" AS sample_bytes
)
SELECT
  sample_string,
  REVERSE(sample_string) AS reverse_string,
  sample_bytes,
  REVERSE(sample_bytes) AS reverse_bytes
FROM example;

+---------------+----------------+--------------+---------------+
| sample_string | reverse_string | sample_bytes | reverse_bytes |
+---------------+----------------+--------------+---------------+
| foo           | oof            | bar          | rab           |
| абвгд         | дгвба          | 123          | 321           |
+---------------+----------------+--------------+---------------+

RPAD

RPAD(original_value, return_length[, pattern])

Beschreibung

Gibt einen Wert zurück, der aus original_value mit angehängtem pattern besteht. return_length ist ein INT64-Wert, der die Länge des zurückgegebenen Werts angibt. Wenn original_value ein BYTES-Wert ist, dann ist return_length die Anzahl der Bytes. Wenn original_value ein STRING-Wert ist, dann ist return_length die Anzahl der Zeichen.

Der Standardwert von pattern ist ein Leerzeichen.

original_value und pattern müssen denselben Datentyp haben.

Wenn return_length kleiner oder gleich der Länge von original_value ist, gibt diese Funktion den Wert von original_value zurück, gekürzt auf den Wert von return_length. Beispiel: RPAD("hello world", 7); gibt "hello w" zurück.

Wenn original_value, return_length oder pattern NULL ist, gibt diese Funktion NULL zurück.

Diese Funktion gibt einen Fehler zurück, wenn:

  • return_length negativ ist
  • pattern leer ist

Rückgabetyp

STRING oder BYTES

Beispiele

SELECT t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);
t Länge RPAD
abc 5 "abc  "
abc 2 "ab"
例子 4 "例子  "
SELECT t, len, pattern, FORMAT("%T", RPAD(t, len, pattern)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);
t Länge Muster RPAD
abc 8 def "abcdefde"
abc 5 "abc--"
例子 5 中文 "例子中文中"
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);
t Länge RPAD
b"abc" 5 b"abc  "
b"abc" 2 b"ab"
b"\xab\xcd\xef" 4 b"\xab\xcd\xef "
SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", RPAD(t, len, pattern)) AS RPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);
t Länge Muster RPAD
b"abc" 8 b"def" b"abcdefde"
b"abc" 5 b"-" b"abc--"
b"\xab\xcd\xef" 5 b"\x00" b"\xab\xcd\xef\x00\x00"

RTRIM

RTRIM(value1[, value2])

Beschreibung

Identisch mit TRIM, es werden jedoch nur nachgestellte Zeichen entfernt.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  RTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+

WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

SELECT
  RTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

Beschreibung

Wandelt eine Sequenz von Byte in einen String um. Alle ungültigen UTF-8-Zeichen werden durch das Unicode-Ersatzzeichen U+FFFD ersetzt.

Rückgabetyp

STRING

Beispiele

Diese Anweisung gibt das Unicode-Ersetzungszeichen "�" zurück:

SELECT SAFE_CONVERT_BYTES_TO_STRING(b'\xc2') as safe_convert;

SPLIT

SPLIT(value[, delimiter])

Beschreibung

Teilt value mithilfe des Arguments delimiter.

Für STRING ist das Standardtrennzeichen das Komma (,).

Für BYTES müssen Sie ein Trennzeichen angeben.

Das Aufteilen mit einem leeren Trennzeichen erzeugt ein Array von UTF-8-Zeichen für STRING-Werte und ein Array von Byte für BYTES-Werte.

Das Aufteilen eines leeren STRINGs gibt ein ARRAY mit einem einzigen leeren STRING zurück.

Rückgabetyp

ARRAY vom Typ STRING oder ARRAY vom Typ BYTES

Beispiele


WITH letters AS
  (SELECT "" as letter_group
  UNION ALL
  SELECT "a" as letter_group
  UNION ALL
  SELECT "b c d" as letter_group)

SELECT SPLIT(letter_group, " ") as example
FROM letters;

+----------------------+
| example              |
+----------------------+
| []                   |
| [a]                  |
| [b, c, d]            |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

Beschreibung

Nimmt zwei Werte an. Gibt TRUE zurück, wenn der zweite Wert ein Präfix des ersten Werts ist.

Rückgabetyp

BOOL

Beispiele


WITH items AS
  (SELECT "foo" as item
  UNION ALL
  SELECT "bar" as item
  UNION ALL
  SELECT "baz" as item)

SELECT
  STARTS_WITH(item, "b") as example
FROM items;

+---------+
| example |
+---------+
|   False |
|    True |
|    True |
+---------+

STRPOS

STRPOS(string, substring)

Beschreibung

Gibt den 1-basierten Index des ersten Vorkommens von substring innerhalb von string zurück. Gibt 0 zurück, wenn substring nicht gefunden wird.

Rückgabetyp

INT64

Beispiele


WITH email_addresses AS
  (SELECT
    "foo@example.com" AS email_address
  UNION ALL
  SELECT
    "foobar@example.com" AS email_address
  UNION ALL
  SELECT
    "foobarbaz@example.com" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

SELECT
  STRPOS(email_address, "@") AS example
FROM email_addresses;

+---------+
| example |
+---------+
|       4 |
|       7 |
|      10 |
|       0 |
+---------+

SUBSTR

SUBSTR(value, position[, length])

Beschreibung

Gibt einen Teilstring des angegebenen Werts zurück. Das Argument position ist eine Ganzzahl, die die Ausgangsposition des Teilstrings angibt, wobei Position = 1 das erste Zeichen oder Byte angibt. Das Argument length ist die maximale Anzahl von Zeichen für STRING-Argumente oder die maximale Anzahl von Byte für BYTES-Argumente.

Wenn position negativ ist, zählt die Funktion ab dem Ende von value, wobei -1 das letzte Zeichen angibt.

Ist position eine Position am linken Ende des STRING (position = 0 oder position < -LENGTH(value)), beginnt die Funktion ab Position = 1. Wenn length die Länge von value überschreitet, werden weniger als die length-Zeichen zurückgegeben.

Ist length kleiner als 0, gibt die Funktion einen Fehler zurück.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2) as example
FROM items;

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2, 2) as example
FROM items;

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, -2) as example
FROM items;

+---------+
| example |
+---------+
| le      |
| na      |
| ge      |
+---------+

TO_BASE64

TO_BASE64(bytes_expr)

Beschreibung

Wandelt eine Sequenz von BYTES in einen base64-codierten STRING um. Mithilfe von FROM_BASE64 kann ein base64-codierter STRING in BYTES umgewandelt werden.

Rückgabetyp

STRING

Beispiel

SELECT TO_BASE64(b'\xde\xad\xbe\xef') AS base64_string;

+---------------+
| base64_string |
+---------------+
| 3q2+7w==      |
+---------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Beschreibung

Nimmt einen Wert an und gibt ein Array von INT64 zurück.

  • Wenn value ein STRING ist, stellt jedes Element im zurückgegebenen Array einen Codepunkt dar. Jeder Codepunkt liegt im Bereich von [0, 0xD7FF] und [0xE000, 0x10FFFF].
  • Ist value BYTES, ist jedes Element im Array ein erweiterter ASCII-Zeichenwert im Bereich von [0, 255].

Informationen zum Umwandeln eines Arrays von Codepunkten in einen STRING oder in BYTES finden Sie unter CODE_POINTS_TO_STRING bzw. CODE_POINTS_TO_BYTES.

Rückgabetyp

ARRAY von INT64

Beispiele

Das folgende Beispiel ruft die Codepunkte für jedes Element in einem Array von Wörtern ab.

SELECT word, TO_CODE_POINTS(word) AS code_points
FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word;

+---------+------------------------------------+
| word    | code_points                        |
+---------+------------------------------------+
| foo     | [102, 111, 111]                    |
| bar     | [98, 97, 114]                      |
| baz     | [98, 97, 122]                      |
| giraffe | [103, 105, 114, 97, 102, 102, 101] |
| llama   | [108, 108, 97, 109, 97]            |
+---------+------------------------------------+

Das folgende Beispiel wandelt ganzzahlige Darstellungen von BYTES in ihre entsprechenden ASCII-Zeichenwerte um.

SELECT word, TO_CODE_POINTS(word) AS bytes_value_as_integer
FROM UNNEST([b'\x00\x01\x10\xff', b'\x66\x6f\x6f']) AS word;

+------------------+------------------------+
| word             | bytes_value_as_integer |
+------------------+------------------------+
| \x00\x01\x10\xff | [0, 1, 16, 255]        |
| foo              | [102, 111, 111]        |
+------------------+------------------------+

Das folgende Beispiel zeigt den Unterschied zwischen einem BYTES-Ergebnis und einem STRING-Ergebnis.

SELECT TO_CODE_POINTS(b'Ā') AS b_result, TO_CODE_POINTS('Ā') AS s_result;

+------------+----------+
| b_result   | s_result |
+------------+----------+
| [196, 128] | [256]    |
+------------+----------+

Beachten Sie, dass das Zeichen Ā als 2-Byte-Unicode-Sequenz dargestellt wird. Deshalb gibt die BYTES-Version von TO_CODE_POINTS ein Array mit zwei Elementen zurück, während die STRING-Version ein Array mit einem einzigen Element zurückgibt.

TO_HEX

TO_HEX(bytes)

Beschreibung

Wandelt eine Sequenz von BYTES in einen hexadezimalen STRING um. Wandelt jedes Byte im STRING in zwei hexadezimale Zeichen im Bereich (0..9, a..f) um. Mithilfe von FROM_HEX kann ein hexadezimal codierter STRING in BYTES umgewandelt werden.

Rückgabetyp

STRING

Beispiel

WITH Input AS (
  SELECT b'\x00\x01\x02\x03\xAA\xEE\xEF\xFF' AS byte_str UNION ALL
  SELECT b'foobar'
)
SELECT byte_str, TO_HEX(byte_str) AS hex_str
FROM Input;

+----------------------------------+------------------+
| byte_string                      | hex_string       |
+----------------------------------+------------------+
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
| foobar                           | 666f6f626172     |
+----------------------------------+------------------+

TRIM

TRIM(value1[, value2])

Beschreibung

Entfernt alle voran- und nachgestellten Zeichen, die mit value2 übereinstimmen. Wenn value2 nicht angegeben ist, werden alle voran- und nachgestellten Leerzeichen (wie nach Unicode-Standard definiert) entfernt. Ist das erste Argument vom Typ BYTES, ist das zweite Argument erforderlich.

Wenn value2 mehr als ein Zeichen oder Byte enthält, entfernt die Funktion alle voran- oder nachgestellten Zeichen oder Byte, die in value2 enthalten sind.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", TRIM(item), "#") as example
FROM items;

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  TRIM(item, "*") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  TRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

UPPER

UPPER(value)

Beschreibung

Bei STRING-Argumenten wird der ursprüngliche String mit allen alphabetischen Zeichen in Großbuchstaben zurückgegeben. Die Zuordnung zwischen Groß- und Kleinbuchstaben erfolgt nach der Unicode-Zeichendatenbank, ohne dabei sprachspezifische Zuordnungen zu berücksichtigen.

Bei BYTES-Argumenten wird das Argument als ASCII-Text behandelt, wobei alle Byte größer als 127 intakt bleiben.

Rückgabetyp

STRING oder BYTES

Beispiele


WITH items AS
  (SELECT
    "foo" as item
  UNION ALL
  SELECT
    "bar" as item
  UNION ALL
  SELECT
    "baz" as item)

SELECT
  UPPER(item) AS example
FROM items;

+---------+
| example |
+---------+
| FOO     |
| BAR     |
| BAZ     |
+---------+

JSON-Funktionen

Cloud Spanner SQL unterstützt Funktionen, die Ihnen beim Abrufen von Daten helfen, die in JSON-formatierten Strings gespeichert sind, und beim Abrufen von Funktionen, mit denen Sie Daten in JSON-formatierte Strings umwandeln können.

JSON_QUERY oder JSON_VALUE

JSON_QUERY(json_string_expr, json_path_string_literal) gibt JSON-Werte als STRING-Werte zurück.

JSON_VALUE(json_string_expr, json_path_string_literal) gibt skalare JSON-Werte als STRING-Werte zurück.

Beschreibung

Extrahiert JSON-Werte oder JSON-Skalarwerte als Strings.

  • json_string_expr: Ein String im JSON-Format. Beispiel:

    {"class" : {"students" : [{"name" : "Jane"}]}}
    
  • json_path_string_literal: Das JSONpath-Format. Gibt den Wert oder die Werte an, die Sie aus dem JSON-formatierten String abrufen möchten. Wenn json_path_string_literal JSON null zurückgibt, wird dies in SQL NULL konvertiert.

Falls ein JSON-Schlüssel ungültige JSONPath-Zeichen verwendet, können Sie diese Zeichen mit doppelten Anführungszeichen maskieren.

Beispiele

SELECT JSON_QUERY(json_text, '$') AS json_text_string
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------------------------------------------------+
| json_text_string                                          |
+-----------------------------------------------------------+
| {"class":{"students":[{"name":"Jane"}]}}                  |
| {"class":{"students":[]}}                                 |
| {"class":{"students":[{"name":"John"},{"name":"Jamie"}]}} |
+-----------------------------------------------------------+
SELECT JSON_QUERY(json_text, '$.class.students[0]') AS first_student
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+
SELECT JSON_QUERY(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name" : null}]}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| NULL              |
| "Jamie"           |
+-------------------+
SELECT JSON_QUERY(json_text, '$.class."students"') AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+
SELECT JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

Falls ein JSON-Schlüssel ungültige JSONPath-Zeichen verwendet, können Sie diese Zeichen mit doppelten Anführungszeichen maskieren. Beispiel:

SELECT JSON_VALUE('{"a.b": {"c": "world"}}', '$."a.b".c') as hello;

+-------+
| hello |
+-------+
| world |
+-------+

JSONPath-Format

Die meisten JSON-Funktionen übergeben einen Parameter json_string_expr oder json_path_string_literal. Der Parameter json_string_expr übergibt einen JSON-formatierten String und der Parameter json_path_string_literal gibt den Wert oder die Werte an, die Sie aus dem JSON-formatierten String erhalten möchten.

Der Parameter json_string_expr muss ein JSON-String im folgenden Format sein:

{"class" : {"students" : [{"name" : "Jane"}]}}

Sie erstellen den Parameter json_path_string_literal im JSONPath-Format. Gemäß diesem Format muss der Parameter mit einem $-Zeichen beginnen, das sich auf die äußerste Ebene des JSON-formatierten Strings bezieht. Sie können untergeordnete Werte mithilfe von Punkten angeben. Wenn das JSON-Objekt ein Array ist, können Sie Klammern verwenden, um den Arrayindex anzugeben. Wenn die Schlüssel $, Punkte oder Klammern enthalten, beachten Sie die Informationen zu den einzelnen JSON-Funktionen zur Maskierung dieser Zeichen.

JSONPath Beschreibung Beispiel Ergebnis mit dem obigen json_string_expr
$ Root-Objekt oder Element "$" {"class":{"students":[{"name":"Jane"}]}}
. Untergeordneter Operator "$.class.students" [{"name":"Jane"}]
[] Tiefgestellt-Operator "$.class.students[0]" {"name":"Jane"}

Eine JSON-Funktion gibt NULL zurück, wenn der Parameter json_path_string_literal mit keinem Wert in json_string_expr übereinstimmt. Wenn der ausgewählte Wert für eine skalare Funktion nicht skalar ist, z. B. ein Objekt oder ein Array, gibt die Funktion NULL zurück.

Wenn der JSONPath-Wert ungültig ist, löst die Funktion einen Fehler aus.

Arrayfunktionen

ARRAY

ARRAY(subquery)

Beschreibung

Die Funktion ARRAY gibt ein ARRAY mit genau einem Element für jede Zeile in einer Unterabfrage zurück.

Wenn durch die subquery eine SQL-Tabelle erzeugt wird, muss die Tabelle genau eine Spalte haben. Jedes Element im Ausgabe-ARRAY ist der Wert der einzelnen Spalte einer Zeile in der Tabelle.

Einschränkungen

  • Unterabfragen sind nicht geordnet. Deshalb wird von den Elementen des Ausgabe-ARRAY die Reihenfolge in der Quelltabelle für die Unterabfrage nicht zwingend beibehalten. Wenn die Unterabfrage jedoch die Klausel ORDER BY enthält, gibt die Funktion ARRAY ein ARRAY zurück, das diese Klausel beachtet.
  • Wenn bei der Unterabfrage mehr als eine Spalte zurückgegeben wird, gibt die ARRAY-Funktion einen Fehler zurück.
  • Wenn bei der Unterabfrage eine Spalte des Typs ARRAY oder Zeilen des Typs ARRAY zurückgegeben werden, gibt die Funktion ARRAY einen Fehler zurück: Cloud Spanner SQL unterstützt keine ARRAY-Objekte mit Elementen des Typs ARRAY.
  • Wenn bei der Unterabfrage keine Zeilen zurückgegeben werden, gibt die ARRAY-Funktion ein leeres ARRAY zurück. Es wird nie ein NULL-ARRAY zurückgegeben.

Rückgabetyp

ARRAY

Beispiele

SELECT ARRAY
  (SELECT 1 UNION ALL
   SELECT 2 UNION ALL
   SELECT 3) AS new_array;

+-----------+
| new_array |
+-----------+
| [1, 2, 3] |
+-----------+

Wenn Sie ein ARRAY aus einer Unterabfrage mit mehreren Spalten erstellen möchten, ändern Sie die Unterabfrage so, dass SELECT AS STRUCT verwendet wird. Daraufhin gibt die ARRAY-Funktion ein ARRAY von STRUCTs zurück. Das ARRAY enthält ein STRUCT für jede Zeile in der Unterabfrage und jedes dieser STRUCTs enthält wiederum ein Feld für jede Spalte in dieser Zeile.

SELECT
  ARRAY
    (SELECT AS STRUCT 1, 2, 3
     UNION ALL SELECT AS STRUCT 4, 5, 6) AS new_array;

+------------------------+
| new_array              |
+------------------------+
| [{1, 2, 3}, {4, 5, 6}] |
+------------------------+

Analog können Sie zum Erstellen eines ARRAY aus einer Unterabfrage, die mindestens ein ARRAY enthält, die Unterabfrage so ändern, dass SELECT AS STRUCT verwendet wird.

SELECT ARRAY
  (SELECT AS STRUCT [1, 2, 3] UNION ALL
   SELECT AS STRUCT [4, 5, 6]) AS new_array;

+----------------------------+
| new_array                  |
+----------------------------+
| [{[1, 2, 3]}, {[4, 5, 6]}] |
+----------------------------+

ARRAY_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

Beschreibung

Verkettet eine oder mehrere Arrays mit demselben Elementtyp zu einem einzelnen Array.

Rückgabetyp

ARRAY

Beispiele

SELECT ARRAY_CONCAT([1, 2], [3, 4], [5, 6]) as count_to_six;

+--------------------------------------------------+
| count_to_six                                     |
+--------------------------------------------------+
| [1, 2, 3, 4, 5, 6]                               |
+--------------------------------------------------+

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Beschreibung

Gibt die Größe des Arrays zurück. Gibt 0 für ein leeres Array zurück. Gibt NULL zurück, wenn array_expression gleich NULL ist.

Rückgabetyp

INT64

Beispiele

WITH items AS
  (SELECT ["coffee", NULL, "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

+---------------------------------+------+
| list                            | size |
+---------------------------------+------+
| [coffee, NULL, milk]            | 3    |
| [cake, pie]                     | 2    |
+---------------------------------+------+

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

Beschreibung

Gibt eine Verkettung der Elemente in array_expression als STRING zurück. Der Wert für array_expression kann entweder ein Array von STRING- oder BYTES-Datentypen sein.

Wenn der Parameter null_text verwendet wird, ersetzt die Funktion alle NULL-Werte im Array durch den Wert von null_text.

Wird der Parameter null_text nicht verwendet, lässt die Funktion den NULL-Wert und sein vorangehendes Trennzeichen weg.

Beispiele

WITH items AS
  (SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| coffee--tea--milk              |
| cake--pie                      |
+--------------------------------+
WITH items AS
  (SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--', 'MISSING') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| coffee--tea--milk              |
| cake--pie--MISSING             |
+--------------------------------+

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

Beschreibung

Gibt ein Array von Werten zurück. Die Parameter start_expression und end_expression bestimmen den einzubeziehenden Start und das einzubeziehende Ende des Arrays.

Die Funktion GENERATE_ARRAY akzeptiert folgende Datentypen als Eingaben:

  • INT64
  • FLOAT64

Der Parameter step_expression bestimmt das Inkrement, das zum Generieren von Arraywerten verwendet wird. Der Standardwert für diesen Parameter ist 1.

Diese Funktion gibt einen Fehler zurück, wenn step_expression auf 0 festgelegt oder eine Eingabe NaN ist.

Wenn eines der Argumente NULL ist, gibt die Funktion ein NULL-Array zurück.

Rückgabedatentyp

ARRAY

Beispiele

Im folgenden Beispiel wird ein Array von Ganzzahlen mit einem Standardschritt von 1 zurückgegeben.

SELECT GENERATE_ARRAY(1, 5) AS example_array;

+-----------------+
| example_array   |
+-----------------+
| [1, 2, 3, 4, 5] |
+-----------------+

Im folgenden Beispiel wird ein Array mit einer benutzerdefinierten Schrittgröße zurückgegeben.

SELECT GENERATE_ARRAY(0, 10, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| [0, 3, 6, 9]  |
+---------------+

Im folgenden Beispiel wird ein Array mit dem negativen Wert -3 als Schrittgröße zurückgegeben.

SELECT GENERATE_ARRAY(10, 0, -3) AS example_array;

+---------------+
| example_array |
+---------------+
| [10, 7, 4, 1] |
+---------------+

Im folgenden Beispiel wird ein Array mit demselben Wert für start_expression und end_expression zurückgegeben.

SELECT GENERATE_ARRAY(4, 4, 10) AS example_array;

+---------------+
| example_array |
+---------------+
| [4]           |
+---------------+

Im folgenden Beispiel wird ein leeres Array zurückgegeben, da start_expression größer als end_expression und der Wert für step_expression positiv ist.

SELECT GENERATE_ARRAY(10, 0, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

Im folgenden Beispiel wird ein NULL-Array zurückgegeben, da end_expression gleich NULL ist.

SELECT GENERATE_ARRAY(5, NULL, 1) AS example_array;

+---------------+
| example_array |
+---------------+
| NULL          |
+---------------+

Im folgenden Beispiel werden mehrere Arrays zurückgegeben.

SELECT GENERATE_ARRAY(start, 5) AS example_array
FROM UNNEST([3, 4, 5]) AS start;

+---------------+
| example_array |
+---------------+
| [3, 4, 5]     |
| [4, 5]        |
| [5]           |
+---------------+

GENERATE_DATE_ARRAY

GENERATE_DATE_ARRAY(start_date, end_date[, INTERVAL INT64_expr date_part])

Beschreibung

Gibt ein Array von Daten zurück. Die Parameter start_date und end_date bestimmen den einzubeziehenden Start und das einzubeziehende Ende des Arrays.

Die Funktion GENERATE_DATE_ARRAY akzeptiert folgende Datentypen als Eingaben:

  • start_date muss ein DATE-Wert sein.
  • end_date muss ein DATE-Wert sein.
  • INT64_expr muss ein INT64-Wert sein.
  • date_part muss ein DAY-, WEEK-, MONTH-, QUARTER- oder YEAR-Wert sein.

Der Parameter INT64_expr bestimmt das Inkrement, das zum Generieren von Datumswerten verwendet wird. Der Standardwert für diesen Parameter ist 1 Tag.

Diese Funktion gibt einen Fehler zurück, wenn INT64_expr auf 0 festgelegt ist.

Rückgabedatentyp

Ein ARRAY mit mindestens 0 DATE-Werten.

Beispiele

Im folgenden Beispiel wird ein Array von Daten mit einem Standardschritt von 1 zurückgegeben.

SELECT GENERATE_DATE_ARRAY('2016-10-05', '2016-10-08') AS example;

+--------------------------------------------------+
| example                                          |
+--------------------------------------------------+
| [2016-10-05, 2016-10-06, 2016-10-07, 2016-10-08] |
+--------------------------------------------------+

Im folgenden Beispiel wird ein Array mit einer benutzerdefinierten Schrittgröße zurückgegeben.

SELECT GENERATE_DATE_ARRAY(
 '2016-10-05', '2016-10-09', INTERVAL 2 DAY) AS example;

+--------------------------------------+
| example                              |
+--------------------------------------+
| [2016-10-05, 2016-10-07, 2016-10-09] |
+--------------------------------------+

Im folgenden Beispiel wird ein Array mit dem negativen Wert -3 als Schrittgröße zurückgegeben.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL -3 DAY) AS example;

+--------------------------+
| example                  |
+--------------------------+
| [2016-10-05, 2016-10-02] |
+--------------------------+

Im folgenden Beispiel wird ein Array mit demselben Wert für start_date und end_date zurückgegeben.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-05', INTERVAL 8 DAY) AS example;

+--------------+
| example      |
+--------------+
| [2016-10-05] |
+--------------+

Im folgenden Beispiel wird ein leeres Array zurückgegeben, da start_date größer als end_date und der Wert für step positiv ist.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

Im folgenden Beispiel wird ein NULL-Array zurückgegeben, da eine seiner Eingaben NULL ist.

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

Im folgenden Beispiel wird ein Array von Datumswerten mit MONTH als date_part-Intervall zurückgegeben.

SELECT GENERATE_DATE_ARRAY('2016-01-01',
  '2016-12-31', INTERVAL 2 MONTH) AS example;

+--------------------------------------------------------------------------+
| example                                                                  |
+--------------------------------------------------------------------------+
| [2016-01-01, 2016-03-01, 2016-05-01, 2016-07-01, 2016-09-01, 2016-11-01] |
+--------------------------------------------------------------------------+

Im folgenden Beispiel werden nicht konstante Datumswerte zum Generieren eines Arrays verwendet.

SELECT GENERATE_DATE_ARRAY(date_start, date_end, INTERVAL 1 WEEK) AS date_range
FROM (
  SELECT DATE '2016-01-01' AS date_start, DATE '2016-01-31' AS date_end
  UNION ALL SELECT DATE "2016-04-01", DATE "2016-04-30"
  UNION ALL SELECT DATE "2016-07-01", DATE "2016-07-31"
  UNION ALL SELECT DATE "2016-10-01", DATE "2016-10-31"
) AS items;

+--------------------------------------------------------------+
| date_range                                                   |
+--------------------------------------------------------------+
| [2016-01-01, 2016-01-08, 2016-01-15, 2016-01-22, 2016-01-29] |
| [2016-04-01, 2016-04-08, 2016-04-15, 2016-04-22, 2016-04-29] |
| [2016-07-01, 2016-07-08, 2016-07-15, 2016-07-22, 2016-07-29] |
| [2016-10-01, 2016-10-08, 2016-10-15, 2016-10-22, 2016-10-29] |
+--------------------------------------------------------------+

OFFSET und ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

Beschreibung

Greift auf ein ARRAY-Element nach Position zu und gibt das Element zurück. OFFSET bedeutet, dass die Nummerierung bei null beginnt, ORDINAL bedeutet, dass die Nummerierung bei eins beginnt.

Ein bestimmtes Array kann entweder als 0-basiert oder 1-basiert interpretiert werden. Beim Zugriff auf ein Arrayelement müssen Sie die Arrayposition mit OFFSET oder ORDINAL einleiten. Es gibt kein Standardverhalten.

Sowohl OFFSET als auch ORDINAL erzeugen einen Fehler, wenn der Index außerhalb des Bereichs liegt.

Rückgabetyp

Variiert je nach den Elementen im ARRAY.

Beispiele

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM items;

+----------------------------------+-----------+-----------+
| list                             | offset_1  | ordinal_1 |
+----------------------------------+-----------+-----------+
| [apples, bananas, pears, grapes] | bananas   | apples    |
| [coffee, tea, milk]              | tea       | coffee    |
| [cake, pie]                      | pie       | cake      |
+----------------------------------+-----------+-----------+

ARRAY_REVERSE

ARRAY_REVERSE(value)

Beschreibung

Gibt den Eingabe-ARRAY mit Elementen in umgekehrter Reihenfolge zurück.

Rückgabetyp

ARRAY

Beispiele

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [4, 5] AS arr UNION ALL
  SELECT [] AS arr
)
SELECT
  arr,
  ARRAY_REVERSE(arr) AS reverse_arr
FROM example;

+-----------+-------------+
| arr       | reverse_arr |
+-----------+-------------+
| [1, 2, 3] | [3, 2, 1]   |
| [4, 5]    | [5, 4]      |
| []        | []          |
+-----------+-------------+

SAFE_OFFSET und SAFE_ORDINAL

array_expression[SAFE_OFFSET(zero_based_offset)]
array_expression[SAFE_ORDINAL(one_based_offset)]

Beschreibung

Identisch mit OFFSET und ORDINAL, außer dass NULL zurückgegeben wird, wenn der Index außerhalb des Bereichs liegt.

Rückgabetyp

Variiert je nach den Elementen im ARRAY.

Beispiel

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list,
  list[SAFE_OFFSET(3)] as safe_offset_3,
  list[SAFE_ORDINAL(3)] as safe_ordinal_3
FROM items;

+----------------------------------+---------------+----------------+
| list                             | safe_offset_3 | safe_ordinal_3 |
+----------------------------------+---------------+----------------+
| [apples, bananas, pears, grapes] | grapes        | pears          |
| [coffee, tea, milk]              | NULL          | milk           |
| [cake, pie]                      | NULL          | NULL           |
+----------------------------------+---------------+----------------+

DATE-Funktionen

Cloud Spanner SQL unterstützt die folgenden DATE-Funktionen.

CURRENT_DATE

CURRENT_DATE([time_zone])

Beschreibung

Gibt das aktuelle Datum in der angegebenen oder in der Standardzeitzone zurück.

Diese Funktion unterstützt den optionalen Parameter time_zone. Dieser Parameter ist ein String, der die Zeitzone darstellt, die verwendet werden soll. Wenn keine Zeitzone angegeben ist, wird die Standardzeitzone, "America/Los_Angeles" verwendet. Informationen zur Angabe einer Zeitzone finden Sie unter Zeitzonendefinitionen.

Wenn der Parameter time_zone als NULL ausgewertet wird, gibt diese Funktion NULL zurück.

Rückgabedatentyp

DATE

Beispiel

SELECT CURRENT_DATE() as the_date;

+--------------+
| the_date     |
+--------------+
| 2016-12-25   |
+--------------+

EXTRACT

EXTRACT(part FROM date_expression)

Beschreibung

Gibt den Wert zurück, der dem angegebenen Datumsteil entspricht. part muss einer der folgenden Typen sein:

  • DAYOFWEEK: gibt Werte im Bereich [1,7] mit Sonntag als dem ersten Tag der Woche zurück.
  • DAY
  • DAYOFYEAR
  • WEEK: gibt die Kalenderwoche des Datums im Bereich [0, 53] zurück. Wochen beginnen mit Sonntag und Datumsangaben vor dem ersten Sonntag des Jahres liegen in Woche 0.
  • ISOWEEK: gibt die ISO 8601-Wochennummer von date_expression zurück. ISOWEEK-Wochen beginnen am Montag. Rückgabewerte liegen im Bereich [1, 53]. Die erste ISOWEEK-Woche eines ISO-Jahres beginnt am Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres.
  • MONTH
  • QUARTER: gibt Werte im Bereich [1,4] zurück.
  • YEAR
  • ISOYEAR: gibt das Kalenderjahr mit ISO 8601-Wochennummerierung zurück. Das entspricht dem gregorianischen Kalenderjahr mit dem Donnerstag der Woche, zu der date_expression gehört.

Rückgabedatentyp

INT64

Beispiele

Im folgenden Beispiel gibt EXTRACT einen Wert zurück, der dem Datumsteil DAY entspricht.

SELECT EXTRACT(DAY FROM DATE '2013-12-25') as the_day;

+---------+
| the_day |
+---------+
| 25      |
+---------+

Im folgenden Beispiel gibt EXTRACT Werte zurück, die verschiedenen Teilen der Terminangabe aus einer Spalte von Daten rund um das Jahresende entsprechen.

SELECT
  date,
  EXTRACT(ISOYEAR FROM date) AS isoyear,
  EXTRACT(ISOWEEK FROM date) AS isoweek,
  EXTRACT(YEAR FROM date) AS year,
  EXTRACT(WEEK FROM date) AS week
FROM UNNEST(GENERATE_DATE_ARRAY('2015-12-23', '2016-01-09')) AS date
ORDER BY date;
+------------+---------+---------+------+------+
| date       | isoyear | isoweek | year | week |
+------------+---------+---------+------+------+
| 2015-12-23 | 2015    | 52      | 2015 | 51   |
| 2015-12-24 | 2015    | 52      | 2015 | 51   |
| 2015-12-25 | 2015    | 52      | 2015 | 51   |
| 2015-12-26 | 2015    | 52      | 2015 | 51   |
| 2015-12-27 | 2015    | 52      | 2015 | 52   |
| 2015-12-28 | 2015    | 53      | 2015 | 52   |
| 2015-12-29 | 2015    | 53      | 2015 | 52   |
| 2015-12-30 | 2015    | 53      | 2015 | 52   |
| 2015-12-31 | 2015    | 53      | 2015 | 52   |
| 2016-01-01 | 2015    | 53      | 2016 | 0    |
| 2016-01-02 | 2015    | 53      | 2016 | 0    |
| 2016-01-03 | 2015    | 53      | 2016 | 1    |
| 2016-01-04 | 2016    | 1       | 2016 | 1    |
| 2016-01-05 | 2016    | 1       | 2016 | 1    |
| 2016-01-06 | 2016    | 1       | 2016 | 1    |
| 2016-01-07 | 2016    | 1       | 2016 | 1    |
| 2016-01-08 | 2016    | 1       | 2016 | 1    |
| 2016-01-09 | 2016    | 1       | 2016 | 1    |
+------------+---------+---------+------+------+

DATE

1. DATE(year, month, day)
2. DATE(timestamp_expression[, timezone])

Beschreibung

  1. Erstellt einen DATE-Wert aus INT64-Werten, die das Jahr, den Monat und den Tag darstellen.
  2. Extrahiert DATE aus einem TIMESTAMP-Ausdruck. Ein optionaler Parameter zur Angabe einer Zeitzone wird unterstützt. Wenn keine Zeitzone angegeben ist, wird die Standardzeitzone "America/Los_Angeles" verwendet.

Rückgabedatentyp

DATE

Beispiel

SELECT
  DATE(2016, 12, 25) as date_ymd,
  DATE(TIMESTAMP "2016-12-25 05:30:00+07", "America/Los_Angeles") as date_tstz;

+------------+------------+
| date_ymd   | date_tstz  |
+------------+------------+
| 2016-12-25 | 2016-12-24 |
+------------+------------+

DATE_ADD

DATE_ADD(date_expression, INTERVAL int64_expression date_part)

Beschreibung

Fügt einem DATE ein bestimmtes Zeitintervall hinzu.

DATE_ADD unterstützt die folgenden date_part-Werte:

  • DAY
  • WEEK. Entspricht sieben DAYs.
  • MONTH
  • QUARTER
  • YEAR

MONTH, QUARTER und YEAR müssen speziell behandelt werden, wenn das Datum der letzte Tag des Monats ist oder in dessen Nähe liegt. Wenn der daraus resultierende Monat weniger Tage als der Monat des ursprünglichen Datums hat, ist der Ergebnistag der letzte Tag des neuen Monats.

Rückgabedatentyp

DATE

Beispiel

SELECT DATE_ADD(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_later;

+--------------------+
| five_days_later    |
+--------------------+
| 2008-12-30         |
+--------------------+

DATE_SUB

DATE_SUB(date_expression, INTERVAL int64_expression date_part)

Beschreibung

Subtrahiert ein bestimmtes Zeitintervall von einem DATE.

DATE_SUB unterstützt die folgenden date_part-Werte:

  • DAY
  • WEEK. Entspricht sieben DAYs.
  • MONTH
  • QUARTER
  • YEAR

MONTH, QUARTER und YEAR müssen speziell behandelt werden, wenn das Datum der letzte Tag des Monats ist oder in dessen Nähe liegt. Wenn der daraus resultierende Monat weniger Tage als der Monat des ursprünglichen Datums hat, ist der Ergebnistag der letzte Tag des neuen Monats.

Rückgabedatentyp

DATE

Beispiel

SELECT DATE_SUB(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_ago;

+---------------+
| five_days_ago |
+---------------+
| 2008-12-20    |
+---------------+

DATE_DIFF

DATE_DIFF(date_expression_a, date_expression_b, date_part)

Beschreibung

Gibt die Anzahl der gesamten angegebenen date_part-Intervalle zwischen zwei DATE-Objekten (date_expression_a - date_expression_b) zurück. Wenn der erste DATE vor dem zweiten liegt, ist die Ausgabe negativ.

DATE_DIFF unterstützt die folgenden date_part-Werte:

  • DAY
  • WEEK: Dieser Datumsteil beginnt mit Sonntag.
  • ISOWEEK: Verwendet Wochengrenzen nach ISO 8601. ISO-Wochen beginnen mit Montag.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: Verwendet die Jahresgrenze gemäß der ISO 8601-Wochennummerierung. Die ISO-Jahresgrenze ist der Montag der ersten Woche, in der der Donnerstag in das entsprechende gregorianische Kalenderjahr fällt.

Rückgabedatentyp

INT64

Beispiel

SELECT DATE_DIFF(DATE '2010-07-07', DATE '2008-12-25', DAY) as days_diff;

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+
SELECT
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', DAY) as days_diff,
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', WEEK) as weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

Im obigen Beispiel wird das Ergebnis von DATE_DIFF für zwei aufeinanderfolgende Tage dargestellt. DATE_DIFF mit dem Datumsteil WEEK gibt 1 zurück, da DATE_DIFF die Anzahl der Datumsteilgrenzen in diesem Datumsbereich zählt. Jede WEEK beginnt mit Sonntag. Deshalb gibt es eine Datumsteilgrenze zwischen Samstag, dem 14.10.2017, und Sonntag, dem 15.10.2017.

Im folgenden Beispiel wird das Ergebnis von DATE_DIFF für zwei Datumsangaben in verschiedenen Jahren dargestellt. DATE_DIFF mit dem Datumsteil YEAR gibt 3 zurück, da die Anzahl der Grenzen von gregorianischen Kalenderjahren zwischen den beiden Datumsangaben gezählt wird. DATE_DIFF mit dem Datumsteil ISOYEAR gibt 2 zurück, da das zweite Datum zum ISO-Jahr 2015 zählt. Der erste Donnerstag des Kalenderjahres 2015 fiel auf den 01.01.2015. Deshalb beginnt das ISO-Jahr 2015 mit dem Montag davor am 29.12.2014.

SELECT
  DATE_DIFF('2017-12-30', '2014-12-30', YEAR) AS year_diff,
  DATE_DIFF('2017-12-30', '2014-12-30', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

Im folgenden Beispiel wird das Ergebnis von DATE_DIFF für zwei aufeinanderfolgende Tage dargestellt. Das erste Datum fällt auf einen Montag, das zweite auf einen Sonntag. DATE_DIFF mit dem Datumsteil WEEK gibt 0 zurück, da dieser Datumsteil Wochen verwendet, die mit Sonntag beginnen. DATE_DIFF mit dem Datumsteil ISOWEEK gibt 1 zurück, da ISO-Wochen mit Montag beginnen.

SELECT
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+--------------+
| week_diff | isoweek_diff |
+-----------+--------------+
| 0         | 1            |
+-----------+--------------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Beschreibung

Kürzt das Datum auf die angegebene Granularität.

DATE_TRUNC unterstützt die folgenden Werte für date_part:

  • DAY
  • WEEK
  • ISOWEEK: kürzt date_expression auf die vorhergehende Wochengrenze nach ISO 8601. ISOWEEKs beginnen mit dem Montag. Die erste ISOWEEK eines ISO-Jahres enthält den ersten Donnerstag des entsprechenden gregorianischen Kalenderjahres. Jede date_expression vor diesem Datum wird auf den Montag davor gekürzt.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: kürzt date_expression auf die vorhergehende Jahresgrenze gemäß der ISO 8601-Wochennummerierung. Die ISO-Jahresgrenze ist der Montag der ersten Woche, in der der Donnerstag in das entsprechende gregorianische Kalenderjahr fällt.

Rückgabedatentyp

DATE

Beispiele

SELECT DATE_TRUNC(DATE '2008-12-25', MONTH) as month;

+------------+
| month      |
+------------+
| 2008-12-01 |
+------------+

Im folgenden Beispiel liegt der ursprüngliche date_expression im gregorianischen Kalenderjahr 2015. DATE_TRUNC mit dem Datumsteil ISOYEAR kürzt date_expression jedoch bis zum Anfang des ISO-Jahres und nicht des gregorianischen Kalenderjahres. Der erste Donnerstag des Kalenderjahres 2015 fiel auf den 01.01.2015. Deshalb beginnt das ISO-Jahr 2015 mit dem Montag davor am 29.12.2014. Entsprechend fällt die ISO-Jahresgrenze vor dem date_expression 2015-06-15 auf den 29.12.2014.

SELECT
  DATE_TRUNC('2015-06-15', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATE '2015-06-15') AS isoyear_number;

+------------------+----------------+
| isoyear_boundary | isoyear_number |
+------------------+----------------+
| 2014-12-29       | 2015           |
+------------------+----------------+

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(int64_expression)

Beschreibung

Interpretiert int64_expression als Anzahl der Tage seit dem 01.01.1970.

Rückgabedatentyp

DATE

Beispiel

SELECT DATE_FROM_UNIX_DATE(14238) as date_from_epoch;

+-----------------+
| date_from_epoch |
+-----------------+
| 2008-12-25      |
+-----------------+

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

Beschreibung

Formatiert date_expr gemäß dem angegebenen Wert für format_string.

Unter Unterstützte Formatelemente für DATE sind die Formatelemente aufgelistet, die von dieser Funktion unterstützt werden.

Rückgabedatentyp

STRING

Beispiele

SELECT FORMAT_DATE("%x", DATE "2008-12-25") as US_format;

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+
SELECT FORMAT_DATE("%b-%d-%Y", DATE "2008-12-25") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec-25-2008 |
+-------------+
SELECT FORMAT_DATE("%b %Y", DATE "2008-12-25") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec 2008    |
+-------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

Beschreibung

Verwendet für die Rückgabe eines DATE-Objekts einen format_string und eine Stringdarstellung eines Datums.

Beachten Sie bei Verwendung von PARSE_DATE Folgendes:

  • Nicht angegebene Felder: Jedes nicht angegebene Feld wird ab 1970-01-01 initialisiert.
  • Groß-/Kleinschreibung in Namen: Bei Namen wie Monday, February usw. wird die Groß-/Kleinschreibung nicht berücksichtigt.
  • Leerraum: Ein oder mehrere aufeinanderfolgende Leerräume im Formatstring stimmen mit null oder mehreren aufeinanderfolgenden Leerräumen im Datumsstring überein. Darüber hinaus sind voran- und nachgestellte Leerräume im Datumsstring immer erlaubt­­ – auch wenn sie nicht im Formatstring vorhanden sind.
  • Formatvorrang. Wenn zwei (oder mehr) Formatelemente überlappende Informationen enthalten (beispielsweise beeinflussen %F und %Y beide das Jahr), überschreibt im Allgemeinen das letzte Format alle vorherigen Formate.

Rückgabedatentyp

DATE

Beispiel

SELECT PARSE_DATE("%x", "12/25/08") as parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

UNIX_DATE

UNIX_DATE(date_expression)

Beschreibung

Gibt die Anzahl der Tage seit dem 01.01.1970 zurück.

Rückgabedatentyp

INT64

Beispiel

SELECT UNIX_DATE(DATE "2008-12-25") as days_from_epoch;

+-----------------+
| days_from_epoch |
+-----------------+
| 14238           |
+-----------------+

Unterstützte Formatelemente für DATE

Wenn nicht anders angegeben, unterstützen DATE-Funktionen, die Formatstrings verwenden, folgende Elemente:

Formatelement Beschreibung
%A Der vollständige Wochentagname.
%a Der abgekürzte Wochentagname.
%B Der vollständige Monatsname.
%b oder %h Der abgekürzte Monatsname.
%C Das Jahrhundert (ein Jahr geteilt durch 100 und gekürzt auf eine Ganzzahl) als Dezimalzahl (00–99).
%D Das Datum im Format %m/%d/%y.
%d Der Tag des Monats als Dezimalzahl (01–31).
%e Der Tag des Monats als Dezimalzahl (1–31); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.
%F Das Datum im Format %Y-%m-%d.
%G Das Jahr nach ISO 8601 mit Jahrhundert als Dezimalzahl. Jedes ISO-Jahr beginnt mit dem Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres. Beachten Sie, dass %G und %Y nahe den gregorianischen Jahresgrenzen unterschiedliche Ergebnisse erzeugen können, wobei das gregorianische Jahr und ISO-Jahr voneinander abweichen können.
%g Das Jahr nach ISO 8601 ohne Jahrhundert als Dezimalzahl (00–99). Jedes ISO-Jahr beginnt mit dem Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres. Beachten Sie, dass %g und %y nahe den gregorianischen Jahresgrenzen unterschiedliche Ergebnisse erzeugen können, wobei das gregoriansiche Jahr und ISO-Jahr von einander abweichen können.
%j Der Tag des Jahres als Dezimalzahl (001–366).
%m Der Monat als Dezimalzahl (01–12).
%n Ein Zeilenumbruch.
%t Ein Tab-Zeichen.
%U Die Wochennummer des Jahres (Sonntag als erster Tag der Woche) als Dezimalzahl (00–53).
%u Der Wochentag (Montag als erster Tag der Woche) als Dezimalzahl (1–7).
%V Die ISO 8601-Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (01–53). Wenn die Woche mit dem 1. Januar mindestens vier Tage im neuen Jahr hat, dann ist sie Woche 1. Andernfalls ist sie Woche 53 des Vorjahres und die nächste Woche ist Woche 1.
%W Die Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (00–53).
%w Der Wochentag (Sonntag als erster Tag der Woche) als Dezimalzahl (0–6).
%x Die Datumsdarstellung im MM/TT/JJ-Format.
%Y Das Jahr mit Jahrhundert als Dezimalzahl.
%y Das Jahr ohne Jahrhundert als Dezimalzahl (00–99), mit einer optionalen vorangestellten Null. Kann mit %C gemischt werden. Wenn %C nicht angegeben ist, sind die Jahre 00–68 2000er, während die Jahre 69–99 1900er sind.
%E4Y Jahre mit vier Ziffern (von 0001 bis 9999). Beachten Sie, dass %Y so viele Zeichen ergibt, wie nötig sind, um das Jahr komplett darzustellen.

TIMESTAMP-Funktionen

Cloud Spanner SQL unterstützt die folgenden TIMESTAMP-Funktionen.

HINWEIS: Diese Funktionen geben bei Überlauf einen Laufzeitfehler zurück. Die Ergebniswerte werden durch die definierten Mindest-/Maximalwerte von Datum und Zeitstempel begrenzt.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Beschreibung

Klammern sind optional. Diese Funktion verarbeitet Schaltsekunden, indem sie über ein Fenster von 20 Stunden um die eingefügten Schaltsekunden herum verteilt werden. CURRENT_TIMESTAMP() erzeugt einen TIMESTAMP-Wert, der kontinuierlich und eindeutig ist, genau 60 Sekunden pro Minute hat und keine Werte über die Schaltsekunde wiederholt.

Unterstützte Eingabetypen

Nicht zutreffend

Datentyp des Ergebnisses

TIMESTAMP

Beispiel

SELECT CURRENT_TIMESTAMP() as now;

+--------------------------------+
| now                            |
+--------------------------------+
| 2020-06-02T23:58:40.347847393Z |
+--------------------------------+

EXTRACT

EXTRACT(part FROM timestamp_expression [AT TIME ZONE tz_spec])

Beschreibung

Gibt einen Wert zurück, der dem angegebenen part aus einer bereitgestellten timestamp_expression entspricht.

Zulässige part-Werte:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAYOFWEEK
  • DAY
  • DAYOFYEAR
  • WEEK: gibt die Kalenderwoche des Datums im Bereich [0, 53] zurück. Wochen beginnen mit Sonntag und Datumsangaben vor dem ersten Sonntag des Jahres liegen in Woche 0.
  • ISOWEEK: gibt die ISO 8601-Wochennummer von datetime_expression zurück. ISOWEEK-Wochen beginnen am Montag. Rückgabewerte liegen im Bereich [1, 53]. Die erste ISOWEEK-Woche eines ISO-Jahres beginnt am Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: gibt das Kalenderjahr mit ISO 8601-Wochennummerierung zurück. Das entspricht dem gregorianischen Kalenderjahr mit dem Donnerstag der Woche, zu der date_expression gehört.
  • DATE

Bei den zurückgegebenen Werten werden jeweils die kleineren Zeiträume weggekürzt. Wenn Sie z. B. Sekunden extrahieren, werden durch EXTRACT die Millisekunden- und Mikrosekundenwerte entfernt.

Informationen zur Angabe einer Zeitzone finden Sie unter Zeitzonendefinitionen.

Rückgabedatentyp

INT64, außer in folgenden Fällen:

  • Wenn part DATE ist, wird ein DATE-Objekt zurückgegeben.

Beispiele

Im folgenden Beispiel gibt EXTRACT einen Wert zurück, der dem Datumsteil DAY entspricht.

WITH Input AS (SELECT TIMESTAMP("2008-12-25 05:30:00+00") AS timestamp_value)
SELECT
  EXTRACT(DAY FROM timestamp_value AT TIME ZONE "UTC") AS the_day_utc,
  EXTRACT(DAY FROM timestamp_value AT TIME ZONE "America/Los_Angeles") AS the_day_california
FROM Input

+-------------+--------------------+
| the_day_utc | the_day_california |
+-------------+--------------------+
| 25          | 24                 |
+-------------+--------------------+

Im folgenden Beispiel gibt EXTRACT Werte zurück, die verschiedenen Datumsteilen aus einer Spalte mit Zeitstempeln entsprechen.

WITH Timestamps AS (
  SELECT TIMESTAMP("2005-01-03 12:34:56+00") AS timestamp_value UNION ALL
  SELECT TIMESTAMP("2007-12-31 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2009-01-01 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2009-12-31 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2017-01-02 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2017-05-26 12:00:00+00")
)
SELECT
  timestamp_value,
  EXTRACT(ISOYEAR FROM timestamp_value) AS isoyear,
  EXTRACT(ISOWEEK FROM timestamp_value) AS isoweek,
  EXTRACT(YEAR FROM timestamp_value) AS year,
  EXTRACT(WEEK FROM timestamp_value) AS week
FROM Timestamps
ORDER BY timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+---------+---------+------+------+
| timestamp_value        | isoyear | isoweek | year | week |
+------------------------+---------+---------+------+------+
| 2005-01-03T12:34:56Z   | 2005    | 1       | 2005 | 1    |
| 2007-12-31T12:00:00Z   | 2008    | 1       | 2007 | 52   |
| 2009-01-01T12:00:00Z   | 2009    | 1       | 2009 | 0    |
| 2009-12-31T12:00:00Z   | 2009    | 53      | 2009 | 52   |
| 2017-01-02T12:00:00Z   | 2017    | 1       | 2017 | 1    |
| 2017-05-26T12:00:00Z   | 2017    | 21      | 2017 | 21   |
+------------------------+---------+---------+------+------+

STRING

STRING(timestamp_expression[, timezone])

Beschreibung

Wandelt einen timestamp_expression in einen STRING-Datentyp um. Unterstützt einen optionalen Parameter zur Angabe einer Zeitzone. Informationen zur Angabe einer Zeitzone finden Sie unter Zeitzonendefinitionen.

Rückgabedatentyp

STRING

Beispiel

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00+00", "UTC") AS string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 15:30:00+00        |
+-------------------------------+

TIMESTAMP

TIMESTAMP(string_expression[, timezone])
TIMESTAMP(date_expression[, timezone])

Beschreibung

  • string_expression[, timezone]: wandelt einen STRING-Ausdruck in einen TIMESTAMP-Datentyp um. string_expression muss ein Zeitstempelliteral enthalten. Wenn string_expression eine Zeitzone im Zeitstempelliteral enthält, fügen Sie kein explizites timezone-Argument ein.
  • date_expression[, timezone]: wandelt ein DATE-Objekt in einen TIMESTAMP-Datentyp um.

Diese Funktion unterstützt einen optionalen Parameter zur Angabe einer Zeitzone. Wenn keine Zeitzone angegeben ist, wird die Standardzeitzone "America/Los_Angeles" verwendet.

Rückgabedatentyp

TIMESTAMP

Beispiele

SELECT TIMESTAMP("2008-12-25 15:30:00+00") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T15:30:00Z |
+----------------------+
SELECT TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T23:30:00Z |
+----------------------+
SELECT TIMESTAMP("2008-12-25 15:30:00 UTC") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T15:30:00Z |
+----------------------+
SELECT TIMESTAMP(DATE "2008-12-25") AS timestamp_date;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T08:00:00Z |
+----------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

Beschreibung

Addiert zum Zeitstempel unabhängig von der Zeitzone int64_expression date_part-Einheiten hinzu.

TIMESTAMP_ADD unterstützt die folgenden Werte für date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Entspricht dem Wert 60  für MINUTE.
  • DAY. Entspricht dem Wert 24 für HOUR.

Rückgabedatentypen

TIMESTAMP

Beispiel

SELECT
  TIMESTAMP("2008-12-25 15:30:00+00") AS original,
  TIMESTAMP_ADD(TIMESTAMP "2008-12-25 15:30:00+00", INTERVAL 10 MINUTE) AS later;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25T15:30:00Z   | 2008-12-25T15:40:00Z   |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL int64_expression date_part)

Beschreibung

Subtrahiert vom Zeitstempel unabhängig von der Zeitzone int64_expression date_part-Einheiten.

TIMESTAMP_SUB unterstützt die folgenden Werte für date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Entspricht dem Wert 60  für MINUTE.
  • DAY. Entspricht dem Wert 24 für HOUR.

Rückgabedatentyp

TIMESTAMP

Beispiel

SELECT
  TIMESTAMP("2008-12-25 15:30:00+00") AS original,
  TIMESTAMP_SUB(TIMESTAMP "2008-12-25 15:30:00+00", INTERVAL 10 MINUTE) AS earlier;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25T15:30:00Z   | 2008-12-25T15:20:00Z   |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression_a, timestamp_expression_b, date_part)

Beschreibung

Gibt die Anzahl der gesamten angegebenen date_part-Intervalle zwischen zwei TIMESTAMP-Objekten (timestamp_expression_a - timestamp_expression_b) zurück. Wenn der erste TIMESTAMP vor dem zweiten liegt, ist die Ausgabe negativ. Ein Fehler wird ausgegeben, wenn die Berechnung einen Überlauf des Ergebnistyps verursacht, z. B. wenn die Differenz in Nanosekunden zwischen den beiden TIMESTAMP-Objekten einen Überlauf für einen INT64-Wert verursachen würde.

TIMESTAMP_DIFF unterstützt die folgenden Werte für date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Entspricht dem Wert 60  für MINUTE.
  • DAY. Entspricht dem Wert 24 für HOUR.

Rückgabedatentyp

INT64

Beispiel

SELECT
  TIMESTAMP("2010-07-07 10:20:00+00") AS later_timestamp,
  TIMESTAMP("2008-12-25 15:30:00+00") AS earlier_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00+00", TIMESTAMP "2008-12-25 15:30:00+00", HOUR) AS hours;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+-------+
| later_timestamp        | earlier_timestamp      | hours |
+------------------------+------------------------+-------+
| 2010-07-07T10:20:00Z   | 2008-12-25T15:30:00Z   | 13410 |
+------------------------+------------------------+-------+

Im folgenden Beispiel liegt der erste Zeitstempel vor dem zweiten, was zu einer negativen Ausgabe führt.

SELECT TIMESTAMP_DIFF(TIMESTAMP "2018-08-14", TIMESTAMP "2018-10-14", DAY);

+---------------+
| negative_diff |
+---------------+
| -61           |
+---------------+

In diesem Beispiel ist das Ergebnis 0, da nur die Anzahl der gesamten angegebenen HOUR-Intervalle enthalten ist.

SELECT TIMESTAMP_DIFF("2001-02-01 01:00:00", "2001-02-01 00:00:01", HOUR)

+---------------+
| negative_diff |
+---------------+
| 0             |
+---------------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part[, time_zone])

Beschreibung

Kürzt einen Zeitstempel auf die Granularität von date_part.

TIMESTAMP_TRUNC unterstützt die folgenden Werte für date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • ISOWEEK: kürzt timestamp_expression auf die vorhergehende Wochengrenze nach ISO 8601. ISOWEEKs beginnen mit dem Montag. Die erste ISOWEEK eines ISO-Jahres enthält den ersten Donnerstag des entsprechenden gregorianischen Kalenderjahres. Jede date_expression vor diesem Datum wird auf den Montag davor gekürzt.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: kürzt timestamp_expression auf die vorhergehende Jahresgrenze gemäß der ISO 8601-Wochennummerierung. Die ISO-Jahresgrenze ist der Montag der ersten Woche, in der der Donnerstag in das entsprechende gregorianische Kalenderjahr fällt.

Die Funktion TIMESTAMP_TRUNC unterstützt den optionalen Parameter time_zone. Dieser Parameter gilt für die folgenden date_parts:

  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

Verwenden Sie diesen Parameter, wenn eine andere Zeitzone als die Standardzeitzone "America/Los_Angeles" als Teil der Kürzung verwendet werden soll.

Beim Kürzen vom TIMESTAMP auf MINUTE oder HOUR gibt TIMESTAMP_TRUNC die amtliche Zeit von TIMESTAMP in der angegebenen (oder standardmäßigen) Zeitzone an und subtrahiert die Minuten und Sekunden (beim Kürzen auf HOUR) oder die Sekunden (beim Kürzen auf MINUTE) von diesem TIMESTAMP-Wert. Dadurch ergeben sich in den meisten Fällen intuitive Ergebnisse. Bei zeitlicher Nähe zu Sommerzeitübergängen ohne Stundenangleichung sind sie jedoch nicht intuitiv.

Rückgabedatentyp

TIMESTAMP

Beispiele

SELECT
  TIMESTAMP_TRUNC(TIMESTAMP "2008-12-25 15:30:00+00", DAY, "UTC") AS utc,
  TIMESTAMP_TRUNC(TIMESTAMP "2008-12-25 15:30:00+00", DAY, "America/Los_Angeles") AS la;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25T00:00:00Z   | 2008-12-25T08:00:00Z   |
+------------------------+------------------------+

Im folgenden Beispiel liegt der ursprüngliche timestamp_expression im gregorianischen Kalenderjahr 2015. TIMESTAMP_TRUNC mit dem Datumsteil ISOYEAR kürzt den timestamp_expression jedoch bis zum Anfang des ISO-Jahres und nicht des gregorianischen Kalenderjahres. Der erste Donnerstag des Kalenderjahres 2015 fiel auf den 01.01.2015. Deshalb beginnt das ISO-Jahr 2015 mit dem Montag davor am 29.12.2014. Entsprechend fällt die ISO-Jahresgrenze vor timestamp_expression 2015-06-15 00:00:00+00 auf den 29.12.2014.

SELECT
  TIMESTAMP_TRUNC("2015-06-15 00:00:00+00", ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM TIMESTAMP "2015-06-15 00:00:00+00") AS isoyear_number;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+----------------+
| parsed                 | isoyear_number |
+------------------------+----------------+
| 2014-12-29T08:00:00Z   | 2015           |
+------------------------+----------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

Beschreibung

Formatiert einen Zeitstempel gemäß dem angegebenen format_string-Wert.

Unter Unterstützte Formatelemente für TIMESTAMP ist eine Liste mit Formatelementen aufgeführt, die von dieser Funktion unterstützt werden.

Rückgabedatentyp

STRING

Beispiel

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2008-12-25 15:30:00+00", "UTC") AS formatted;

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 15:30:00 2008 |
+--------------------------+
SELECT FORMAT_TIMESTAMP("%b-%d-%Y", TIMESTAMP "2008-12-25 15:30:00+00") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec-25-2008 |
+-------------+
SELECT FORMAT_TIMESTAMP("%b %Y", TIMESTAMP "2008-12-25 15:30:00+00")
  AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec 2008    |
+-------------+

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, string[, time_zone])

Beschreibung

Verwendet einen format_string und eine Stringdarstellung eines Zeitstempels, um ein TIMESTAMP-Objekt zurückzugeben.

Beachten Sie bei Verwendung von PARSE_TIMESTAMP Folgendes:

  • Nicht angegebene Felder: Jedes nicht angegebene Feld wird ab 1970-01-01 00:00:00.0 initialisiert. Dieser Initialisierungswert verwendet die durch das Zeitzonenargument der Funktion angegebene Zeitzone, falls vorhanden. Wenn das Argument nicht vorhanden ist, verwendet der Initialisierungswert die Standardzeitzone "America/Los_Angeles". Sollte beispielsweise das Jahr nicht angegeben sein, wird standardmäßig 1970 verwendet usw.
  • Groß-/Kleinschreibung in Namen: Bei Namen wie Monday, February usw. wird die Groß-/Kleinschreibung nicht berücksichtigt.
  • Leerraum. Ein oder mehrere aufeinanderfolgende Leerräume im Formatstring stimmen mit null oder mehreren aufeinanderfolgenden Leerräumen im Zeitstempelstring überein. Darüber hinaus sind voran- und nachgestellte Leerräume im Zeitstempelstring immer erlaubt – auch wenn sie nicht im Formatstring vorhanden sind.
  • Formatvorrang. Wenn zwei oder mehr Formatelemente überlappende Informationen haben (%F und %Y beeinflussen z. B. beide das Jahr), überschreibt im Allgemeinen das letzte Format alle vorherigen Formate, mit gewissen Ausnahmen (siehe Beschreibung von %s, %C und %y).

Rückgabedatentyp

TIMESTAMP

Beispiel

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008") AS parsed;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| parsed                 |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_SECONDS

TIMESTAMP_SECONDS(int64_expression)

Beschreibung

Interpretiert int64_expression als Anzahl der Sekunden seit 01.01.1970 00:00:00 UTC.

Rückgabedatentyp

TIMESTAMP

Beispiel

SELECT TIMESTAMP_SECONDS(1230219000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

Beschreibung

Interpretiert int64_expression als Anzahl der Millisekunden seit 01.01.1970 00:00:00 UTC.

Rückgabedatentyp

TIMESTAMP

Beispiel

SELECT TIMESTAMP_MILLIS(1230219000000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

Beschreibung

Interpretiert int64_expression als Anzahl der Mikrosekunden seit 01.01.1970 00:00:00 UTC.

Rückgabedatentyp

TIMESTAMP

Beispiel

SELECT TIMESTAMP_MICROS(1230219000000000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Beschreibung

Gibt die Anzahl der Sekunden seit 01.01.1970 00:00:00 UTC zurück. Nachkommastellen werden abgeschnitten.

Rückgabedatentyp

INT64

Beispiel

SELECT UNIX_SECONDS(TIMESTAMP "2008-12-25 15:30:00+00") AS seconds;

+------------+
| seconds    |
+------------+
| 1230219000 |
+------------+

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Beschreibung

Gibt die Anzahl der Millisekunden seit 01.01.1970 00:00:00 UTC zurück. Nachkommastellen werden abgeschnitten.

Rückgabedatentyp

INT64

Beispiel

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00+00") AS millis;

+---------------+
| millis        |
+---------------+
| 1230219000000 |
+---------------+

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

Beschreibung

Gibt die Anzahl der Mikrosekunden seit 01.01.1970 00:00:00 UTC zurück. Nachkommastellen werden abgeschnitten.

Rückgabedatentyp

INT64

Beispiel

SELECT UNIX_MICROS(TIMESTAMP "2008-12-25 15:30:00+00") AS micros;

+------------------+
| micros           |
+------------------+
| 1230219000000000 |
+------------------+

PENDING_COMMIT_TIMESTAMP

PENDING_COMMIT_TIMESTAMP()

Beschreibung

Verwenden Sie die Funktion PENDING_COMMIT_TIMESTAMP() in einer DML-Anweisung vom Typ INSERT oder UPDATE, um den ausstehenden Commit-Zeitstempel, also den Commit-Zeitstempel des Schreibvorgangs, in eine Spalte vom Typ TIMESTAMP zu schreiben.

Cloud Spanner SQL wählt den Commit-Zeitstempel aus, wenn der Commit der Transaktion ausgeführt wird. Die PENDING_COMMIT_TIMESTAMP-Funktion kann nur als Wert für INSERT oder UPDATE einer entsprechend typisierten Spalte verwendet werden. Er kann nicht in SELECT oder als Eingabe für einen anderen skalaren Ausdruck verwendet werden.

Rückgabedatentyp

TIMESTAMP

Beispiel

Mit der folgenden DML-Anweisung wird der Commit-Zeitstempel in die Spalte LastUpdated in der Tabelle "Singers" geschrieben.

UPDATE Performances SET LastUpdated = PENDING_COMMIT_TIMESTAMP()
   WHERE SingerId=1 AND VenueId=2 AND EventDate="2015-10-21"

Unterstützte Formatelemente für TIMESTAMP

Wenn nicht anders angegeben, unterstützen TIMESTAMP-Funktionen, die Formatstrings verwenden, folgende Elemente:

Formatelement Beschreibung
%A Der vollständige Wochentagname.
%a Der abgekürzte Wochentagname.
%B Der vollständige Monatsname.
%b oder %h Der abgekürzte Monatsname.
%C Das Jahrhundert (ein Jahr geteilt durch 100 und gekürzt auf eine Ganzzahl) als Dezimalzahl (00–99).
%c Die Datums- und Uhrzeitdarstellung im Format %a %b %e %T %Y.
%D Das Datum im Format %m/%d/%y.
%d Der Tag des Monats als Dezimalzahl (01–31).
%e Der Tag des Monats als Dezimalzahl (1–31); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.
%F Das Datum im Format %Y-%m-%d.
%G Das Jahr nach ISO 8601 mit Jahrhundert als Dezimalzahl. Jedes ISO-Jahr beginnt mit dem Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres. Beachten Sie, dass %G und %Y nahe den gregorianischen Jahresgrenzen unterschiedliche Ergebnisse erzeugen können, wobei das gregorianische Jahr und ISO-Jahr voneinander abweichen können.
%g Das Jahr nach ISO 8601 ohne Jahrhundert als Dezimalzahl (00–99). Jedes ISO-Jahr beginnt mit dem Montag vor dem ersten Donnerstag des gregorianischen Kalenderjahres. Beachten Sie, dass %g und %y nahe den gregorianischen Jahresgrenzen unterschiedliche Ergebnisse erzeugen können, wobei das gregorianische Jahr und ISO-Jahr voneinander abweichen können.
%H Die Stunde (24-Stunden-Anzeige) als Dezimalzahl (00–23).
%I Die Stunde (12-Stunden-Anzeige) als Dezimalzahl (01–12).
%j Der Tag des Jahres als Dezimalzahl (001–366).
%k Die Stunde (24-Stunden-Anzeige) als Dezimalzahl (0–23); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.
%l Die Stunde (12-Stunden-Anzeige) als Dezimalzahl (1–12); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.
%M Die Minute als Dezimalzahl (00–59).
%m Der Monat als Dezimalzahl (01–12).
%n Ein Zeilenumbruch.
%P Entweder "am" oder "pm".
%p Entweder "AM" oder "PM".
%R Die Zeit im Format %H:%M.
%r Die 12-Stunden-Anzeige mit AM/PM-Notation.
%S Die Sekunde als Dezimalzahl (00–60).
%s Die Anzahl der Sekunden seit 01.01.1970 00:00:00 UTC. Überschreibt immer alle anderen Formatelemente, unabhängig davon, wo %s im String angezeigt wird. Wenn mehrere %s Elemente angezeigt werden, dann hat das letzte Element Vorrang.
%T Die Zeit im Format %H:%M:%S.
%t Ein Tab-Zeichen.
%U Die Wochennummer des Jahres (Sonntag als erster Tag der Woche) als Dezimalzahl (00–53).
%u Der Wochentag (Montag als erster Tag der Woche) als Dezimalzahl (1–7).
%V Die ISO 8601-Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (01–53). Wenn die Woche mit dem 1. Januar mindestens vier Tage im neuen Jahr hat, dann ist sie Woche 1. Andernfalls ist sie Woche 53 des Vorjahres und die nächste Woche ist Woche 1.
%W Die Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (00–53).
%w Der Wochentag (Sonntag als erster Tag der Woche) als Dezimalzahl (0–6).
%X Die Zeitdarstellung im HH:MM:SS-Format.
%x Die Datumsdarstellung im MM/TT/JJ-Format.
%Y Das Jahr mit Jahrhundert als Dezimalzahl.
%y Das Jahr ohne Jahrhundert als Dezimalzahl (00–99), mit einer optionalen vorangestellten Null. Kann mit %C gemischt werden. Wenn %C nicht angegeben ist, sind die Jahre 00–68 2000er, während die Jahre 69–99 1900er sind.
%Z Der Zeitzonenname.
%z Der Versatz von der Nullmeridian-Zeitzone je nach Bedarf im Format +HHMM oder -HHMM, wobei die positiven Werte Orte östlich von Greenwich darstellen.
%% Ein einzelnes %-Zeichen.
%Ez RFC 3339-kompatible numerische Zeitzone (+HH:MM oder -HH:MM).
%E#S Sekunden mit #-Ziffern in Bruchgenauigkeit.
%E*S Sekunden mit vollständiger Bruchgenauigkeit (ein literales "*").
%E4Y Jahre mit vier Ziffern (von 0001 bis 9999). Beachten Sie, dass %Y so viele Zeichen ergibt, wie nötig sind, um das Jahr komplett darzustellen.

Zeitzonendefinitionen

Mit bestimmten Datums- und Zeitstempelfunktionen kann die Standardzeitzone durch eine andere Zeitzone zu überschrieben werden. Sie geben eine Zeitzone entweder durch den Zeitzonennamen (z. B. America/Los_Angeles) oder durch den Zeitzonenversatz von UTC an (z. B. -08).

Wenn Sie sich für einen Zeitzonenversatz entscheiden, verwenden Sie folgendes Format:

(+|-)H[H][:M[M]]

Die folgenden Zeitstempel sind äquivalent, da der Zeitzonenversatz für America/Los_Angeles für das angegebene Datum und die angegebene Uhrzeit -08 lautet.

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00 America/Los_Angeles") as millis;
SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00-08:00") as millis;

Operatoren

Operatoren werden durch Sonderzeichen oder Schlüsselwörter dargestellt; sie verwenden keine Funktionsaufrufsyntax. Ein Operator manipuliert eine beliebige Anzahl von Dateneingaben, auch Operanden genannt, und gibt ein Ergebnis zurück.

Allgemeine Konventionen:

  • Wenn nicht anders angegeben, geben alle Operatoren NULL zurück, wenn einer der Operanden NULL ist.
  • Alle Operatoren geben einen Fehler aus, wenn das Berechnungsergebnis überläuft.
  • Bei allen Gleitkommaoperationen werden +/-inf und NaN nur zurückgegeben, wenn einer der Operanden +/-inf oder NaN ist. In allen anderen Fällen wird ein Fehler zurückgegeben.

In der folgenden Tabelle sind alle Cloud Spanner SQL-Operatoren von der höchsten bis zur niedrigsten Priorität aufgeführt, d. h. in der Reihenfolge, in der sie innerhalb einer Anweisung ausgewertet werden.

Rangfolge Operator Datentypen der Eingabe Name Operator-Arität
1 . STRUCT
Mitgliedsfeldzugriffsoperator Binär
  [ ] ARRAY Arrayposition. Muss mit OFFSET oder ORDINAL verwendet werden ­– siehe Arrayfunktionen . Binär
2 - Alle numerischen Typen Unäres Minus Unär
  ~ Ganzzahl oder BYTES Bitweises NOT Unär
3 * Alle numerischen Typen Multiplikation Binär
  / Alle numerischen Typen Division Binär
  || STRING, BYTES oder ARRAY<T> Verkettungsoperator Binär
4 + Alle numerischen Typen Addition Binär
  - Alle numerischen Typen Subtraktion Binär
5 << Ganzzahl oder BYTES Bitweise Linksverschiebung Binär
  >> Ganzzahl oder BYTES Bitweise Rechtsverschiebung Binär
6 & Ganzzahl oder BYTES Bitweises AND Binär
7 ^ Ganzzahl oder BYTES Bitweises XOR Binär
8 | Ganzzahl oder BYTES Bitweises OR Binär
9 (Vergleichsoperatoren) = Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Gleich Binär
  < Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Kleiner als Binär
  > Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Größer als Binär
  <= Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Kleiner als oder gleich Binär
  >= Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Größer als oder gleich Binär
  !=, <> Jeder vergleichbare Typ. Eine vollständige Liste finden Sie unter Datentypen. Ungleich Binär
  [NOT] LIKE STRING und Byte Wert entspricht [nicht] dem angegebenen Muster Binär
  [NOT] BETWEEN Alle vergleichbaren Typen. Eine vollständige Liste finden Sie unter Datentypen. Wert ist [nicht] innerhalb des angegebenen Bereichs Binär
  [NOT] IN Alle vergleichbaren Typen. Eine vollständige Liste finden Sie unter Datentypen. Wert ist [nicht] in der Liste der angegebenen Werte Binär
  IS [NOT] NULL Alle Wert ist [nicht] NULL. Unär
  IS [NOT] TRUE BOOL Wert ist [nicht] TRUE. Unär
  IS [NOT] FALSE BOOL Wert ist [nicht] FALSE. Unär
10 NOT BOOL Logisches NOT Unär
11 AND BOOL Logisches AND Binär
12 OR BOOL Logisches OR Binär

Operatoren mit der gleichen Präzedenz sind links-assoziativ. Das heißt, dass diese Operatoren von links nach rechts gruppiert werden. Zum Beispiel wird der Ausdruck:

x AND y AND z

interpretiert als:

( ( x AND y ) AND z )

Der Ausdruck:

x * y / z

wird interpretiert als:

( ( x * y ) / z )

Alle Vergleichsoperatoren haben die gleiche Priorität. Vergleichsoperatoren sind jedoch nicht assoziativ. Daher sind Klammern erforderlich, um Mehrdeutigkeiten aufzulösen. Beispiel:

(x < y) IS FALSE

Operatoren für den Elementzugriff

Operator Syntax Datentypen der Eingabe Datentyp des Ergebnisses Beschreibung
. expression.fieldname1... STRUCT
Typ T in fieldname1 gespeichert Dot-Operator. Kann für den Zugriff auf verschachtelte Felder verwendet werden, z. B. expression.fieldname1.fieldname2...
[ ] array_expression [position_keyword (int_expression ) ] Siehe ARRAY-Funktionen. Typ T in ARRAY gespeichert Position_keyword ist entweder OFFSET oder ORDINAL. Unter ARRAY-Funktionen finden Sie die beiden Funktionen, die diesen Operator verwenden.

Arithmetische Operatoren

Alle arithmetischen Operatoren akzeptieren die Eingabe des numerischen Typs T und der Ergebnistyp weist den Typ T auf, sofern in der nachfolgenden Beschreibung nichts anderes angegeben ist:

Name Syntax
Addition X + Y
Subtraktion X - Y
Multiplikation X * Y
Division X / Y
Unäres Minus - X

HINWEIS: Division durch Nulloperationen gibt einen Fehler zurück. Ziehen Sie die Funktion IEEE_DIVIDE oder SAFE_DIVIDE in Betracht, damit ein anderes Ergebnis zurückgegeben wird.

Ergebnistypen für Addition und Multiplikation:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

Ergebnistypen für Subtraktion:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

Ergebnistypen für Division:

 INT64FLOAT64
INT64FLOAT64FLOAT64
FLOAT64FLOAT64FLOAT64

Ergebnistypen für unäres Minus:

Datentyp der Eingabe Datentyp des Ergebnisses
INT64 INT64
FLOAT64 FLOAT64

Bitweiser Operator

Alle bitweisen Operatoren geben den gleichen Typ und die gleiche Länge wie der erste Operand zurück.

Name Syntax Datentyp der Eingabe Beschreibung
Bitweises NOT ~ X Ganzzahl oder BYTES Führt eine logische Negation auf jedem Bit durch und bildet das Einerkomplement des gegebenen Binärwerts.
Bitweises OR X | Y X: Ganzzahl oder BYTES
Y: gleicher Typ wie X
Nimmt zwei Bitmuster gleicher Länge und führt die logische inklusive OR-Operation bei jedem Paar der entsprechenden Bits durch. Dieser Operator gibt einen Fehler aus, wenn X- und Y-BYTES unterschiedlicher Länge sind.
Bitweises XOR X ^ Y X: Ganzzahl oder BYTES
Y: gleicher Typ wie X
Nimmt zwei Bitmuster gleicher Länge an und führt die logische exklusive OR-Operation bei jedem Paar der entsprechenden Bits durch. Dieser Operator gibt einen Fehler aus, wenn X- und Y-BYTES unterschiedlicher Länge sind.
Bitweises AND X & Y X: Ganzzahl oder BYTES
Y: gleicher Typ wie X
Nimmt zwei Bitmuster gleicher Länge und führt die logische AND-Operation bei jedem Paar der entsprechenden Bits durch. Dieser Operator gibt einen Fehler aus, wenn X- und Y-BYTES unterschiedlicher Länge sind.
Linksverschiebung X << Y X: Integer oder BYTES
Y: INT64
Verschiebt den ersten Operanden X nach links. Dieser Operator gibt 0 oder eine Bytesequenz von b'\x00' zurück, wenn der zweite Operand Y größer oder gleich der Bitlänge des ersten Operanden X ist (z. B. 64, wenn X den Typ INT64 hat). Dieser Operator gibt einen Fehler aus, wenn Y negativ ist.
Rechtsverschiebung X >> Y X: Integer oder BYTES
Y: INT64
Verschiebt den ersten Operanden X nach rechts. Dieser Operator führt keine Vorzeichenbit-Erweiterung bei einem Typ mit Vorzeichen durch (d. h. er füllt freie Bits auf der linken Seite mit 0). Dieser Operator gibt 0 oder eine Bytesequenz von b'\x00' zurück, wenn der zweite Operand Y größer oder gleich der Bitlänge des ersten Operanden X ist (z. B. 64, wenn X den Typ INT64 hat). Dieser Operator gibt einen Fehler aus, wenn Y negativ ist.

Logische Operatoren

Alle logischen Operatoren erlauben nur die BOOL-Eingabe.

Name Syntax Beschreibung
Logisches NOT NOT X Gibt FALSE zurück, wenn die Eingabe TRUE ist. Gibt TRUE zurück, wenn die Eingabe FALSE ist. Gibt ansonsten NULL zurück.
Logisches AND X AND Y Gibt FALSE zurück, wenn mindestens eine Eingabe FALSE ist. Gibt TRUE zurück, wenn sowohl X als auch Y TRUE ist. Gibt ansonsten NULL zurück.
Logisches OR X OR Y Gibt FALSE zurück, wenn X und Y beide FALSE sind. Gibt TRUE zurück, wenn mindestens eine Eingabe TRUE ist. Andernfalls wird NULL zurückgegeben.

Vergleichsoperator

Vergleiche geben immer BOOL zurück. Im Allgemeinen müssen dafür beide Operanden vom gleichen Typ sein. Wenn die Operanden einen unterschiedlichen Typ haben und Cloud Spanner SQL die Werte dieser Typen ohne Genauigkeitsverlust in einen allgemeinen Typ umwandeln kann, erzwingt Cloud Spanner SQL in der Regel für den Vergleich eine Umwandlung in diesen allgemeinen Typ. Cloud Spanner SQL erzwingt grundsätzlich die Umwandlung von Literalen in Nicht-Literale, sofern vorhanden. Vergleichbare Datentypen sind unter Datentypen definiert.

STRUCTs unterstützt nur vier Vergleichsoperatoren: gleich (=), ungleich (!= und <>) sowie IN.

Beim Vergleich dieser Datentypen gelten folgende Regeln:

  • FLOAT64: Alle Vergleiche mit NaN geben FALSE zurück, außer bei != und <>. Dafür wird TRUE zurückgegeben.
  • BOOL: FALSE ist kleiner als TRUE.
  • STRING: Strings werden von Codepunkt zu Codepunkt miteinander verglichen, d. h., der Vergleich kanonisch äquivalenter Strings wird nur dann zuverlässig als gleich ausgewertet, wenn sie zuerst normalisiert wurden.
  • NULL: Dafür gilt folgende Konvention: Jeder Vorgang mit einer NULL-Eingabe gibt NULL zurück.
Name Syntax Beschreibung
Kleiner als X < Y Gibt TRUE zurück, wenn X kleiner als Y ist.
Kleiner als oder gleich X <= Y Gibt TRUE zurück, wenn X kleiner oder gleich Y ist.
Größer als X > Y Gibt TRUE zurück, wenn X größer als Y ist.
Größer als oder gleich X >= Y Gibt TRUE zurück, wenn X größer oder gleich Y ist.
Gleich X = Y Gibt TRUE zurück, wenn X gleich Y ist.
Ungleich X != Y
X <> Y
Gibt TRUE zurück, wenn X ungleich Y ist.
BETWEEN X [NOT] BETWEEN Y AND Z Gibt TRUE zurück, wenn X in dem angegebenen Bereich [nicht] vorhanden ist. Das Ergebnis von "X BETWEEN Y AND Z" ist äquivalent mit "Y <= X AND X <= Z", aber X wird nur einmal in ersterem ausgewertet.
LIKE X [NOT] LIKE Y Überprüft, ob der STRING im ersten Operanden X mit einem vom zweiten Operanden Y angegebenen Muster übereinstimmt. Ausdrücke können diese Zeichen enthalten:
  • Ein Prozentzeichen "%" entspricht einer beliebigen Anzahl von Zeichen oder Byte
  • Ein Unterstrich "_" entspricht einem einzelnen Zeichen oder Byte
  • Sie können "\", "_" oder "%" mit zwei Backslashs maskieren. Beispiel: "\\%". Wenn Sie Rohstrings verwenden, ist nur ein einziger Backslash erforderlich. Beispiel: r"\%".
IN Mehrere – siehe unten Gibt FALSE zurück, wenn der rechte Operand leer ist. Gibt NULL zurück, wenn der linke Operand NULL ist. Gibt TRUE oder NULL, aber niemals FALSE zurück, wenn der rechte Operand NULL enthält. Argumente auf beiden Seiten von IN sind allgemeine Ausdrücke. Keiner der Operanden muss ein Literal sein, obwohl die Verwendung eines Literals auf der rechten Seite am häufigsten ist. X wird nur einmal ausgewertet.

Beim Testen von Werten, die einen STRUCT-Datentyp für Gleichheit haben, ist es möglich, dass ein oder mehrere Felder NULL sind. In solchen Fällen:

  • Wenn alle Nicht-NULL-Feldwerte gleich sind, gibt der Vergleich NULL zurück.
  • Wenn alle Nicht-NULL-Feldwerte ungleich sind, gibt der Vergleich FALSE zurück.

Die folgende Tabelle zeigt, wie STRUCT-Datentypen verglichen werden, wenn sie Felder aufweisen, die mit NULL bewertet werden.

Struct1 Struct2 Struct1 = Struct2
STRUCT(1, NULL) STRUCT(1, NULL) NULL
STRUCT(1, NULL) STRUCT(2, NULL) FALSE
STRUCT(1,2) STRUCT(1, NULL) NULL

IN-Operator

Der IN-Operator unterstützt die folgenden Syntaxen:

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

Argumente auf beiden Seiten des IN-Operators sind allgemeine Ausdrücke. Es ist üblich, Literale auf der rechten Seite des Ausdrucks zu verwenden. Das ist jedoch nicht erforderlich.

Die Semantik von:

x IN (y, z, ...)

ist gleichbedeutend mit:

(x = y) OR (x = z) OR ...

und die Unterabfrage und Arrayformen sind in ähnlicher Weise definiert.

x NOT IN ...

entspricht:

NOT(x IN ...)

In der Form UNNEST wird ein Arrayscan wie UNNEST in der Klausel FROM behandelt:

x [NOT] IN UNNEST(<array expression>)

Diese Form wird häufig mit ARRAY-Parametern verwendet. Beispiel:

x IN UNNEST(@array_parameter)

Hinweis: Das ARRAY NULL wird wie ein leeres ARRAY behandelt.

Weitere Informationen zur Verwendung dieser Syntax finden Sie im Thema Arrays.

Bei Verwendung des IN-Operators gilt folgende Semantik:

  • IN mit einem leeren Ausdruck auf der rechten Seite ist immer FALSE.
  • IN mit einem NULL-Ausdruck auf der linken Seite und einem nicht-leeren Ausdruck auf der rechten Seite ist immer NULL.
  • IN mit einer NULL in der IN-Liste kann nur TRUE oder NULL, niemals FALSE zurückgeben.
  • NULL IN (NULL) gibt NULL zurück
  • IN UNNEST(<NULL array>) gibt FALSE zurück (nicht NULL).
  • NOT IN mit NULL in der IN-Liste kann nur FALSE oder NULL, aber in keinem Fall TRUE zurückgeben.

IN kann unter Verwendung der STRUCT-Konstruktorsyntax mit mehrteiligen Schlüsseln verwendet werden. Beispiel:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

Weitere Informationen zu dieser Syntax enthält der Abschnitt Struct-Typ unter "Datentypen".

IS-Operator

IS-Operatoren geben TRUE oder FALSE für die Bedingung zurück, die sie testen. Im Gegensatz zu den unter Mathematische Funktionen definierten Funktionen IS_NF und IS_NAN geben sie nie NULL zurück, auch nicht bei NULL-Eingaben. Wenn NOT vorhanden ist, wird der Ausgabewert BOOL invertiert.

Funktions-Syntax Datentyp der Eingabe Datentyp des Ergebnisses Beschreibung

X IS [NOT] NULL
Jeder Werttyp BOOL Gibt TRUE zurück, wenn der Operand X als NULL ausgewertet wird. Ansonsten wird FALSE zurückgegeben.

X IS [NOT] TRUE
BOOL BOOL Gibt TRUE zurück, wenn der Operand BOOL als TRUE ausgewertet wird. Ansonsten wird FALSE zurückgegeben.

X IS [NOT] FALSE
BOOL BOOL Gibt TRUE zurück, wenn der BOOL-Operand als FALSE ausgewertet wird. Ansonsten wird FALSE zurückgegeben.

Verkettungsoperator

Der Verkettungsoperator kombiniert mehrere Werte zu einem einzigen Wert.

Funktionssyntax Datentyp der Eingabe Datentyp des Ergebnisses

STRING || STRING [ || ... ]
STRING STRING

BYTES || BYTES [ || ... ]
BYTES STRING

ARRAY<T> || ARRAY<T> [ || ... ]
ARRAY<T> ARRAY<T>

Bedingte Ausdrücke

Bedingte Ausdrücke erzwingen Einschränkungen für die Auswertungsreihenfolge ihrer Eingaben. Im Wesentlichen werden sie von links nach rechts nach dem Kurzschlussprinzip ausgewertet und zwar nur der gewählte Ausgabewert. Im Gegensatz dazu werden alle Eingaben für reguläre Funktionen vor Aufruf der Funktion ausgewertet. Die Kurzschlussauswertung in bedingten Ausdrücken kann für Fehlerbehandlung oder Leistungsabstimmung genutzt werden.

CASE-expr

CASE expr
  WHEN expr_to_match THEN result
  [ ... ]
  [ ELSE else_result ]
END

Beschreibung

Vergleicht expr mit expr_to_match jeder aufeinanderfolgenden WHEN - Klausel und gibt das erste Ergebnis zurück, bei dem dieser Vergleich "true" zurückgibt. Die verbleibenden WHEN-Klauseln und else_result werden nicht ausgewertet. Wenn der Vergleich expr = expr_to_match für alle WHEN-Klauseln "false" oder "NULL" zurückgibt, wird else_result zurückgegeben, sofern vorhanden. Falls nicht vorhanden, wird NULL zurückgegeben.

expr und expr_to_match können ein beliebiger Typ sein. Sie müssen implizit zu einem gemeinsamen Supertyp erzwungen werden können. Gleichheitsvergleiche werden für erzwungene Werte durchgeführt. Es gibt möglicherweise mehrere result - Typen. result- und else_result-Ausdrücke müssen zu einem gemeinsamen Supertyp gezwungen werden können.

Rückgabedatentyp

Supertyp von result[, ...] und else_result.

Beispiel

WITH Numbers AS
 (SELECT 90 as A, 2 as B UNION ALL
  SELECT 50, 8 UNION ALL
  SELECT 60, 6 UNION ALL
  SELECT 50, 10)
SELECT A, B,
  CASE A
    WHEN 90 THEN 'red'
    WHEN 50 THEN 'blue'
    ELSE 'green'
  END
  AS result
FROM Numbers

+------------------+
| A  | B  | result |
+------------------+
| 90 | 2  | red    |
| 50 | 8  | blue   |
| 60 | 6  | green  |
| 50 | 10 | blue   |
+------------------+

CASE

CASE
  WHEN condition THEN result
  [ ... ]
  [ ELSE else_result ]
  END

Beschreibung

Wertet die Bedingung jeder aufeinanderfolgenden WHEN - Klausel aus und gibt das erste Ergebnis zurück, wenn die Bedingung "true" zurückgibt; Alle verbleibenden WHEN - Klauseln und else_result werden nicht ausgewertet. Wenn alle Bedingungen "false" oder "NULL" sind, wird else_result zurückgegeben, falls vorhanden. Wenn nicht vorhanden, wird NULL zurückgegeben.

condition muss ein boolescher Ausdruck sein. Es gibt möglicherweise mehrere result - Typen. result- und else_result-Ausdrücke müssen implizit zu einem gemeinsamen Supertyp gezwungen werden können.

Rückgabedatentyp

Supertyp von result[, ...] und else_result.

Beispiel

WITH Numbers AS
 (SELECT 90 as A, 2 as B UNION ALL
  SELECT 50, 6 UNION ALL
  SELECT 20, 10)
SELECT A, B,
  CASE
    WHEN A > 60 THEN 'red'
    WHEN A > 30 THEN 'blue'
    ELSE 'green'
  END
  AS result
FROM Numbers

+------------------+
| A  | B  | result |
+------------------+
| 90 | 2  | red    |
| 50 | 6  | blue   |
| 20 | 10 | green  |
+------------------+

COALESCE

COALESCE(expr[, ...])

Beschreibung

Gibt den Wert des ersten Nicht-Null-Ausdrucks zurück. Die übrigen Ausdrücke werden nicht ausgewertet. Ein Eingabeausdruck kann einen beliebigen Typ haben. Es können mehrere Arten von Eingabeausdrücken vorhanden sein. Alle Eingabeausdrücke müssen implizit zu einem gemeinsamen Supertypen gezwungen werden können.

Rückgabedatentyp

Supertyp von expr [, ...].

Beispiele

SELECT COALESCE('A', 'B', 'C') as result

+--------+
| result |
+--------+
| A      |
+--------+
SELECT COALESCE(NULL, 'B', 'C') as result

+--------+
| result |
+--------+
| B      |
+--------+

IF

IF(expr, true_result, else_result)

Beschreibung

Wenn expr "true" ist, wird true_result zurückgegeben. Andernfalls wird else_result zurückgegeben. else_result wird nicht ausgewertet, wenn expr "true" ist. true_result wird nicht ausgewertet, wenn expr falsch oder NULL ist.

expr muss ein boolescher Ausdruck sein. true_result und else_result müssen zu einem gemeinsamen Supertyp gezwungen werden können.

Rückgabedatentyp

Supertyp von true_result und else_result.

Beispiel

WITH Numbers AS
 (SELECT 10 as A, 20 as B UNION ALL
  SELECT 50, 30 UNION ALL
  SELECT 60, 60)
SELECT
  A, B,
  IF( A<B, 'true', 'false') as result
FROM Numbers

+------------------+
| A  | B  | result |
+------------------+
| 10 | 20 | true   |
| 50 | 30 | false  |
| 60 | 60 | false  |
+------------------+

IFNULL

IFNULL(expr, null_result)

Beschreibung

Wenn expr NULL ist, wird null_result zurückgegeben. Andernfalls wird expr zurückgeben. Wenn expr nicht NULL ist, wird null_result nicht ausgewertet.

expr und null_result können ein beliebiger Typ sein und müssen implizit zu einem gemeinsamen Supertyp gezwungen werden können. Synonym für COALESCE(expr, null_result).

Rückgabedatentyp

Supertyp von expr oder null_result.

Beispiele

SELECT IFNULL(NULL, 0) as result

+--------+
| result |
+--------+
| 0      |
+--------+
SELECT IFNULL(10, 0) as result

+--------+
| result |
+--------+
| 10     |
+--------+

NULLIF

NULLIF(expr, expr_to_match)

Beschreibung

Gibt NULL zurück, wenn expr = expr_to_match "true" ist, andernfalls wird expr zurückgegeben.

expr und expr_to_match müssen implizit zu einem gemeinsamen Supertyp erzwungen werden können und vergleichbar sein.

NULLIF unterstützt keine STRUCT-Typen.

Rückgabedatentyp

Supertyp von expr und expr_to_match.

Beispiel

SELECT NULLIF(0, 0) as result

+--------+
| result |
+--------+
| NULL   |
+--------+
SELECT NULLIF(10, 0) as result

+--------+
| result |
+--------+
| 10     |
+--------+

Ausdruck-Unterabfragen

Es gibt vier Typen von Ausdruck-Unterabfragen, also von Unterabfragen, die als Ausdrücke verwendet werden. Ausdruck-Unterabfragen geben im Gegensatz zu einer Spalte oder Tabelle NULL oder einen einzelnen Wert zurück und müssen von Klammern umgeben sein. Weitere Informationen zu Unterabfragen finden Sie im Abschnitt Unterabfragen.

Unterabfragentyp Datentyp des Ergebnisses Beschreibung
Skalar Beliebiger Typ T Eine Unterabfrage in Klammern innerhalb eines Ausdrucks (z. B. in der SELECT-Liste oder WHERE-Klausel) wird als skalare Unterabfrage interpretiert. Die SELECT-Liste in einer skalaren Unterabfrage muss genau ein Feld haben. Wenn die Unterabfrage genau eine Zeile zurückgibt, ist dieser einzelne Wert das skalare Unterabfrageergebnis. Wenn die Unterabfrage keine Zeilen zurückgibt, ist der skalare Unterabfragenwert NULL. Wenn die Unterabfrage mehr als eine Zeile zurückgibt, schlägt die Abfrage mit einem Laufzeitfehler fehl. Wenn die Unterabfrage mit SELECT AS STRUCT geschrieben wird, kann sie mehrere Spalten enthalten. Der zurückgegebene Wert ist dann der erstellte STRUCT-Wert. Die Auswahl mehrerer Spalten ohne Verwendung von SELECT AS führt zu einem Fehler.
ARRAY ARRAY Kann SELECT AS STRUCT verwenden, um Arrays von Structs zu erstellen, und umgekehrt. Die Auswahl mehrerer Spalten ohne Verwendung von SELECT AS führt zu einem Fehler. Gibt ein leeres ARRAY zurück, wenn die Unterabfrage keine Zeilen zurückgibt. Gibt in keinem Fall ein NULL-ARRAY zurück.
IN BOOL Tritt in einem Ausdruck nach dem IN-Operator auf. Die Unterabfrage muss eine einzelne Spalte erzeugen, deren Typ mit dem Ausdruck auf der linken Seite des IN-Operators gleichheitskompatibel ist. Gibt FALSE zurück, wenn die Unterabfrage keine Zeilen zurückgibt. x IN () entspricht x IN (value, value, ...). Die vollständige Semantik finden Sie unter Vergleichsoperatoren im Abschnitt zum Operator IN.
EXISTS BOOL Gibt TRUE zurück, wenn die Unterabfrage eine oder mehrere Zeilen erzeugt hat. Gibt FALSE zurück, wenn die Unterabfrage Nullzeilen erzeugt. Gibt niemals NULL zurück. Im Gegensatz zu allen anderen Ausdruck-Unterabfragen gibt es keine Regeln über die Spaltenliste. Es können beliebig viele Spalten ausgewählt werden. Das Abfrageergebnis wird davon nicht beeinflusst.

Beispiele

In den folgenden Beispielen für Ausdruck-Unterabfragen wird davon ausgegangen, dass t.int_array vom Typ ARRAY<INT64> ist.

Typ Unterabfrage Datentyp des Ergebnisses Hinweise
Skalar (SELECT COUNT(*) FROM t.int_array) INT64  
(SELECT DISTINCT i FROM t.int_array i) INT64, möglicher Laufzeitfehler  
(SELECT i FROM t.int_array i WHERE i=5) INT64, möglicher Laufzeitfehler  
(SELECT ARRAY_AGG(i) FROM t.int_array i) ARRAY Verwendet die ARRAY_AGG-Aggregationsfunktion, um ein ARRAY zurückzugeben.
(SELECT 'xxx' a) STRING  
(SELECT 'xxx' a, 123 b) Fehler Gibt einen Fehler zurück, da es mehr als eine Spalte gibt.
(SELECT AS STRUCT 'xxx' a, 123 b) STRUCT  
(SELECT AS STRUCT 'xxx' a) STRUCT  
ARRAY ARRAY(SELECT COUNT(*) FROM t.int_array) ARRAY der Größe 1  
ARRAY(SELECT x FROM t) ARRAY  
ARRAY(SELECT 5 a, COUNT(*) b FROM t.int_array) Fehler Gibt einen Fehler zurück, da es mehr als eine Spalte gibt.
ARRAY(SELECT AS STRUCT 5 a, COUNT(*) b FROM t.int_array) ARRAY  
ARRAY(SELECT AS STRUCT i FROM t.int_array i) ARRAY Erstellt ein ARRAY von STRUCTs mit einem Feld.
ARRAY(SELECT AS STRUCT 1 x, 2, 3 x) ARRAY Gibt einen ARRAY von STRUCTs mit anonymen oder doppelten Feldern zurück.
ARRAY(SELECT AS TypeName SUM(x) a, SUM(y) b, SUM(z) c from t) array<TypeName> Auswahl eines benannten Typs. Nimmt an, dass TypeName ein STRUCT-Typ mit den Feldern a, b, c ist.
STRUCT (SELECT AS STRUCT 1 x, 2, 3 x) STRUCT Konstruiert einen STRUCT mit anonymen oder doppelten Feldern.
EXISTS EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
NOT EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
IN x IN (SELECT y FROM table WHERE z) BOOL  
x NOT IN (SELECT y FROM table WHERE z) BOOL  

Fehlerbehebungsfunktionen

Cloud Spanner SQL unterstützt die folgenden Fehlerbehebungsfunktionen.

ERROR

ERROR(error_message)

Beschreibung

Gibt einen Fehler zurück. Das Argument error_message ist ein STRING.

Cloud Spanner SQL behandelt ERROR auf die gleiche Weise wie alle Ausdrücke, die zu einem Fehler führen können. Es gibt keine spezielle Garantie für die Auswertungsreihenfolge.

Rückgabedatentyp

Cloud Spanner SQL leitet den Rückgabetyp im Kontext ab.

Beispiele

Im folgenden Beispiel wird durch die Abfrage eine Fehlermeldung zurückgegeben, wenn der Wert der Zeile keinem von zwei definierten Werten entspricht.

SELECT
  CASE
    WHEN value = 'foo' THEN 'Value is foo.'
    WHEN value = 'bar' THEN 'Value is bar.'
    ELSE ERROR(concat('Found unexpected value: ', value))
  END AS new_value
FROM (
  SELECT 'foo' AS value UNION ALL
  SELECT 'bar' AS value UNION ALL
  SELECT 'baz' AS value);

Found unexpected value: baz

Im folgenden Beispiel kann Cloud Spanner SQL die Funktion ERROR vor oder nach der Bedingung x > 0 auswerten, da Cloud Spanner SQL im Allgemeinen keine Reihenfolge zwischen WHERE-Klauselbedingungen garantiert und es keine speziellen Garantien für die Funktion ERROR gibt.

SELECT *
FROM (SELECT -1 AS x)
WHERE x > 0 AND ERROR('Example error');

Im nächsten Beispiel wertet die Klausel WHERE die Bedingung IF aus. Sie sorgt dafür, dass Cloud Spanner SQL die Funktion ERROR nur dann auswertet, wenn die Bedingung nicht erfüllt ist.

SELECT *
FROM (SELECT -1 AS x)
WHERE IF(x > 0, true, ERROR(FORMAT('Error: x must be positive but is %t', x)));'

Error: x must be positive but is -1