Funções de rede no SQL padrão

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Descrição

Converte um endereço IPv4 ou IPv6 do formato de texto (STRING) para o formato binário (BYTES) na ordem de bytes da rede.

Esta função suporta os seguintes formatos para addr_str:

  • IPv4: formato "dotted-quad" (quádruplo com ponto). Por exemplo, 10.1.2.3.
  • IPv6: formato separado por dois-pontos. Por exemplo, 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Para mais exemplos, consulte Arquitetura de endereçamento de IP versão 6 (em inglês).

Essa função não é compatível com a notação CIDR, como 10.1.2.3/32.

Se ela receber uma entrada NULL, retornará NULL. Se a entrada for considerada inválida, ocorrerá um erro OUT_OF_RANGE.

Tipos de dados retornados

BYTES

Exemplo

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)

Descrição

Semelhante a NET.IP_FROM_STRING, mas retorna NULL em vez de gerar um erro se a entrada for inválida.

Tipos de dados retornados

BYTES

Exemplo

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)

Descrição Converte um endereço IPv4 ou IPv6 do formato binário (BYTES) na ordem de bytes da rede para o formato de texto (STRING).

Se a entrada for de 4 bytes, essa função retornará um endereço IPv4 como uma STRING. Se a entrada for de 16 bytes, ela retornará um endereço IPv6 como uma STRING.

Se receber uma entrada NULL, essa função retornará NULL. Se a entrada tiver um comprimento diferente de 4 ou 16, ocorrerá um erro OUT_OF_RANGE.

Tipos de dados retornados

STRING

Exemplo

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)

Descrição

Retorna uma máscara de rede: uma sequência de bytes com comprimento igual a num_output_bytes, em que os primeiros prefix_length bits são definidos como um e os outros bits são definidos como zero. num_output_bytes e prefix_length são INT64. Esta função gera um erro se num_output_bytes não for 4 (para IPv4) ou 16 (para IPv6). Ele também gera um erro se prefix_length for negativo ou maior que 8 * num_output_bytes.

Tipos de dados retornados

BYTES

Exemplo

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)

Descrição Obtém addr_bin, um endereço IPv4 ou IPv6 no formato binário (BYTES) na ordem de bytes da rede e retorna um endereço de sub-rede no mesmo formato. O resultado tem o mesmo comprimento que addr_bin, onde os primeiros prefix_length bits são iguais aos addr_bin e os bits restantes são 0

Esta função gera um erro se LENGTH(addr_bin) não for 4 ou 16, ou se prefix_len for negativo ou maior que LENGTH(addr_bin) * 8.

Tipos de dados retornados

BYTES

Exemplo

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)

Descrição

Converte um endereço IPv4 do formato inteiro para binário (BYTES) na ordem de bytes da rede. Na entrada do inteiro, o bit menos significativo do endereço IP é armazenado no bit menos significativo do inteiro, independentemente da arquitetura do host ou do cliente. Por exemplo, 1 significa 0.0.0.1 e 0x1FF significa 0.0.1.255.

Essa função verifica se todos os 32 bits mais significativos são 0, ou se todos os 33 bits mais significativos são 1 (estendido por sinal de um inteiro de 32 bits). Em outras palavras, a entrada precisa estar no intervalo [-0x80000000, 0xFFFFFFFF]. Caso contrário, esta função gerará um erro.

Essa função não aceita IPv6.

Tipos de dados retornados

BYTES

Exemplo

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)

Descrição

Converte um endereço IPv4 do formato binário (BYTES) na ordem de bytes da rede para inteiro. Na saída do número inteiro, o bit menos significativo do endereço IP é armazenado no bit menos significativo do número inteiro, independentemente da arquitetura do host ou do cliente. Por exemplo, 1 significa 0.0.0.1, e 0x1FF significa 0.0.1.255. A saída está no intervalo [0, 0xFFFFFFFF].

Se o comprimento de entrada não for 4, esta função gerará um erro.

Essa função não aceita IPv6.

Tipos de dados retornados

INT64

Exemplo

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)

Descrição

Toma uma URL como uma STRING e retorna o host como uma STRING. Para os melhores resultados, os valores de URL precisam obedecer ao formato conforme definido pelo RFC 3986. Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante. Se não for possível analisar a entrada, será retornado NULL.

Nota: a função não realiza a normalização.

Tipos de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Descrição

Toma uma URL como uma STRING e retorna o sufixo público (como com, org ou net) como uma STRING. Um sufixo público é um domínio da ICANN registrado em publicsuffix.org. Para os melhores resultados, os valores de URL precisam obedecer ao formato conforme definido pelo RFC 3986. Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante.

A função retornará NULL, se qualquer uma das seguintes situações for verdadeira:

  • Não é possível analisar o host com a entrada.
  • O host analisado contém pontos adjacentes no meio (não à esquerda ou direita).
  • O host analisado não contém um sufixo público.

Antes de pesquisar o sufixo público, essa função normalizará temporariamente o host convertendo letras em inglês em maiúsculas para minúsculas e codificando todos os caracteres não ASCII com Punycode. Depois, ela retornará o sufixo público como parte do host original em vez do host normalizado:

Observação: a função não realiza a normalização Unicode.

Observação: os dados de sufixo público em publicsuffix.org também contêm domínios privados. Essa função ignora os domínios privados.

Observação: os dados do sufixo público podem mudar ao longo do tempo. Por conseguinte, a entrada que produz um resultado NULL no momento pode produzir um valor não NULL no futuro.

Tipos de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Descrição

Toma uma URL como uma STRING e retorna o domínio registrado ou registrável (o sufixo público mais um rótulo precedente), como uma STRING. Para os melhores resultados, os valores de URL precisam obedecer ao formato conforme definido pelo RFC 3986. Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante.

A função retornará NULL, se qualquer uma das seguintes situações for verdadeira:

  • Não é possível analisar o host com a entrada.
  • O host analisado contém pontos adjacentes no meio (não à esquerda ou direita).
  • O host analisado não contém um sufixo público.
  • O host analisado contém somente um sufixo público sem rótulo precedente.

Antes de pesquisar o sufixo público, essa função normalizará temporariamente o host convertendo letras em inglês em maiúsculas para minúsculas e codificando todos os caracteres não ASCII com Punycode. Depois, ela retornará o domínio registrado ou registrável como parte do host original em vez do host normalizado.

Observação: a função não realiza a normalização Unicode.

Observação: os dados de sufixo público em publicsuffix.org também contêm domínios privados. Essa função não trata um domínio privado como um sufixo público. Por exemplo, se "us.com" for um domínio privado nos dados de sufixo público, NET.REG_DOMAIN ("foo.us.com") retornará "us.com" (o sufixo público "com" mais o rótulo anterior "us ") em vez de "foo.us.com" (o domínio privado "us.com" mais o rótulo anterior "foo").

Observação: os dados do sufixo público podem mudar ao longo do tempo. Por conseguinte, a entrada que produz um resultado NULL no momento pode produzir um valor não NULL no futuro.

Tipos de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL