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

"Konversion" umfasst unter anderem die Prozesse Umwandeln und Erzwingen.

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 Konversionen mit eigenen Funktionsnamen, z. B. PARSE_DATE(). Weitere Informationen zu diesen Funktionen finden Sie unter Konversionsfunktionen.

Vergleichsdiagramm

In der Tabelle unten sind alle möglichen Konversionen für das Umwandeln (CAST) und das Erzwingen der Cloud Spanner SQL-Datentypen zusammengefasst. "Erzwingen in" gilt für alle Ausdrücke eines bestimmten Datentyps (beispielsweise einer Spalte).

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

Umwandeln

Die meisten Datentypen können mit der Funktion CAST von einem Typ in einen anderen übertragen werden. Eine Abfrage mit CAST kann fehlschlagen, wenn Cloud Spanner SQL die Umwandlung nicht ausführen kann. Wenn Sie Ihre Abfragen vor diesen Fehlern schützen möchten, können Sie SAFE_CAST verwenden. Weitere Informationen zu den Regeln für CAST, SAFE_CAST und andere Umwandlungsfunktionen finden Sie unter Konvertierungsfunktionen.

Erzwingen

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

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 der zugehörige Wert SELECT keine GROUP BY-Klausel hat oder wenn bestimmte Modifikatoren für Aggregatfunktionen Zeilen aus der zusammenzufassenden Gruppe filtern, ist es möglich, dass die Aggregatfunktion eine leere Gruppe zusammenfassen 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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
IGNORE NULLS oder RESPECT NULLS: Wenn IGNORE NULLS angegeben ist, werden die NULL-Werte aus dem Ergebnis ausgeschlossen. Wenn RESPECT NULLS angegeben ist, werden die NULL-Werte in das Ergebnis eingeschlossen. Wenn keiner der beiden Werte angegeben ist, werden die NULL-Werte in das Ergebnis eingeschlossen.
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

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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	FLOAT64	NUMERIC	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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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

Gibt die Anzahl der Zeilen in der Eingabe zurück.
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. Wenn DISTINCT vorhanden ist, kann expression nur einen Datentyp haben, der gruppierbar ist.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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

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

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

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

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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Sonderfälle:

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.

Alle numerischen Typen werden unterstützt. Wenn die Eingabe NUMERIC ist, kann die interne Aggregation mit der endgültigen Ausgabe in ein FLOAT64 umgewandelt werden. Andernfalls wird die Eingabe vor der Aggregation in ein FLOAT64 konvertiert, was zu einem potenziell instabilen Ergebnis führen kann.

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

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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.

Optionale Klauseln

Die Klauseln werden in folgender Reihenfolge angewendet:

DISTINCT: Jeder unterschiedliche Wert von expression fließt nur einmal in das Ergebnis ein.
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.

Umrechnungsfunktionen

Cloud Spanner SQL unterstützt die folgenden Konvertierungsfunktionen. Diese Datentyp-Konversionen sind explizit. Einige Konversionen können jedoch implizit erfolgen. Weitere Informationen zur impliziten und expliziten Konversionen finden Sie hier.

CAST-Übersicht

CAST(expression AS typename)

Beschreibung

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

Bei Verwendung von CAST kann eine Abfrage fehlschlagen, wenn Cloud Spanner SQL die Umwandlung nicht durchführen kann. Wenn Sie Ihre Abfragen vor diesen Fehlern schützen möchten, können Sie SAFE_CAST verwenden.

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.

Beispiele

Die folgende Abfrage führt zu "true", wenn x gleich 1 ist, "false" für jeden anderen Nicht-NULL-Wert und NULL, wenn x gleich NULL ist.

CAST(x=1 AS STRING)

ALS ARRAY UMWANDELN

CAST(expression AS ARRAY<element_type>)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in ARRAY. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

ARRAY

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
ARRAY	ARRAY	Muss exakt derselbe ARRAY-Typ sein.

ALS BOOL UMWANDELN

CAST(expression AS BOOL)

Beschreibung

Cloud Spanner SQL unterstützt das Streamen von BOOL. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

INT64
BOOL
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
INT64	BOOL	Gibt `FALSE` zurück, wenn `x` gleich `0` ist, ansonsten `TRUE`.
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.

ALS BYTES UMWANDELN

CAST(expression AS BYTES)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in BYTES. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

BYTES
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
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.

ALS DATUM UMWANDELN

CAST(expression AS DATE)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in DATE. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

STRING
TIMESTAMP

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
STRING	DATE	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.
TIMESTAMP	DATE	Beim Umwandeln eines Zeitstempels in ein Datum wird der Zeitstempel gemäß der Standardzeitzone effektiv gekürzt.

ALS FLOAT64 UMWANDELN

CAST(expression AS FLOAT64)

Beschreibung

Cloud Spanner SQL unterstützt das Streamen in Gleitkommatypen. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

INT64
FLOAT64
NUMERIC
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
INT64	FLOAT64	Gibt einen annähernden, aber möglicherweise keinen exakten Gleitkommawert zurück.
NUMERIC	FLOAT64	NUMERIC wird in die nächste Gleitkommazahl konvertiert, was mit einem Genauigkeitsverlust verbunden sein kann.
STRING	FLOAT64	Gibt `x` als Gleitkommawert zurück und interpretiert ihn so, als hätte er die gleiche Form wie ein gültiges Gleitkommaliteral. Unterstützt auch Umwandlungen von `"[+,-]inf"` zu `[,-]Infinity`, `"[+,-]infinity"` zu `[,-]Infinity` und von `"[+,-]nan"` zu `NaN`. Bei der Konversion wird die Groß-/Kleinschreibung nicht beachtet.

ALS INT64 UMWANDELN

CAST(expression AS INT64)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in Ganzzahltypen. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

INT64
FLOAT64
NUMERIC
BOOL
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
FLOAT64	INT64	Gibt den nächstgelegenen ganzzahligen Wert zurück. Halbe Zahlen wie 1,5 oder -0,5 runden von 0 weg.
BOOL	INT64	Gibt `1` zurück, wenn `x` gleich `TRUE` ist, ansonsten `0`.
STRING	INT64	Ein Hexadezimalstring kann in eine Ganzzahl umgewandelt werden. Beispiel: `0x123` zu `291` oder `-0x123` zu `-291`.

Beispiele

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       |
+-----------+------------+

ALS NUMERIC UMWANDELN

CAST(expression AS NUMERIC)

Beschreibung

Cloud Spanner SQL unterstützt casting zu NUMERIC. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

INT64
FLOAT64
NUMERIC
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
FLOAT64	NUMERIC	Die Gleitkommazahl wird kaufmännisch gerundet. Beim Umwandeln von `NaN`, `+inf` oder `-inf` wird ein Fehler zurückgegeben. Beim Umwandeln eines Werts außerhalb des Bereichs `NUMERIC` wird ein Überlauffehler zurückgegeben.
STRING	NUMERIC	Das in `STRING` enthaltene numerische Literal darf die maximale Genauigkeit oder den maximalen Bereich des Typs `NUMERIC` nicht überschreiten. Andernfalls tritt ein Fehler auf. Wenn die Anzahl der Nachkommastellen größer als neun ist, wird der resultierende `NUMERIC`-Wert kaufmännisch gerundet, sodass neun Nachkommastellen übrig bleiben.

ALS STRING UMWANDELN

CAST(expression AS STRING)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in STRING. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

INT64
FLOAT64
NUMERIC
BOOL
BYTES
DATE
TIMESTAMP
STRING

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
FLOAT64	STRING	Gibt eine ungefähre Stringdarstellung zurück.
BOOL	STRING	Gibt `"true"` zurück, wenn `x` gleich `TRUE` ist, ansonsten `"false"`.
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.
DATE	STRING	Die Umwandlung von einem Datumstyp in einen String ist unabhängig von der Zeitzone und erfolgt in der Form `YYYY-MM-DD`.
TIMESTAMP	STRING	Beim Umwandeln von Zeitstempeltypen in Strings wird der Zeitstempel mit der Standardzeitzone "America/Los_Angeles" interpretiert. Wie viele Stellen für Sekundenbruchteile generiert werden, hängt von der Anzahl der angehängten Nullen im Sekundenbruchteilbereich ab. Die Funktion CAST schneidet null, drei oder sechs Stellen ab.

Beispiele

CAST(CURRENT_DATE() AS STRING) AS current_date

+---------------+
| current_date  |
+---------------+
| 2021-03-09    |
+---------------+

ALS STRUCT UMWANDELN

CAST(expression AS STRUCT)

Beschreibung

Cloud Spanner SQL unterstützt casting zu STRUCT. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

