Trabalhar com analisadores de texto

A páginaCREATE SEARCH INDEX Instrução DDL ,SEARCH função e TEXT_ANALYZE função oferece suporte a opções avançadas de configuração do analisador de texto. Entender os analisadores de texto do BigQuery e as opções deles permite refinar sua experiência de pesquisa.

Neste documento, você terá uma visão geral dos diferentes analisadores de texto disponíveis no BigQuery e as opções de configuração. Além disso, você verá exemplos de como eles funcionam com a pesquisa no BigQuery. Para mais informações sobre a sintaxe do analisador de texto, consulte Análise de texto.

Analisadores de texto

O BigQuery oferece suporte aos seguintes analisadores de texto:

  • NO_OP_ANALYZER
  • LOG_ANALYZER
  • PATTERN_ANALYZER

NO_OP_ANALYZER

Use o NO_OP_ANALYZER quando tiver dados pré-processados que você quer corresponder exatamente. Não há tokenização ou normalização aplicada ao texto. Como esse analisador não realiza a tokenização ou normalização, ele não aceita nenhuma configuração. Para mais informações sobre NO_OP_ANALYZER, consulte NO_OP_ANALYZER.

LOG_ANALYZER

O LOG_ANALYZER modifica os dados de texto das seguintes maneiras:

  • O texto fica em letras minúsculas.
  • Valores ASCII maiores do que 127 são mantidos como estão.

  • O texto é dividido em termos individuais, chamados tokens, pelas seguintes delimitadores:

    [ ] < > ( ) { } | ! ; , ' " * & ? + / : = @ . - $ % \ _ \n \r \s \t %21 %26
    %2526 %3B %3b %7C %7c %20 %2B %2b %3D %3d %2520 %5D %5d %5B %5b %3A %3a %0A
    %0a %2C %2c %28 %29
    

    Se você não quiser usar os delimitadores padrão, poderá especificar os delimitadores que quer usar como opções do analisador de texto. LOG_ANALYZER permite configurar delimitadores e filtros de token específicos para ter mais controle sobre os resultados da pesquisa. Para mais informações sobre as opções de configuração específicas disponíveis ao usar asLOG_ANALYZER, consulte delimiters Analyzer etoken_filters Analyzer de dois minutos.

PATTERN_ANALYZER

O analisador de texto PATTERN_ANALYZER extrai tokens do texto usando uma expressão regular. O mecanismo de expressão regular e a sintaxe usados com PATTERN_ANALYZER são RE2. PATTERN_ANALYZER tokeniza padrões na seguinte ordem:

  1. Ele encontra a primeira substring que corresponde ao padrão (da esquerda) na string. Esse é um token a ser incluído na saída.
  2. Ele remove tudo da string de entrada até o final da substring encontrada na etapa 1.
  3. Ele repete o processo até que a string esteja vazia.

A tabela a seguir mostra exemplos de extração de token PATTERN_ANALYZER:

Padrão Entrada de texto Tokens de saída
ab ababab
  • ab
ab abacad
  • ab
[a-z]{2} abacad
  • ab
  • ac
  • ad
aaa aaaaa
  • aaa
[a-z]/ a/b/c/d/e
  • a/
  • b/
  • c/
  • d/
/[^/]+/ aa/bb/cc
  • /bb/
[0-9]+ abc
(?:/?)[a-z] /abc
  • /abc
(?:/)[a-z] /abc
  • /abc
(?:[0-9]abc){3}(?:[a-z]000){2} 7abc7abc7abcx000y000
  • 7abc7abc7abcx000y000
".+" "cats" and "dogs"
  • "cats" and "dogs"


O uso de quantificadores gananciosos + faz com que a correspondência corresponda à maior string possível no texto, resultando em "gatos". e "dogs" para extrair como token no texto.
".+?" "cats" and "dogs"
  • "cats"
  • "dogs"


O uso de quantificadores lentos +? faz com que a expressão regular corresponda à string mais curta possível no texto, fazendo com que "gatos" "', '"dogs"' para ser extraído como dois tokens separados no texto.

O uso do analisador de texto PATTERN_ANALYZER oferece mais controle sobre os tokens extraídos de um texto quando usados com a função SEARCH. A tabela a seguir mostra como padrões e resultados diferentes resultam em resultados SEARCH diferentes:

Padrão Consulta Texto Tokens de texto SEARCH(texto; consulta) Explicação
abc abcdef abcghi
  • abcghi
VERDADEIRO 'abc' em ['abcghi']
cd[a-z] abcdef abcghi
  • abcghi
FALSE 'cde' em ['abcghi']
[a-z]/ a/b/ a/b/c/d/
  • a/
  • b/
  • c/
  • d/
VERDADEIRO 'a/' in ['a/', 'b/', 'c/', 'd/'] AND 'b/' em ['a/', 'b/', 'c/', 'd/']
/[^/]+/ aa/bb/ aa/bb/cc/
  • /bb/
VERDADEIRO '/bb/' in ['/bb/']
/[^/]+/ bb aa/bb/cc/
  • /bb/
ERRO No match found in query term
[0-9]+ abc abc123 ERRO No match found in query term
[0-9]+ abc123! abc123 ERRO Nenhuma correspondência encontrada no termo de consulta

Aparece como acento grave, e não um caractere especial.
[a-z][a-z0-9]*@google\.com Meu e-mail é test@google.com test@google.com
  • test@google.com
VERDADEIRO "test@google.com" em "test@google.com"
abc abc\ abc abc
  • abc
VERDADEIRO "abc" em ['abc']

Observe que "abc abc" é uma única subconsulta(ie) depois de ser analisado pelo analisador de consultas de pesquisa, já que o espaço tem escape.
(?i)(?:Abc) (sem normalização) aBcd Abc
  • Abc
FALSE 'aBc' in ['Abc']
(?i)(?:Abc)

normalização:
minúscula = verdadeira
aBcd Abc
  • abc
VERDADEIRO 'abc' em ['abc']
(?:/?)abc bc/abc /abc/abc/
  • /abc
VERDADEIRO '/abc' em ['/abc']
(?:/?)abc abc d/abc
  • /abc
FALSE 'abc' em ['/abc']
".+" "cats" "cats" and "dogs"
  • "cats" and "dogs"
FALSE "gatos" em ['"gatos" e "cachorros"]

O uso de quantificadores gananciosos + faz com que a expressão regular corresponda ao maior string possível no texto, fazendo com que '"gatos" e "cachorros"' sejam extraídos como um token no texto.
".+?" "cats" "cats" and "dogs"
  • "cats"
  • "dogs"
VERDADEIRO '"cats"' in ['"cats"', '"dogs"]

O uso de quantificadores lentos +? torna o resultado A expressão corresponde à menor string possível no texto, fazendo com que '"cats"', '"dogs"' sejam extraídos como dois tokens separados no texto.

Exemplos

Nos exemplos a seguir, demonstramos o uso da análise de texto com opções de personalização para criar índices de pesquisa, extrair tokens e retornar resultados da pesquisa.

LOG_ANALYZER com normalização de ICU do NFKC e palavras de parada

O exemplo a seguir configura as opções de LOG_ANALYZER com a normalização da NFKC ICU e as palavras de parada. No exemplo, pressupomos a seguinte tabela de dados com dados já preenchidos:

CREATE TABLE dataset.data_table(
  text_data STRING
);

Para criar um índice de pesquisa com a normalização de ICU NFKC e uma lista de palavras de parada, crie uma string formatada em JSON na opção analyzer_options da instrução DDL CREATE SEARCH INDEX. de dois minutos. Para uma lista completa das opções disponíveis na criação de um índice de pesquisa com LOG_ANALYZER, consulte LOG_ANALYZER. Neste exemplo, nossas palavras de parada são "the", "of", "and", "for".

CREATE OR REPLACE SEARCH INDEX `my_index` ON `dataset.data_table`(ALL COLUMNS) OPTIONS(
  analyzer='PATTERN_ANALYZER',
  analyzer_options= '''{
    "token_filters": [
      {
        "normalizer": {
          "mode": "ICU_NORMALIZE",
          "icu_normalize_mode": "NFKC",
          "icu_case_folding": true
        }
      },
      { "stop_words": ["the", "of", "and", "for"] }
    ]
  }''');

Considerando o exemplo anterior, a tabela a seguir descreve a extração do token para vários valores de text_data. Neste documento, o caractere de ponto de interrogação duplo (??) está em itálico para diferenciar entre dois pontos (??):

Texto de dados Tokens para o índice Explicação
A raposa-parda rápida ["rápido", "marrom", "raposa"] A tokenização LOG_ANALYZER produz os tokens ["The", "Quick", "Brown", "Fox"].

Em seguida, a normalização da ICU com icu_case_folding = true diminui os tokens para produzir ["a", "rápida", "marrom", "fox"]

Por fim, o filtro de palavras de parada remove "o" da lista.
A raposa-parda rápida ["rápido", "marrom", "raposa"] A tokenização LOG_ANALYZER produz os tokens ["The", "Quick", "Brown", "Fox"].

Em seguida, a normalização da ICU do NFKC comicu_case_folding = true em letras minúsculas os tokens para produzir ["o", "rápido", "marrom", "raposa"]

Por fim, o filtro de palavras de parada remove "o" da lista.
ⓆuickⒻox ["rápido??raposa"] A tokenização LOG_ANALYZER produz os tokens ["The", "Quick??Fox"].

Em seguida, a normalização da ICU do NFKC com icu_case_folding = true diminui os tokens para produzir ["quick??fox"]. Observe que o ponto de interrogação duplo Unicode foi normalizado em dois caracteres ASCII de ponto de interrogação.

Por fim, o filtro de palavras de parada não faz nada, porque nenhum dos tokens está na lista de filtros.

Agora que o índice de pesquisa foi criado, use a função SEARCH para pesquisar na tabela com as mesmas configurações do analisador especificadas no índice de pesquisa. Se as configurações do analisador na função SEARCH não corresponderem às do índice de pesquisa, o índice de pesquisa não será usado. Use a seguinte consulta:

SELECT
  SEARCH(
  analyzer => 'LOG_ANALYZER',
  analyzer_options => '''{
    "token_filters": [
      {
        "normalizer": {
          "mode": "ICU_NORMALIZE",
          "icu_normalize_mode": "NFKC",
          "icu_case_folding": true
        }
      },
      {
        "stop_words": ["the", "of", "and", "for"]
      }
    ]
  }''')

Substitua:

  • search_query: o texto que você quer pesquisar.

A tabela a seguir demonstra vários resultados com base em diferentes textos de pesquisa e valores de search_query diferentes:

text_data search_query Resultado Explicação
A raposa-parda rápida "Ⓠuick" TRUE A lista final de tokens extraídos do texto é ["quick", "brown", "fox"].
A lista final de tokens extraídos da consulta de texto é ["quick"].

Todos os tokens de consulta da lista podem ser encontrados nos tokens de texto.
A raposa-parda rápida "quick" TRUE A lista final de tokens extraídos do texto é ["quick", "brown", "fox"].
A lista final de tokens extraídos da consulta de texto é ["quick"].

Todos os tokens de consulta da lista podem ser encontrados nos tokens de texto.
ⓆuickⒻox "quick" FALSE A lista final de tokens extraídos do texto é ["quick??fox"].

A lista final de tokens extraídos da consulta de texto é ["quick"].

"rápido" não está na lista de tokens do texto.
ⓆuickⒻox "quickfox" TRUE A lista final de tokens extraídos do texto é ["quick??fox"].

A lista final de tokens extraídos da consulta de texto é ["quick??fox"].

"quick??fox" está na lista de tokens do texto.
ⓆuickⒻox "`quickfox`" FALSE Em LOG_ANALYZER, a crase exige uma correspondência exata de texto.

PATTERN_ANALYZER para pesquisa IPv4 com palavras de parada

O exemplo a seguir configura o analisador de texto PATTERN_ANALYZER para pesquisar um padrão específico ao filtrar determinadas palavras de parada. Neste exemplo, o padrão corresponde a um endereço IPv4 e ignora o valor de localhost (127.0.0.1).

Neste exemplo, presumimos que a tabela a seguir seja preenchida com dados:

CREATE TABLE dataset.data_table(
  text_data STRING
);

Para criar um índice de pesquisa com a opção pattern e uma lista de palavras de parada, crie uma string formatada em JSON na opção analyzer_options da instrução DDL CREATE SEARCH INDEX. Para uma lista completa das opções disponíveis na criação de um índice de pesquisa com PATTERN_ANALYZER, consulte PATTERN_ANALYZER. Neste exemplo, nossas palavras de parada são o endereço do localhost, 127.0.0.1.

CREATE SEARCH INDEX my_index
ON dataset.data_table(text_data)
OPTIONS (analyzer = 'PATTERN_ANALYZER', analyzer_options = '''{
  "patterns": [
    "(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)[.]){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"
  ],
  "token_filters": [
    {
      "stop_words": [
        "127.0.0.1"
      ]
    }
  ]
}'''
);

Ao usar expressões regulares com analyzer_options, inclua três símbolos \ iniciais para o escape correto de expressões regulares que incluam um símbolo \, como \d ou \b.

A tabela a seguir descreve as opções de tokenização para diversos valores de text_data.

Texto de dados Tokens para o índice Explicação
abc192.168.1.1def 172.217.20.142 ["192.168.1.1", "172.217.20.142"] Os padrões IPv4 capturam os endereços IPv4 mesmo que não haja espaço entre o endereço e o texto.
104.24.12.10abc 127.0.0.1 ["104.24.12.10"] "127.0.0.1" é filtrado porque está na lista de palavras de parada.

Agora que o índice de pesquisa foi criado, use a função SEARCH para pesquisar na tabela com base na tokenização especificada em analyzer_options. Use a seguinte consulta:

SELECT
  SEARCH(dataset.data_table.text_data
  "search_data",
  analyzer => 'PATTERN_ANALYZER',
  analyzer_options => '''{
    "patterns": [
      "(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)[.]){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"
      ],
    "token_filters": [
      {
        "stop_words": [
          "127.0.0.1"
        ]
      }
    ]
  }'''
);

Substitua:

  • search_query: o texto que você quer pesquisar.

A tabela a seguir demonstra vários resultados com base em diferentes textos de pesquisa e valores de search_query diferentes:

text_data search_query Resultado Explicação
128.0.0.2 "127.0.0.1" ERRO Não há tokens de pesquisa na consulta.

A consulta passa pelo analisador de texto, que filtra o token "127.0.0.1".
abc192.168.1.1def 172.217.20.142 "192.168.1.1abc" VERDADEIRO A lista de tokens extraídos da consulta é ["192.168.1.1"].

A lista de tokens extraídos do texto é ["192.168.1.1", "172.217.20.142"].
abc192.168.1.1def 172.217.20.142 "`192.168.1.1`" VERDADEIRO A lista de tokens extraídos da consulta é ["192.168.1.1"].

A lista de tokens extraídos do texto é ["192.168.1.1", "172.217.20.142"].

Os acentos graves são tratados como caracteres normais para Padrão_ANALYZER.

A seguir