STRUCT

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
STRUCT	STRUCT	Zulässig, wenn folgende Bedingungen erfüllt sind: Die beiden STRUCTs haben dieselbe Feldanzahl. Die ursprünglichen STRUCT-Feldtypen können explizit in die entsprechenden Ziel-STRUCT-Feldtypen (wie nach Feldreihenfolge, nicht nach Feldname definiert) umgewandelt werden.

ALS TIMESTAMP UMWANDELN

CAST(expression AS TIMESTAMP)

Beschreibung

Cloud Spanner SQL unterstützt das Übertragen in TIMESTAMP. Der Parameter expression kann einen Ausdruck für diese Datentypen darstellen:

STRING
TIMESTAMP

Konversionsregeln

Von	Zu	Regel(n) beim Umwandeln von `x`
STRING	TIMESTAMP	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 Zeitzone enthalten. Wenn in `string_expression` eine Zeitzone vorhanden ist, wird diese Zeitzone für die Konversion verwendet, andernfalls gilt die Standardzeitzone "America/Los_Angeles". Wenn der String weniger als sechs Ziffern hat, dann 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.
DATE	TIMESTAMP	Bei der Umwandlung eines Datums in einen Zeitstempel wird als Uhrzeit für `date_expression` Mitternacht (Tagesbeginn) in der Standardzeitzone "America/Los_Angeles" verwendet.

SAFE_CAST

SAFE_CAST(expression AS typename)

Beschreibung

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, gibt jedoch NULL zurück, anstatt einen Fehler auszulösen.

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.

Weitere Konversionsfunktionen

Weitere Informationen zu diesen Konversionsfunktionen finden Sie an anderer Stelle in der Dokumentation:

Konversionsfunktionen	Von	To
ARRAY_TO_STRING	ARRAY	STRING
DATE	Verschiedene Datentypen	DATE
FROM_BASE32	STRING	BYTEs
FROM_BASE64	STRING	BYTES
FROM_HEX	STRING	BYTES
PARSE_DATE	STRING	DATE
PARSE_TIMESTAMP	STRING	TIMESTAMP
SAFE_CONVERT_BYTES_TO_STRING	BYTES	STRING
STRING	TIMESTAMP	STRING
TIMESTAMP	Verschiedene Datentypen	TIMESTAMP
TO_BASE32	BYTES	STRING
TO_BASE64	BYTES	STRING
TO_HEX	BYTES	STRING

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 für den größten negativen Eingabewert, der nicht positiv dargestellt wird.

X	ABS(X)
25	25
-25	25
`+inf`	`+inf`
`-inf`	`+inf`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

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.

X	SIGN(X)
25	+1
0	0
-25	-1
NaN	NaN

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

IS_INF

IS_INF(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert positiv oder negativ unendlich ist.

Gibt FALSE für NUMERIC-Eingaben zurück, da NUMERIC nicht INF sein kann.

X	IS_INF(X)
`+inf`	`TRUE`
`-inf`	`TRUE`
25	`FALSE`

IS_NAN

IS_NAN(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert ein NaN-Wert ist.

Gibt FALSE für NUMERIC-Eingaben zurück, da NUMERIC nicht NaN sein kann.

X	IS_NAN(X)
`NaN`	`TRUE`
25	`FALSE`

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 für die Division durch null oder Überlauf.

X	J	IEEE_DIVIDE(X, Y)
20.0	4.0	5,0
0,0	25.0	0,0
25.0	0,0	`+inf`
-25.0	0,0	`-inf`
0,0	0,0	`NaN`
0,0	`NaN`	`NaN`
`NaN`	0,0	`NaN`
`+inf`	`+inf`	`NaN`
`-inf`	`-inf`	`NaN`

SQRT

SQRT(X)

Beschreibung

Berechnet die Quadratwurzel aus X. Generiert einen Fehler, wenn X kleiner als 0 ist.

X	SQRT(X)
`25.0`	`5.0`
`+inf`	`+inf`
`X < 0`	Fehler

Rückgabedatentyp

NUMERIC wird nicht direkt als Eingabe unterstützt. Sie müssen zuerst NUMERIC explizit in FLOAT64 umwandeln. Die Ausgabe lautet FLOAT64.

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.

X	J	POW(X, Y)
2.0	3,0	8.0
1,0	Beliebiger Wert, einschließlich `NaN`	1,0
Beliebiger Wert, einschließlich `NaN`	0	1,0
-1,0	`+inf`	1,0
-1,0	`-inf`	1,0
ABS (X) < 1	`-inf`	`+inf`
ABS (X) > 1	`-inf`	0,0
ABS (X) < 1	`+inf`	0,0
ABS (X) > 1	`+inf`	`+inf`
`-inf`	Y < 0	0,0
`-inf`	Y > 0	`-inf`, wenn Y eine ungerade Ganzzahl ist, sonst `+inf`
`+inf`	Y < 0	0
`+inf`	Y > 0	`+inf`
Endlicher Wert < 0	Keine Ganzzahl	Fehler
0	Endlicher Wert < 0	Fehler

Rückgabedatentyp

Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUT	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

POWER

POWER(X, Y)

Beschreibung

Synonym für POW(X, Y).

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.

X	EXP(X)
0,0	1,0
`+inf`	`+inf`
`-inf`	0,0

Rückgabedatentyp

NUMERIC wird nicht direkt als Eingabe unterstützt. Sie müssen zuerst NUMERIC explizit in FLOAT64 umwandeln. Die Ausgabe lautet FLOAT64.

LN

LN(X)

Beschreibung

Berechnet den natürlichen Logarithmus von X. Generiert einen Fehler, wenn X kleiner als oder gleich null ist.

X	LN(X)
1,0	0,0
`+inf`	`+inf`
`X < 0`	Fehler

Rückgabedatentyp

NUMERIC wird nicht direkt als Eingabe unterstützt. Sie müssen zuerst NUMERIC explizit in FLOAT64 umwandeln. Die Ausgabe lautet FLOAT64.

LOG

LOG(X [, Y])

Beschreibung

Wenn nur X vorhanden ist, dann ist LOG ein Synonym für LN. Ist Y ebenfalls vorhanden, berechnet LOG den Logarithmus von X zur Basis Y.

X	Y	LOG(X, Y)
100,0	10,0	2.0
`-inf`	Beliebiger Wert	`NaN`
Beliebiger Wert	`+inf`	`NaN`
`+inf`	0.0 < Y < 1.0	`-inf`
`+inf`	Y > 1,0	`+inf`
X <= 0	Beliebiger Wert	Fehler
Beliebiger Wert	Y <= 0	Fehler
Beliebiger Wert	1,0	Fehler

Rückgabedatentyp

NUMERIC wird nicht direkt als Eingabe unterstützt. Sie müssen zuerst NUMERIC explizit in FLOAT64 umwandeln. Die Ausgabe lautet FLOAT64.

LOG10

LOG10(X)

Beschreibung

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

X	LOG10(X)
100,0	2.0
`-inf`	`NaN`
`+inf`	`NaN`
X <= 0	Fehler

Rückgabedatentyp

NUMERIC wird nicht direkt als Eingabe unterstützt. Sie müssen zuerst NUMERIC explizit in FLOAT64 umwandeln. Die Ausgabe lautet FLOAT64.

GREATEST

GREATEST(X1,...,XN)

Beschreibung

Der größte Wert wird unter X1,…,XN gemäß Kleiner-als-Vergleich (<) zurückgegeben. Wenn Teile von X1,...,XN NULL sind, ist der Rückgabewert NULL.

X1,...,XN	GREATEST(X1,...,XN)
3,5,1	5

Rückgabedatentypen

Der Datentyp der Eingabewerte.

LEAST

LEAST(X1,...,XN)

Beschreibung

Der kleinste Wert wird unter X1,…,XN gemäß Größer-als-Vergleich (>) zurückgegeben. Wenn Teile von X1,...,XN NULL sind, ist der Rückgabewert NULL.

X1,...,XN	LEAST(X1,...,XN)
3,5,1	1

Rückgabedatentypen

Der Datentyp der Eingabewerte.

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. Wenn beide Eingaben NUMERIC sind und das Ergebnis ist vom Typ Überlauf, gibt es einen numeric overflow-Fehler zurück.

X	J	DIV(X, Y)
20	4	5
0	20	0
20	0	Fehler

Rückgabedatentyp

Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUT	INT64	NUMERIC
INT64	INT64	NUMERIC
NUMERIC	NUMERIC	NUMERIC

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Beschreibung

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

X	J	SAFE_DIVIDE(X, Y)
20	4	5
0	20	`0`
20	0	`NULL`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Beschreibung

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

X	J	SAFE_MULTIPLY(X, Y)
20	4	80

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_NEGATE

SAFE_NEGATE(X)

Beschreibung

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

X	SAFE_NEGATE(X)
+1	-1
-1	+1
0	0

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

SAFE_ADD

SAFE_ADD(X, Y)

Beschreibung

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

X	J	SAFE_ADD(X, Y)
5	4	9

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Beschreibung

Gibt das Ergebnis von X minus Y zurück. Entspricht dem Subtraktionsoperator (-), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

X	J	SAFE_SUBTRACT(X, Y)
5	4	1

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

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.

X	J	MOD(X, Y)
25	12	1
25	0	Fehler

Rückgabedatentyp

Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUT	INT64	NUMERIC
INT64	INT64	NUMERIC
NUMERIC	NUMERIC	NUMERIC

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.

X	ROUND(X)
2.0	2,0
2,3	2.0
2,8	3,0
2,5	3,0
-2,3	-2,0
-2,8	-3,0
-2,5	-3,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	FLOAT64	NUMERIC	FLOAT64

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.

X	TRUNC(X)
2.0	2,0
2,3	2.0
2,8	2.0
2,5	2.0
-2,3	-2,0
-2,8	-2,0
-2,5	-2,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	FLOAT64	NUMERIC	FLOAT64

CEIL

CEIL(X)

Beschreibung

Gibt den kleinsten Integralwert zurück, der nicht kleiner als X ist.

X	CEIL(X)
2.0	2,0
2,3	3,0
2,8	3,0
2,5	3,0
-2,3	-2,0
-2,8	-2,0
-2,5	-2,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	FLOAT64	NUMERIC	FLOAT64

CEILING

CEILING(X)

Beschreibung

Synonym von CEIL(X)

FLOOR

FLOOR(X)

Beschreibung

Gibt den größten Integralwert zurück, der nicht größer als X ist.

X	FLOOR(X)
2,0	2,0
2,3	2.0
2,8	2.0
2,5	2.0
-2,3	-3,0
-2,8	-3,0
-2,5	-3,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Rückgabedatentyp

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	FLOAT64	NUMERIC	FLOAT64

COS

COS(X)

Beschreibung

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

X	COS(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

COSH

COSH(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	COSH(X)
`+inf`	`+inf`
`-inf`	`+inf`
`NaN`	`NaN`

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.

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ACOS(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	Fehler
X > 1	Fehler

ACOSH

ACOSH(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ACOSH(X)
`+inf`	`+inf`
`-inf`	`NaN`
`NaN`	`NaN`
X < 1	Fehler

SIN

SIN(X)

Beschreibung

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

X	SIN(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

SINH

SINH(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	SINH(X)
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

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.

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ASIN(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	Fehler
X > 1	Fehler

ASINH

ASINH(X)

Beschreibung

Berechnet den inversen hyperbolischen Sinus von X. Scheitert nie.

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ASINH(X)
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

TAN

TAN(X)

Beschreibung

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

X	TAN(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

TANH

TANH(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	TANH(X)
`+inf`	1,0
`-inf`	-1,0
`NaN`	`NaN`

ATAN

ATAN(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ATAN(X)
`+inf`	π/2
`-inf`	-π/2
`NaN`	`NaN`

ATANH

ATANH(X)

Beschreibung

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

Wenn X NUMERIC ist, ist die Ausgabe FLOAT64.

X	ATANH(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	Fehler
X > 1	Fehler

ATAN2

ATAN2(X, Y)

Beschreibung

Berechnet den Hauptwert des inversen Tangens von X/Y unter Verwendung der Vorzeichen der beiden Argumente, um den Quadranten zu bestimmen. Der zurückgegebene Wert liegt im Bereich [-π, π].

Wenn Y NUMERIC ist, ist die Ausgabe FLOAT64.

X	J	ATAN2(X, Y)
`NaN`	Beliebiger Wert	`NaN`
Beliebiger Wert	`NaN`	`NaN`
0,0	0,0	0,0
Positiver endlicher Wert	`-inf`	π
Negativer endlicher Wert	`-inf`	-π
Endlicher Wert	`+inf`	0,0
`+inf`	Endlicher Wert	π/2
`-inf`	Endlicher Wert	-π/2
`+inf`	`-inf`	¾π
`-inf`	`-inf`	-¾π
`+inf`	`+inf`	π/4
`-inf`	`+inf`	-π/4

Hash-Funktionen

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

Beschreibung

Berechnet den Fingerabdruck der STRING- oder BYTES-Eingabe mit der Fingerprint64-Funktion aus der Open-Source-FarmHash-Bibliothek. 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 entweder STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Byte.

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 entweder STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Byte.

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 entweder STRING oder BYTES sein. Die Stringversion behandelt die Eingabe als ein Array von Byte.

Diese Funktion gibt 64 Bytes zurück.

Rückgabetyp

BYTES

Beispiel

SELECT SHA512("Hello World") as sha512;

Stringfunktionen

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

Funktionen, die Positionswerte wie STRPOS zurückgeben, codieren diese Positionen im Format INT64. Der Wert 1 bezieht sich auf das erste Zeichen (oder Byte), 2 bezieht sich auf das zweite Zeichen (oder Byte) und so weiter. Der Wert 0 gibt einen ungültigen Index an. Bei der Nutzung von Daten vom Typ STRING 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 STRING- oder BYTES-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 von STRING 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

Gibt für ein Array von erweiterten ASCII-Codepunkten (ARRAY von INT64) 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;

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'AbCd' is the result.
+----------+
| bytes    |
+----------+
| QWJDZA== |
+----------+

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;

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'Grfg Fgevat!' is the result.
+------------------+
| encoded_string   |
+------------------+
| R3JmZyBGZ2V2YXQh |
+------------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Beschreibung

Gibt für ein Array von Unicode-Codepunkten (ARRAY von INT64) einen STRING-Wert zurück. Wenn ein Codepunkt 0 ist, wird im STRING kein Zeichen dafür zurückgegeben.

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

Rückgabetyp

STRING

Beispiele

Es folgen einfache Beispiele, in denen CODE_POINTS_TO_STRING verwendet wird.

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

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

SELECT CODE_POINTS_TO_STRING([97, 0, 0xF9B5]) AS string;

+--------+
| string |
+--------+
| a例    |
+--------+

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

+--------+
| string |
+--------+
| NULL   |
+--------+

Das folgende Beispiel berechnet die Häufigkeit der Buchstaben in einer Gruppe von Wörtern.

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

Verwendet zwei STRING- oder BYTES-Werte. 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 generiert einen STRING aus einem Formatstring, der null oder mehr Formatspezifizierer enthält, zusammen mit einer Liste variabler Länge mit zusätzlichen Argumenten, die mit den Formatspezifizierern übereinstimmt. 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 FORMAT()-Syntax verwendet einen Formatstring sowie eine Argumentliste mit variabler Länge 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 inf nan	NUMERIC FLOAT64
`F`	Dezimalschreibweise: [-](Ganzzahl).(Bruchteil) für endliche Werte, in Großbuchstaben für nicht endliche Werte	392.650000 INF NAN	NUMERIC FLOAT64
`e`	Exponentialschreibweise (Mantisse/Exponent), Kleinbuchstaben	3.926500e+02 inf nan	NUMERIC FLOAT64
`E`	Exponentialschreibweise (Mantisse/Exponent), Großbuchstaben	3.926500E+02 INF NAN	NUMERIC 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	NUMERIC FLOAT64
`G`	Entweder Dezimal- oder wissenschaftliche Schreibweise, je nach Exponent des Eingabewerts und angegebener Genauigkeit. Großschreibung. Weitere Informationen finden Sie unter %g- und %G-Verhalten.	392.65 3.9265E+07 INF NAN	NUMERIC FLOAT64
`s`	String	Beispiel	STRING
`t`	Gibt einen druckbaren String zurück, der den Wert darstellt. Entspricht häufig der Umwandlung des Arguments in `STRING`. Informationen dazu finden Sie unter %t- und %T-Verhalten.	Beispiel 01‑01-2014	<any>
`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 dazu finden Sie unter %t- und %T-Verhalten.	'Beispiel' b'bytes Beispiel' 1234 2.3 Datum '2014‑01‑01'	<any>
`%`	'%%' 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 von links mit Nullen (0) statt mit Leerzeichen 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 Wert, der ausgegeben werden soll, 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 nicht im Formatstring angegeben, sondern als zusätzliches Ganzzahlargument vor dem Argument, das formatiert werden muss, vorangestellt.

Präzision

Präzision	Beschreibung
`.`<Anzahl>	Für die Ganzzahlspezifizierer "%d", "%i", "%o", "%u", "%x" und "%X" gibt die Genauigkeit die Mindestanzahl an Ziffern an, die geschrieben werden sollen. 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" ist dies die Anzahl an Ziffern, die nach dem Dezimalzeichen ausgegeben werden sollen. Der Standardwert ist 6. Für die Spezifizierer "%g" und "%G" ist dies die Anzahl an signifikanten Ziffern, die ausgegeben werden sollen, bevor die Nullen nach dem Dezimalzeichen entfernt werden. Der Standardwert ist 6.
`.*`	Die Präzision wird nicht im Formatstring angegeben, sondern als zusätzliches Ganzzahlargument dem Argument, das formatiert werden soll, 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. Die Werte für Breite, Präzision und Flags funktionieren wie bei %s. Die Breite ist die Mindestbreite und der STRING wird auf diese Größe aufgefüllt. Die Präzision ist die maximale Breite des angezeigten Inhalts 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 ist in folgender Weise formatiert:

Typ	%t	%T
`NULL` eines beliebigen Typs	NULL	NULL
INT64	123	123
NUMERIC	123,0 (immer mit ,0)	NUMERIC "123,0"
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 Ausgabe-STRING von NULL. Alle anderen Argumente werden in diesem Fall ignoriert.

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

Allerdings gibt es dafür Ausnahmen. Wenn der Formatspezifizierer %t oder %T ist (beide generieren STRINGs, die effektiv mit CAST und der Literalwertsemantik übereinstimmen), generiert ein STRING-Wert den String "NULL" (ohne Anführungszeichen) im Ergebnis-NULL. Ein Beispiel dafür ist die folgende 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 (in Klein- oder 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, die keine Nicht-String-Literaldarstellungen haben.

FROM_BASE32

FROM_BASE32(string_expr)

Beschreibung

Wandelt den base32-codierten Eingabe-string_expr in das BYTES-Format um. Zum Umwandeln von BYTES in einen base32-codierten STRING verwenden Sie TO_BASE32.

Rückgabetyp

BYTES

Beispiel

SELECT FROM_BASE32('MFRGGZDF74======') AS byte_data;

-- Note that the result of FROM_BASE32 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| YWJjZGX/  |
+-----------+

FROM_BASE64

FROM_BASE64(string_expr)

Beschreibung

Wandelt den base64-codierten Eingabe-string_expr in das BYTES-Format um. Zum Umwandeln von BYTES in einen base64-codierten STRING verwenden Sie TO_BASE64.

Es gibt mehrere gängige base64-Codierungen, die sich darin unterscheiden, mit welchem Alphabet aus 65 ASCII-Zeichen die 64 Ziffern und das Auffüllen codiert werden. Weitere Informationen finden Sie unter RFC 4648. Diese Funktion erwartet das Alphabet [A-Za-z0-9+/=].

Rückgabetyp

BYTES

Beispiel

SELECT FROM_BASE64('/+A=') AS byte_data;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| /+A=      |
+-----------+

Wenn Sie mit einer Codierung mit einem anderen base64-Standard arbeiten möchten, müssen Sie unter Umständen FROM_BASE64 mit der Funktion REPLACE erstellen. Die URL-sichere und dateinamen-sichere base64url-Codierung, die häufig von Webprogrammierern verwendet wird, verwendet -_= statt +/= als letzte Zeichen. Um einen base64url-codierten String zu decodieren, ersetzen Sie + und / durch - bzw. _.

SELECT FROM_BASE64(REPLACE(REPLACE("_-A=", "-", "+"), "_", "/")) AS binary;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+--------+
| binary |
+--------+
| /+A=   |
+--------+

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 an Zeichen enthält, verhält sich die Funktion so, als würde die Eingabe eine zusätzliche führende 0 enthalten. Zum Umwandeln von BYTES in einen hexadezimal codierten STRING verwenden Sie TO_HEX.

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 STRING- oder BYTES-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 STRING- oder BYTES-Wert zurück, der aus original_value mit vorangestelltem pattern besteht. Die return_length ist ein INT64-Wert, der die Länge des zurückgegebenen Werts angibt. Wenn original_value vom Typ BYTES ist, dann stellt return_length die Anzahl der Byte dar. Wenn original_value vom Typ STRING ist, dann gibt return_length die Anzahl der Zeichen wieder.

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 den Wert NULL hat, 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    | len | 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    | len | pattern | 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               | len | 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               | len | pattern | 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.

BYTES-Argumente werden 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 partiell mit dem regulären regexp-Ausdruck übereinstimmt.

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 entweder aus 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 regexp-Ausdruck ü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 STRING- oder BYTES-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 gleich 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 den umgekehrten Wert der STRING- oder BYTES-Eingabe 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 STRING- oder BYTES-Wert zurück, der aus dem original_value mit angehängtem pattern besteht. Der Parameter return_length ist ein INT64-Wert, der die Länge des zurückgegebenen Werts angibt. Wenn für original_value der Typ BYTES gilt, dann ist return_length die Anzahl der Byte. Wenn für original_value der Typ STRING gilt, 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 original_value, return_length oder pattern den Wert NULL hat, 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    | len | 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    | len | pattern | 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               | len | 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               | len | pattern | 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 BYTES-Sequenz in 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 generiert ein Array von UTF-8-Zeichen für STRING-Werte und ein Array von BYTES für BYTES-Werte.

Das Aufteilen eines leeren STRING gibt ein ARRAY aus einem einzelnen 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

Verwendet zwei STRING- oder BYTES-Werte. 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(value1, value2)

Beschreibung

Verwendet zwei STRING- oder BYTES-Werte. Gibt den 1-basierten Index des ersten Vorkommens von value2 innerhalb von value1 zurück. Gibt 0 zurück, wenn value2 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 STRING- oder BYTES-Werts zurück. Das Argument position ist eine Ganzzahl, die die Startposition des Teilstrings angibt, wobei Position = 1 das erste Zeichen oder Byte festlegt. Das Argument length ist die maximale Anzahl an Zeichen für STRING-Argumente oder an 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 vom linken Ende des STRING (position = 0 oder position < -LENGTH(value)), startet die Funktion ab Position = 1. Wenn length die Länge von value überschreitet, gibt die Funktion weniger als die Anzahl der length-Zeichen zurück.

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_BASE32

TO_BASE32(bytes_expr)

Beschreibung

Wandelt eine Sequenz aus BYTES in einen base32-codierten STRING um. Zum Konvertieren eines base32-codierten STRING in BYTES verwenden Sie FROM_BASE32.

Rückgabetyp

STRING

Beispiel

SELECT TO_BASE32(b'abcde\xFF') AS base32_string;

+------------------+
| base32_string    |
+------------------+
| MFRGGZDF74====== |
+------------------+

TO_BASE64

TO_BASE64(bytes_expr)

Beschreibung

Wandelt eine Sequenz aus BYTES in einen base64-codierten STRING um. Zum Konvertieren eines base64-codierten STRING in BYTES verwenden Sie FROM_BASE64.

Rückgabetyp

STRING

Beispiel

SELECT TO_BASE64(b'\377\340') AS base64_string;

+---------------+
| base64_string |
+---------------+
| /+A=          |
+---------------+

Wenn Sie mit einer Codierung mit einem anderen base64-Standard arbeiten möchten, müssen Sie unter Umständen TO_BASE64 mit der Funktion REPLACE erstellen. Die URL-sichere und dateinamen-sichere base64url-Codierung, die häufig von Webprogrammierern verwendet wird, verwendet -_= statt +/= als letzte Zeichen. Um einen base64url-codierten String zu codieren, ersetzen Sie - und _ durch + bzw. /.

SELECT REPLACE(REPLACE(TO_BASE64(b"\377\340"), "+", "-"), "/", "_") as websafe_base64;

+----------------+
| websafe_base64 |
+----------------+
| _-A=           |
+----------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Beschreibung

Gibt für einen Wert ein INT64-Array 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].
Wenn value ein BYTES-Wert ist, stellt jedes Element im Array einen erweiterten ASCII-Zeichenwert im Bereich von [0, 255] dar.

Informationen zur Umwandlung eines Arrays von Codepunkten in STRING oder 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]        |
+------------------+------------------------+

Im folgenden Beispiel wird der Unterschied zwischen einem BYTES-Ergebnis und einem STRING-Ergebnis veranschaulicht.

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 von zwei Elementen zurück, während die STRING-Version ein Array aus einem einzelnen 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. Zum Konvertieren eines hexadezimal codierten STRING in BYTES verwenden Sie FROM_HEX.

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. Wenn das erste Argument vom Typ BYTES ist, 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.

BYTES-Argumente werden 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.

Funktionsübersicht

Die folgenden Funktionen verwenden doppelte Anführungszeichen, um ungültige JSONPath-Zeichen zu maskieren: "a.b".

Dieses Verhalten entspricht dem ANSI-Standard.

JSON-Funktion	Beschreibung	Rückgabetyp
`JSON_QUERY`	Extrahiert einen JSON-Wert, z. B. ein Array oder Objekt oder einen skalaren JSON-formatierten Wert, wie einen String, eine Ganzzahl oder ein boolescher Wert.	JSON-formatierte `STRING`
`JSON_VALUE`	Extrahiert einen skalaren Wert. Ein skalarer Wert kann einen String, eine Ganzzahl oder einen booleschen Wert darstellen. Entfernt die äußeren Anführungszeichen und maskiert die Werte. Gibt einen SQL-`NULL` zurück, wenn ein Nicht-Skalarwert ausgewählt ist.	`STRING`

JSON_QUERY

JSON_QUERY(json_string_expr, json_path)

Beschreibung

Extrahiert einen JSON-Wert, z. B. ein Array oder Objekt oder einen skalaren JSON-formatierten Wert, wie einen String, eine Ganzzahl oder ein boolescher Wert. Wenn ein JSON-Schlüssel ungültige JSONPath-Zeichen verwendet, können Sie diese Zeichen mit doppelten Anführungszeichen maskieren.

json_string_expr: Ein String im JSON-Format. Beispiel:
```
{"class" : {"students" : [{"name" : "Jane"}]}}
```
json_path: Der JSONpath. Gibt den Wert oder die Werte an, die Sie aus dem JSON-formatierten String abrufen möchten. Wenn json_path eine null im JSON-Format zurückgibt, wird dies in eine NULL im SQL-Format konvertiert.

Wenn Sie nicht skalare Werte wie Arrays in die Extraktion aufnehmen möchten, verwenden Sie JSON_QUERY. Wenn Sie nur skalare Werte wie Strings, Ganzzahlen und boolesche Werte extrahieren möchten, verwenden Sie JSON_VALUE.

Rückgabetyp

Ein JSON-formatierter STRING

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"}] |
+------------------------------------+

JSON_VALUE

JSON_VALUE(json_string_expr, json_path)

Beschreibung

Extrahiert einen skalaren Wert und gibt ihn dann als String zurück. Ein skalarer Wert kann einen String, eine Ganzzahl oder einen booleschen Wert darstellen. Entfernt die äußeren Anführungszeichen und maskiert die Rückgabewerte. Wenn ein JSON-Schlüssel ungültige JSONPath-Zeichen verwendet, können Sie diese Zeichen mit doppelten Anführungszeichen maskieren.

json_string_expr: Ein String im JSON-Format. Beispiel:
```
{"class" : {"students" : [{"name" : "Jane"}]}}
```
json_path: Der JSONpath. Gibt den Wert oder die Werte an, die Sie aus dem JSON-formatierten String abrufen möchten. Wenn json_path einen JSON-null oder einen Nicht-Skalarwert zurückgibt, d. h., wenn json_path sich auf ein Objekt oder ein Array bezieht, dann gilt ein SQL-NULL. wird zurückgegeben.

Wenn Sie nur skalare Werte wie Strings, Ganzzahlen und boolesche Werte extrahieren möchten, verwenden Sie JSON_VALUE. Wenn Sie nicht skalare Werte wie Arrays in die Extraktion aufnehmen möchten, verwenden Sie JSON_QUERY.

Rückgabetyp

STRING

Beispiele

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_age;

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

SELECT JSON_QUERY('{"fruits": ["apple", "banana"]}', '$.fruits') AS json_query,
  JSON_VALUE('{"fruits": ["apple", "banana"]}', '$.fruits') AS json_value;

+--------------------+------------+
| json_query         | json_value |
+--------------------+------------+
| ["apple","banana"] | NULL       |
+--------------------+------------+

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

Die meisten JSON-Funktionen übergeben einen Parameter json_string_expr oder json_path. Der Parameter json_string_expr übergibt einen JSON-formatierten String und der Parameter json_path 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 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 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 einzigen Spalte einer Zeile in der Tabelle.

Wenn durch die subquery eine Wertetabelle erzeugt wird, entspricht jedes Element im Ausgabe-ARRAY der gesamten entsprechenden Zeile der Wertetabelle.

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 ARRAY_TO_STRING(list, ', ', 'NULL'), 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
NUMERIC
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]      |
| []        | []          |
+-----------+-------------+

ARRAY_IS_DISTINCT

ARRAY_IS_DISTINCT(value)

Beschreibung

Gibt „true“ zurück, wenn das Array keine wiederkehrenden Elemente enthält und dieselbe Gleichheitsvergleichslogik wie SELECT DISTINCT verwendet.

Rückgabetyp

BOOL

Beispiele

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [1, 1, 1] AS arr UNION ALL
  SELECT [1, 2, NULL] AS arr UNION ALL
  SELECT [1, 1, NULL] AS arr UNION ALL
  SELECT [1, NULL, NULL] AS arr UNION ALL
  SELECT [] AS arr UNION ALL
  SELECT CAST(NULL AS ARRAY<INT64>) AS arr
)
SELECT
  arr,
  ARRAY_IS_DISTINCT(arr) as is_distinct
FROM example;

+-----------------+-------------+
| arr             | is_distinct |
+-----------------+-------------+
| [1, 2, 3]       | true        |
| [1, 1, 1]       | false       |
| [1, 2, NULL]    | true        |
| [1, 1, NULL]    | false       |
| [1, NULL, NULL] | false       |
| []              | true        |
| NULL            | NULL        |
+-----------------+-------------+

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 der Standardzeitzone zurück. Klammern sind optional, wenn sie ohne Argumente aufgerufen werden.

Diese Funktion unterstützt den optionalen Parameter time_zone. Dieser Parameter ist ein String, der die zu verwendende Zeitzone darstellt. Wenn keine Zeitzone angegeben ist, wird die Standardzeitzone "America/Los_Angeles" verwendet. Siehe Zeitzonendefinitionen für Anweisungen, wie eine Zeitzone festgelegt wird.

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   |
+--------------+

Wenn eine Spalte mit dem Namen current_date vorhanden ist, sind der Spaltenname und der Funktionsaufruf ohne Klammern nicht eindeutig. Fügen Sie Klammern hinzu, um den Funktionsaufruf zu gewährleisten. Um den Spaltennamen sicherzustellen, geben Sie für ihn seine Bereichsvariable an. Die folgende Abfrage wählt beispielsweise die Funktion in der Spalte the_date und die Tabellenspalte in der Spalte current_date aus.

WITH t AS (SELECT 'column value' AS `current_date`)
SELECT current_date() AS the_date, t.current_date FROM t;

+------------+--------------+
| the_date   | current_date |
+------------+--------------+
| 2016-12-25 | column value |
+------------+--------------+

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

Erstellt einen DATE-Wert aus INT64-Werten, die das Jahr, den Monat und den Tag darstellen.
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

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 entsprechend dem angegebenen 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

Wandelt eine Stringdarstellung des Datums in ein DATE-Objekt um.

format_string enthält die Formatelemente, die definieren, wie date_string formatiert ist. Jedem Element in date_string muss ein Element in format_string entsprechen. Die Position jedes Elements in format_string muss mit der Position der einzelnen Elemente in date_string übereinstimmen.

-- This works because elements on both sides match.
SELECT PARSE_DATE("%A %b %e %Y", "Thursday Dec 25 2008")

-- This doesn't work because the year element is in different locations.
SELECT PARSE_DATE("%Y %A %b %e", "Thursday Dec 25 2008")

-- This doesn't work because one of the year elements is missing.
SELECT PARSE_DATE("%A %b %e", "Thursday Dec 25 2008")

-- This works because %F can find all matching elements in date_string.
SELECT PARSE_DATE("%F", "2000-12-30")

Der Formatstring unterstützt mit Ausnahme von %a, %A, %g, %G, %j, %u und %U, %V, %w und %W die meisten Formatelemente vollständig.

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

Beispiele

In diesem Beispiel wird ein als MM/DD/YY formatierter String in ein DATE-Objekt konvertiert:

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

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

In diesem Beispiel wird ein als YYYYMMDD formatierter String in ein DATE-Objekt konvertiert:

SELECT PARSE_DATE("%Y%m%d", "20081225") 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	Beispiel
%A	Der vollständige Wochentagname.	Mittwoch
%a	Der abgekürzte Wochentagname.	Mi
%B	Der vollständige Monatsname.	Januar
%b oder %h	Der abgekürzte Monatsname.	Jan
%C	Das Jahrhundert (ein Jahr geteilt durch 100 und gekürzt auf eine Ganzzahl) als Dezimalzahl (00–99).	20
%D	Das Datum im Format %m/%d/%y.	01/20/21
%d	Der Tag des Monats als Dezimalzahl (01–31).	20
%e	Der Tag des Monats als Dezimalzahl (1–31); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.	20
%F	Das Datum im Format %Y-%m-%d.	2021-01-20
%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, wo das gregorianische Jahr und das ISO-Jahr möglicherweise voneinander abweichen.	2021
%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 das ISO-Jahr voneinander abweichen können.	21
%j	Der Tag des Jahres als Dezimalzahl (001–366).	020
%m	Der Monat als Dezimalzahl (01–12).	01
%n	Ein Zeilenumbruch.
%t	Ein Tab-Zeichen.
%U	Die Wochennummer des Jahres (Sonntag als erster Tag der Woche) als Dezimalzahl (00–53).	03
%u	Der Wochentag (Montag als erster Tag der Woche) als Dezimalzahl (1–7).	3
%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.	03
%W	Die Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (00–53).	03
%w	Der Wochentag (Sonntag als erster Tag der Woche) als Dezimalzahl (0–6).	3
%x	Die Datumsdarstellung im MM/TT/JJ-Format.	01/20/21
%Y	Das Jahr mit Jahrhundert als Dezimalzahl.	2021
%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.	21
%E4Y	Jahre mit vier Ziffern (von 0001 bis 9999). Beachten Sie, dass %Y so viele Zeichen produziert, wie nötig sind, um das Jahr komplett darzustellen.	2021

Zeitstempelfunktionen

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

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

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Beschreibung

CURRENT_TIMESTAMP() erzeugt einen TIMESTAMP-Wert, der kontinuierlich und eindeutig ist, genau 60 Sekunden pro Minute hat und keine Werte über die Schaltsekunde wiederholt. Klammern sind optional.

Diese Funktion verarbeitet Schaltsekunden, indem diese über ein Fenster von 20 Stunden um die eingefügten Schaltsekunden herum verteilt werden.

Unterstützte Eingabetypen

Nicht zutreffend

Datentyp des Ergebnisses

TIMESTAMP

Beispiele

SELECT CURRENT_TIMESTAMP() as now;

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

Wenn eine Spalte mit dem Namen current_timestamp vorhanden ist, sind der Spaltenname und der Funktionsaufruf ohne Klammern nicht eindeutig. Fügen Sie Klammern hinzu, um den Funktionsaufruf zu gewährleisten. Um den Spaltennamen sicherzustellen, geben Sie für ihn seine Bereichsvariable an. Die folgende Abfrage wählt beispielsweise die Funktion in der Spalte now und die Tabellenspalte in der Spalte current_timestamp aus.

WITH t AS (SELECT 'column value' AS `current_timestamp`)
SELECT current_timestamp() AS now, t.current_timestamp FROM t;

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

EXTRACT

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

Beschreibung

Gibt einen Wert zurück, der dem angegebenen part aus einer bereitgestellten timestamp_expression entspricht. Diese Funktion unterstützt den optionalen Parameter timezone. Informationen zur Angabe einer Zeitzone finden Sie unter Zeitzonendefinitionen.

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.

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_date       |
+----------------------+
| 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[, timezone])

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 timezone. Dieser Parameter gilt für die folgenden date_parts:

MINUTE
HOUR
DAY
WEEK
ISOWEEK
MONTH
QUARTER
YEAR
ISOYEAR

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[, timezone])

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, timestamp_string[, timezone])

Beschreibung

Wandelt die Stringdarstellung eines Zeitstempels in ein TIMESTAMP-Objekt um.

format_string enthält die Formatelemente, die definieren, wie timestamp_string formatiert ist. Jedem Element in timestamp_string muss ein Element in format_string entsprechen. Die Position jedes Elements in format_string muss mit der Position der einzelnen Elemente in timestamp_string übereinstimmen.

-- This works because elements on both sides match.
SELECT PARSE_TIMESTAMP("%a %b %e %I:%M:%S %Y", "Thu Dec 25 07:30:00 2008")

-- This doesn't work because the year element is in different locations.
SELECT PARSE_TIMESTAMP("%a %b %e %Y %I:%M:%S", "Thu Dec 25 07:30:00 2008")

-- This doesn't work because one of the year elements is missing.
SELECT PARSE_TIMESTAMP("%a %b %e %I:%M:%S", "Thu Dec 25 07:30:00 2008")

-- This works because %c can find all matching elements in timestamp_string.
SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008")

Der Formatstring unterstützt mit Ausnahme von %a, %A, %g, %G, %j, %P, %u, %U, %V, %w und %W die meisten Formatelemente vollständig.

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 einigen 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, d. h. 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	Beispiel
%A	Der vollständige Wochentagname.	Mittwoch
%a	Der abgekürzte Wochentagname.	Mi
%B	Der vollständige Monatsname.	Januar
%b oder %h	Der abgekürzte Monatsname.	Jan
%C	Das Jahrhundert (ein Jahr geteilt durch 100 und gekürzt auf eine Ganzzahl) als Dezimalzahl (00–99).	20
%c	Die Datums- und Uhrzeitdarstellung im Format %a %b %e %T %Y.	Mittwoch, 20. Januar 16:47:00 2021
%D	Das Datum im Format %m/%d/%y.	01/20/21
%d	Der Tag des Monats als Dezimalzahl (01–31).	20
%e	Der Tag des Monats als Dezimalzahl (1–31); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.	20
%F	Das Datum im Format %Y-%m-%d.	2021-01-20
%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, wo das gregorianische Jahr und das ISO-Jahr möglicherweise voneinander abweichen.	2021
%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 das ISO-Jahr voneinander abweichen können.	21
%H	Die Stunde (24-Stunden-Anzeige) als Dezimalzahl (00–23).	16
%I	Die Stunde (12-Stunden-Anzeige) als Dezimalzahl (01–12).	04
%j	Der Tag des Jahres als Dezimalzahl (001–366).	020
%k	Die Stunde (24-Stunden-Anzeige) als Dezimalzahl (0–23); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.	16
%l	Die Stunde (12-Stunden-Anzeige) als Dezimalzahl (1–12); den einzelnen Ziffern ist ein Leerzeichen vorangestellt.	11
%M	Die Minute als Dezimalzahl (00–59).	47
%m	Der Monat als Dezimalzahl (01–12).	01
%n	Ein Zeilenumbruch.
%P	Entweder "am" oder "pm".	a.m.
%p	Entweder "AM" oder "PM".	AM
%Q	Das Quartal als Dezimalzahl (1–4).	1
%R	Die Zeit im Format %H:%M.	16:47
%r	Die 12-Stunden-Anzeige mit AM/PM-Notation.	04:47:00 PM
%S	Die Sekunde als Dezimalzahl (00–60).	00
%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.	1611179220
%T	Die Zeit im Format %H:%M:%S.	16:47:00
%t	Ein Tab-Zeichen.
%U	Die Wochennummer des Jahres (Sonntag als erster Tag der Woche) als Dezimalzahl (00–53).	03
%u	Der Wochentag (Montag als erster Tag der Woche) als Dezimalzahl (1–7).	3
%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.	03
%W	Die Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl (00–53).	03
%w	Der Wochentag (Sonntag als erster Tag der Woche) als Dezimalzahl (0–6).	3
%X	Die Zeitdarstellung im Format HH:MM:SS.	16:47:00
%x	Die Datumsdarstellung im MM/TT/JJ-Format.	01/20/21
%Y	Das Jahr mit Jahrhundert als Dezimalzahl.	2021
%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.	21
%Z	Der Zeitzonenname.	UTC-5
%z	Der Versatz von der Nullmeridian-Zeitzone je nach Bedarf im Format +HHMM oder -HHMM, wobei die positiven Werte Orte östlich von Greenwich darstellen.	-0500
%%	Ein einzelnes %-Zeichen.	%
%Ez	RFC 3339-kompatible numerische Zeitzone (+HH:MM oder -HH:MM).	-05:00
%E#S	Sekunden mit #-Ziffern in Bruchgenauigkeit.	00.000
%E*S	Sekunden mit vollständiger Bruchgenauigkeit (ein richtiges Sternchen).	00
%E4Y	Jahre mit vier Ziffern (von 0001 bis 9999). Beachten Sie, dass %Y so viele Zeichen produziert, wie nötig sind, um das Jahr komplett darzustellen.	2021

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;

NET-Funktionen

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Beschreibung

Wandelt eine IPv4- oder IPv6-Adresse vom Textformat (STRING) in das Binärformat (BYTES) in Netzwerk-Byte-Reihenfolge um.

Diese Funktion unterstützt die folgenden Formate für addr_str:

IPv4: Dotted-Quad-Format (vier durch Punkte voneinander getrennte Zahlen). z. B. 10.1.2.3
IPv6: durch Doppelpunkte getrenntes Format. Beispiel: 1234:5678:90ab:cdef:1234:5678:90ab:cdef Weitere Beispiele finden Sie in der Beschreibung der Adressierungsarchitektur von IP-Version 6.

Diese Funktion unterstützt keine CIDR-Notation wie 10.1.2.3/32.

Wenn diese Funktion eine NULL-Eingabe empfängt, gibt sie NULL zurück. Wenn die Eingabe als ungültig erachtet wird, tritt ein OUT_OF_RANGE-Fehler auf.

Rückgabedatentyp

BYTES

Beispiel

SELECT
  addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128'
]) AS addr_str;

addr_str	ip_from_string
48.49.50.51	b"0123"
::1	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445	b"0123456789@ABCDE"
::ffff:192.0.2.128	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

Beschreibung

Ähnlich wie NET.IP_FROM_STRING, gibt aber NULL zurück, statt bei ungültiger Eingabe einen Fehler auszugeben.

Rückgabedatentyp

BYTES

Beispiel

SELECT
  addr_str,
  FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128',
  '48.49.50.51/32',
  '48.49.50',
  '::wxyz'
]) AS addr_str;

addr_str	safe_ip_from_string
48.49.50.51	b"0123"
::1	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445	b"0123456789@ABCDE"
::ffff:192.0.2.128	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
48.49.50.51/32	NULL
48.49.50	NULL
::wxyz	NULL

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

Beschreibung Wandelt eine IPv4- oder IPv6-Adresse vom Binärformat (BYTES) in Netzwerk-Byte-Reihenfolge in das Text-Format (STRING) um.

Wenn die Eingabe 4 Byte ist, gibt die Funktion eine IPv4-Adresse als STRING zurück. Wenn die Eingabe 16 Byte ist, gibt sie eine IPv6-Adresse als STRING zurück.

Wenn diese Funktion eine NULL-Eingabe empfängt, gibt sie NULL zurück. Wenn die Eingabe eine andere Länge als 4 oder 16 Byte hat, tritt der Fehler OUT_OF_RANGE auf.

Rückgabedatentyp

STRING

Beispiel

SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
  b"0123",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
  b"0123456789@ABCDE",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;

addr_bin	ip_to_string
b"0123"	48.49.50.51
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"	::1
b"0123456789@ABCDE"	3031:3233:3435:3637:3839:4041:4243:4445
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"	::ffff:192.0.2.128

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

Beschreibung

Gibt eine Netzwerkmaske zurück: eine Bytesequenz mit Länge gleich num_output_bytes, wobei die ersten prefix_length-Bits auf 1 eingestellt sind und die anderen Bits auf 0. num_output_bytes und prefix_length sind INT64. Diese Funktion gibt einen Fehler aus, wenn num_output_bytes nicht 4 Byte (für IPv4) oder 16 Byte (für IPv6) ist. Außerdem wird ein Fehler ausgegeben, wenn prefix_length negativ oder größer als 8 * num_output_bytes ist.

Rückgabedatentyp

BYTES

Beispiel

SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
  STRUCT(4 as x, 0 as y),
  (4, 20),
  (4, 32),
  (16, 0),
  (16, 1),
  (16, 128)
]);

x	y	ip_net_mask
4	0	b"\x00\x00\x00\x00"
4	20	b"\xff\xff\xf0\x00"
4	32	b"\xff\xff\xff\xff"
16	0	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16	1	b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16	128	b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

Beschreibung Nimmt addr_bin an, eine IPv4- oder IPv6-Adresse im Binärformat (BYTES) in Netzwerk-Bytereihenfolge, und gibt eine Subnetzadresse im selben Format zurück. Das Ergebnis hat die gleiche Länge wie addr_bin, wobei die ersten prefix_length-Bit gleich denen in addr_bin und die verbleibenden Bit 0 sind.

Diese Funktion gibt einen Fehler aus, wenn LENGTH(addr_bin) nicht 4 oder 16 Byte ist oder wenn prefix_len negativ oder größer als LENGTH(addr_bin) * 8 ist.

Rückgabedatentyp

BYTES

Beispiel

SELECT
  FORMAT("%T", x) as addr_bin, prefix_length,
  FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
  STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
  (b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
  (b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
  (b'0123456789@ABCDE', 80)
]);

addr_bin	prefix_length	ip_trunc
b"\xaa\xbb\xcc\xdd"	0	b"\x00\x00\x00\x00"
b"\xaa\xbb\xcc\xdd"	11	b"\xaa\xa0\x00\x00"
b"\xaa\xbb\xcc\xdd"	12	b"\xaa\xb0\x00\x00"
b"\xaa\xbb\xcc\xdd"	24	b"\xaa\xbb\xcc\x00"
b"\xaa\xbb\xcc\xdd"	32	b"\xaa\xbb\xcc\xdd"
b"0123456789@ABCDE"	80	b"0123456789\x00\x00\x00\x00\x00\x00"

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

Beschreibung

Wandelt eine IPv4-Adresse vom Ganzzahlformat in das Binärformat (BYTES) in Netzwerk-Byte-Reihenfolge um. Bei der Ganzzahleingabe wird ungeachtet der Host- oder Clientarchitektur das niedrigstwertige Bit der IP-Adresse im niedrigstwertigen Bit der Ganzzahl gespeichert. Beispiel: 1 bedeutet 0.0.0.1 und 0x1FF bedeutet 0.0.1.255.

Diese Funktion prüft, ob entweder alle höchstwertigen 32 Bits 0 sind oder alle höchstwertigen 33 Bits 1 sind (zeichenerweitert von einer 32-Bit-Ganzzahl). Mit anderen Worten: Die Eingabe sollte im Bereich [-0x80000000, 0xFFFFFFFF] liegen. Andernfalls gibt diese Funktion einen Fehler aus.

Diese Funktion unterstützt kein IPv6.

Rückgabedatentyp

BYTES

Beispiel

SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
  SELECT CAST(x_hex AS INT64) x, x_hex
  FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);

x	x_hex	ipv4_from_int64
0	0x0	b"\x00\x00\x00\x00"
11259375	0xABCDEF	b"\x00\xab\xcd\xef"
4294967295	0xFFFFFFFF	b"\xff\xff\xff\xff"
-1	-0x1	b"\xff\xff\xff\xff"
-2	-0x2	b"\xff\xff\xff\xfe"

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

Beschreibung

Wandelt eine IPv4-Adresse vom Binärformat (BYTES) in Netzwerk-Byte-Reihenfolge in das Ganzzahlformat um. Bei der Ganzzahlausgabe wird ungeachtet der Host- oder Client-Architektur das niedrigstwertige Bit der IP-Adresse in das niedrigstwertige Bit der Ganzzahl gespeichert. Beispiel: 1 bedeutet 0.0.0.1 und 0x1FF bedeutet 0.0.1.255. Die Ausgabe liegt im Bereich [0, 0xFFFFFFFF].

Wenn die Eingabelänge nicht 4 Byte ist, gibt diese Funktion einen Fehler aus.

Diese Funktion unterstützt kein IPv6.

Rückgabedatentyp

INT64

Beispiel

SELECT
  FORMAT("%T", x) AS addr_bin,
  FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;

addr_bin	ipv4_to_int64
b"\x00\x00\x00\x00"	0x0
b"\x00\xab\xcd\xef"	0xABCDEF
b"\xff\xff\xff\xff"	0xFFFFFFFF

NET.HOST

NET.HOST(url)

Beschreibung

Nimmt eine URL als STRING an und gibt den Host als STRING zurück. Optimale Ergebnisse erzielen Sie, wenn URL-Werte dem durch RFC 3986 definierten Format entsprechen. Wenn der URL-Wert nicht mit der Formatierung von RFC 3986 übereinstimmt, versucht diese Funktion trotzdem, die Eingabe zu parsen und ein relevantes Ergebnis zurückzugeben. Wenn die Funktion die Eingabe nicht parsen kann, gibt sie NULL zurück.

Hinweis: Die Funktion führt keine Normalisierung durch.

Rückgabedatentyp

STRING

Beispiel

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Eingabe	Beschreibung	Host	Suffix	Domain
""	Ungültige Eingabe	NULL	NULL	NULL
"http://abc.xyz"	Standard-URL	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	Standard-URL mit relativem Schema, Port, Pfad und relativer Abfrage, aber kein öffentliches Suffix	"a.b"	NULL	NULL
"https://[::1]:80"	Standard-URL mit IPv6-Host	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	Standard-URL mit internationalisiertem Domainnamen	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
" www.Example.Co.UK "	Nicht-Standard-URL mit Leerzeichen, Großbuchstaben und ohne Schema	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK"
"mailto:?to=&subject=&body="	URI statt URL – nicht unterstützt	"mailto"	NULL	NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Beschreibung

Nimmt eine URL als STRING an und gibt das öffentliche Suffix (z. B. com, org oder net) als STRING zurück. Ein öffentliches Suffix ist eine ICANN-Domain, die bei publicsuffix.org registriert ist. Optimale Ergebnisse erzielen Sie, wenn URL-Werte dem durch RFC 3986 definierten Format entsprechen. Wenn der URL-Wert nicht mit der Formatierung von RFC 3986 übereinstimmt, versucht diese Funktion trotzdem, die Eingabe zu parsen und ein relevantes Ergebnis zurückzugeben.

Diese Funktion gibt NULL zurück, wenn eine der folgenden Aussagen zutrifft:

Der Host kann nicht aus der Eingabe geparst werden.
Der geparste Host enthält in der Mitte benachbarte Punkte (nicht voran- oder nachgestellt).
Der geparste Host enthält kein öffentliches Suffix.

Bevor das öffentliche Suffix abgerufen wird, normalisiert diese Funktion den Host vorübergehend. Hierzu werden englische Großbuchstaben in Kleinbuchstaben umgewandelt und alle Nicht-ASCII-Zeichen mit Punycode codiert. Die Funktion gibt dann das öffentliche Suffix als Teil des ursprünglichen Hosts anstelle des normalisierten Hosts zurück.

Hinweis: Die Funktion führt keine Unicode-Normalisierung durch.

Hinweis: Die Daten zu öffentlichen Suffixen bei publicsuffix.org enthalten auch private Domains. Diese Funktion ignoriert die privaten Domains.

Hinweis: Die öffentlichen Suffix-Daten können sich im Laufe der Zeit ändern. Folglich kann die Eingabe, die derzeit ein NULL-Ergebnis erzeugt, in Zukunft einen Nicht-NULL-Wert erzeugen.

Rückgabedatentyp

STRING

Beispiel

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Eingabe	Beschreibung	Host	Suffix	Domain
""	Ungültige Eingabe	NULL	NULL	NULL
"http://abc.xyz"	Standard-URL	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	Standard-URL mit relativem Schema, Port, Pfad und relativer Abfrage, aber kein öffentliches Suffix	"a.b"	NULL	NULL
"https://[::1]:80"	Standard-URL mit IPv6-Host	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	Standard-URL mit internationalisiertem Domainnamen	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
" www.Example.Co.UK "	Nicht-Standard-URL mit Leerzeichen, Großbuchstaben und ohne Schema	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK
"mailto:?to=&subject=&body="	URI statt URL – nicht unterstützt	"mailto"	NULL	NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Beschreibung

Nimmt eine URL als STRING an und gibt die registrierte oder registrierbare Domain, also das öffentliche Suffix plus ein vorangestelltes Label, als STRING zurück. Optimale Ergebnisse erzielen Sie, wenn URL-Werte dem durch RFC 3986 definierten Format entsprechen. Wenn der URL-Wert nicht mit der Formatierung von RFC 3986 übereinstimmt, versucht diese Funktion trotzdem, die Eingabe zu parsen und ein relevantes Ergebnis zurückzugeben.

Diese Funktion gibt NULL zurück, wenn eine der folgenden Aussagen zutrifft:

Der Host kann nicht aus der Eingabe geparst werden.
Der geparste Host enthält benachbarte Punkte in der Mitte (nicht voran- oder nachgestellt);
Der geparste Host enthält kein öffentliches Suffix;
Der geparste Host enthält nur ein öffentliches Suffix ohne vorangestelltes Label.

Bevor das öffentliche Suffix abgerufen wird, normalisiert diese Funktion den Host vorübergehend, indem englische Großbuchstaben in Kleinbuchstaben umwandelt und alle Nicht-ASCII-Zeichen mit Punycode codiert werden. Die Funktion gibt dann die registrierte oder registrierbare Domain als Teil des ursprünglichen Hosts anstelle des normalisierten Hosts zurück.

Hinweis: Die Funktion führt keine Unicode-Normalisierung durch.

Hinweis: Die Daten zu öffentlichen Suffixen bei publicsuffix.org enthalten auch private Domains. Diese Funktion behandelt eine private Domain nicht als öffentliches Suffix. Wenn zum Beispiel "us.com" eine private Domain in den öffentlichen Suffixdaten ist, gibt NET.REG_DOMAIN ("foo.us.com") den Wert "us.com" (das öffentliche Suffix "com" plus das vorangestellte Label "us") statt "foo.us.com" (die private Domain "us.com" plus das vorangestellte Label "foo") zurück.

Hinweis: Die öffentlichen Suffixdaten können sich im Laufe der Zeit ändern. Folglich kann die Eingabe, die derzeit ein NULL-Ergebnis erzeugt, in Zukunft einen Nicht-NULL-Wert erzeugen.

Rückgabedatentyp

STRING

Beispiel

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Eingabe	Beschreibung	Host	Suffix	Domain
""	Ungültige Eingabe	NULL	NULL	NULL
"http://abc.xyz"	Standard-URL	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	Standard-URL mit relativem Schema, Port, Pfad und relativer Abfrage, aber kein öffentliches Suffix	"a.b"	NULL	NULL
"https://[::1]:80"	Standard-URL mit IPv6-Host	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	Standard-URL mit internationalisiertem Domainnamen	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
" www.Example.Co.UK "	Nicht-Standard-URL mit Leerzeichen, Großbuchstaben und ohne Schema	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK"
"mailto:?to=&subject=&body="	URI statt URL – nicht unterstützt	"mailto"	NULL	NULL

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 Plus	Unär
	-	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 Plus	+ X
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, Subtraktion und Multiplikation:

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Ergebnistypen für Division:

INPUT	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Ergebnistypen für unäres Plus:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Ergebnistypen für unäres Minus:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	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

Cloud Spanner SQL unterstützt die logischen Operatoren AND, OR und NOT. Logische Operatoren lassen nur Eingaben in Form von Booten oder NULL zu und verwenden eine dreiwertige Logik, um ein Ergebnis zu erzeugen. Das Ergebnis kann TRUE, FALSE oder NULL sein:

x	y	x AND y	x OR y
TRUE	TRUE	TRUE	TRUE
TRUE	FALSE	FALSE	TRUE
TRUE	NULL	NULL	TRUE
FALSE	TRUE	FALSE	TRUE
FALSE	FALSE	FALSE	FALSE
FALSE	NULL	FALSE	NULL
NULL	TRUE	NULL	TRUE
NULL	FALSE	FALSE	NULL
NULL	NULL	NULL	NULL

x	NOT x
TRUE	FALSE
FALSE	TRUE
NULL	NULL

Beispiele

Die Beispiele in diesem Abschnitt beziehen sich auf eine Tabelle namens entry_table:

+-------+
| entry |
+-------+
| a     |
| b     |
| c     |
| NULL  |
+-------+

SELECT 'a' FROM entry_table WHERE entry = 'a'

-- a => 'a' = 'a' => TRUE
-- b => 'b' = 'a' => FALSE
-- NULL => NULL = 'a' => NULL

+-------+
| entry |
+-------+
| a     |
+-------+

SELECT entry FROM entry_table WHERE NOT (entry = 'a')

-- a => NOT('a' = 'a') => NOT(TRUE) => FALSE
-- b => NOT('b' = 'a') => NOT(FALSE) => TRUE
-- NULL => NOT(NULL = 'a') => NOT(NULL) => NULL

+-------+
| entry |
+-------+
| b     |
| c     |
+-------+

SELECT entry FROM entry_table WHERE entry IS NULL

-- a => 'a' IS NULL => FALSE
-- b => 'b' IS NULL => FALSE
-- NULL => NULL IS NULL => TRUE

+-------+
| entry |
+-------+
| NULL  |
+-------+

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-Operatoren

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.

Funktionssyntax	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-Ausdrücke

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, wenn 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 auf erzwungene Werte angewendet. 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 "false" 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  |
+------------------+

WENNNULL

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 einen beliebigen Typ haben 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 Ausdrucks-Unterabfragen, d. h. 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. Eine ausführlichere Beschreibung von Unterabfragen ist unter Unterabfragen zu finden.

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
EXISTS	`NOT EXISTS(SELECT x,y,z FROM table WHERE y=z)`	BOOL
IN	`x IN (SELECT y FROM table WHERE z)`	BOOL
IN	`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