Funções de análise de texto

O GoogleSQL para BigQuery oferece suporte às funções de análise de texto a seguir.

Lista de funções

Nome Resumo
BAG_OF_WORDS Recebe a frequência de cada termo (token) em um documento tokenizado.
TEXT_ANALYZE Extrai termos (tokens) do texto e os converte em um documento tokenizado.
TF_IDF Avalia a relevância de um termo (token) para um documento tokenizado em um conjunto de documentos tokenizados.

BAG_OF_WORDS

BAG_OF_WORDS(tokenized_document)

Definição

Recebe a frequência de cada termo (token) em um documento tokenizado.

Definições

  • tokenized_document: valor ARRAY<STRING> que representa um documento que foi tokenizado. Um documento tokenizado é uma coleção de termos (tokens) usados para análise de texto.

Tipo de retorno

ARRAY<STRUCT<term STRING, count INT64>>

Definições:

  • term: um termo exclusivo no documento tokenizado.
  • count: o número de vezes que o termo foi encontrado no documento tokenizado.

Exemplos

A consulta a seguir produz termos e frequências em dois documentos tokenizados:

WITH
  ExampleTable AS (
    SELECT 1 AS id, ['I', 'like', 'pie', 'pie', 'pie', NULL] AS f UNION ALL
    SELECT 2 AS id, ['yum', 'yum', 'pie', NULL] AS f
  )
SELECT id, BAG_OF_WORDS(f) AS results
FROM ExampleTable
ORDER BY id;

/*----+------------------------------------------------*
 | id | results                                        |
 +----+------------------------------------------------+
 | 1  | [(null, 1), ('I', 1), ('like', 1), ('pie', 3)] |
 | 2  | [(null, 1), ('pie', 1), ('yum', 2)]            |
 *----+------------------------------------------------*/

TEXT_ANALYZE

TEXT_ANALYZE(
  text
  [, analyzer=>{ 'LOG_ANALYZER' | 'NO_OP_ANALYZER' | 'PATTERN_ANALYZER' }]
  [, analyzer_options=>analyzer_options_values]
)

Descrição

Extrai termos (tokens) do texto e os converte em um documento tokenizado.

Definições

  • text: valor STRING que representa o texto de entrada a ser tokenizado.

  • analyzer: argumento opcional de nome obrigatório que determina qual analisador usar para converter text em uma matriz de termos (tokens). Pode ser o seguinte:

    • 'LOG_ANALYZER' (padrão): divide a entrada em termos quando delimitadores são encontrados e, em seguida, normaliza os termos. Se analyzer não for especificado, ele será usado por padrão. Para mais informações, consulte Analisador de texto LOG_ANALYZER.

    • 'NO_OP_ANALYZER': extrai o texto como um termo único (token), mas não aplica a normalização. Para mais informações, consulte Analisador de texto NO_OP_ANALYZER.

    • 'PATTERN_ANALYZER': divide a entrada em termos que correspondem a uma expressão regular. Para mais informações, consulte Analisador de texto PATTERN_ANALYZER.

  • analyzer_options: argumento nomeado obrigatório opcional que usa uma lista de regras de análise de texto como um STRING formatado em JSON. Para mais informações, consulte Opções do analisador de texto.

Detalhes

Não há garantia quanto à ordem dos tokens produzidos por essa função.

Se nenhum analisador for especificado, o LOG_ANALYZER vai ser usado por padrão.

Tipo de retorno

ARRAY<STRING>

Exemplos

A consulta a seguir usa o analisador de texto padrão, LOG_ANALYZER, com o texto de entrada:

SELECT TEXT_ANALYZE('I like pie, you like-pie, they like 2 PIEs.') AS results

/*--------------------------------------------------------------------------*
 | results                                                                  |
 +--------------------------------------------------------------------------+
 | ['i', 'like', 'pie', 'you', 'like', 'pie', 'they', 'like', '2', 'pies' ] |
 *--------------------------------------------------------------------------*/

A consulta a seguir usa o analisador de texto NO_OP_ANALYZER com o texto de entrada:

SELECT TEXT_ANALYZE(
  'I like pie, you like-pie, they like 2 PIEs.',
  analyzer=>'NO_OP_ANALYZER'
) AS results

/*-----------------------------------------------*
 | results                                       |
 +-----------------------------------------------+
 | 'I like pie, you like-pie, they like 2 PIEs.' |
 *-----------------------------------------------*/

A consulta a seguir usa o analisador de texto PATTERN_ANALYZER com o texto de entrada:

SELECT TEXT_ANALYZE(
  'I like pie, you like-pie, they like 2 PIEs.',
  analyzer=>'PATTERN_ANALYZER'
) AS results

/*----------------------------------------------------------------*
 | results                                                        |
 +----------------------------------------------------------------+
 | ['like', 'pie', 'you', 'like', 'pie', 'they', 'like', 'pies' ] |
 *----------------------------------------------------------------*/

Para ver mais exemplos que incluem opções do analisador, consulte Análise de texto.

Para receitas úteis de analisadores que podem ser usadas para melhorar as consultas compatíveis com o analisador, consulte Pesquisar com analisadores de texto.

TF_IDF

TF_IDF(tokenized_document) OVER()

TF_IDF(tokenized_document, max_distinct_tokens) OVER()

TF_IDF(tokenized_document, max_distinct_tokens, frequency_threshold) OVER()

Descrição

Avalia a relevância de um termo para um documento tokenizado em um conjunto de documentos tokenizados, usando o algoritmo TF-IDF (frequência inversa de documentos de frequência de termo, na sigla em inglês).

Definições

  • tokenized_document: valor ARRAY<STRING> que representa um documento que foi tokenizado. Um documento tokenizado é uma coleção de termos (tokens) usados para análise de texto.

  • max_distinct_tokens: argumento opcional. Usa um valor INT64 não negativo, que representa o tamanho do dicionário, excluindo o termo desconhecido.

    Os termos são adicionados ao dicionário até que esse limite seja atingido. Portanto, se esse valor for 20, os primeiros 20 termos exclusivos serão adicionados e nenhum termo adicional será adicionado.

    Se esse argumento não for fornecido, o valor padrão será 32000. Se esse argumento for especificado, o valor máximo será 1048576.

  • frequency_threshold: argumento opcional. Usa um valor INT64 não negativo que representa o número mínimo de vezes que um termo precisa aparecer em um documento tokenizado para ser incluído no dicionário. Portanto, se esse valor for 3, um termo precisará aparecer pelo menos três vezes no documento tokenizado para ser adicionado ao dicionário.

    Se esse argumento não for fornecido, o valor padrão será 5.

Detalhes

Essa função usa um algoritmo TF-IDF (frequência de frequência inversa de documentos) para calcular a relevância dos termos em um conjunto de documentos tokenizados. O TF-IDF multiplica duas métricas: quantas vezes um termo aparece em um documento (frequência do termo) e a frequência inversa do documento do termo em uma coleção de documentos (frequência inversa de documentos).

  • TDIF:

    term frequency * inverse document frequency

  • frequência do termo:

    (count of term in document) / (document size)

  • frequência inversa do documento:

    log(1 + document set size / (1 + count of documents containing term))

Os termos são adicionados a um dicionário de termos se atenderem aos critérios de max_distinct_tokens e frequency_threshold. Caso contrário, serão considerados o termo desconhecido. O termo desconhecido é sempre o primeiro termo no dicionário e representado como NULL. O restante do dicionário é ordenado por frequência de termo, e não por ordem alfabética.

Tipo de retorno

ARRAY<STRUCT<term STRING, tf_idf DOUBLE>>

Definições:

  • term: o termo exclusivo que foi adicionado ao dicionário.
  • tf_idf: o cálculo de TF-IDF para o termo.

Exemplos

A consulta a seguir calcula a relevância de até 10 termos que aparecem pelo menos duas vezes em um conjunto de documentos tokenizados. Neste exemplo, os argumentos nomeados são transmitidos em posição. 10 representa max_distinct_tokens e 2 representa frequency_threshold:

WITH ExampleTable AS (
  SELECT 1 AS id, ['I', 'like', 'pie', 'pie', 'pie', NULL] AS f UNION ALL
  SELECT 2 AS id, ['yum', 'yum', 'pie', NULL] AS f UNION ALL
  SELECT 3 AS id, ['I', 'yum', 'pie', NULL] AS f UNION ALL
  SELECT 4 AS id, ['you', 'like', 'pie', 'too', NULL] AS f
)
SELECT id, TF_IDF(f, 10, 2) OVER() AS results
FROM ExampleTable
ORDER BY id;

/*----+-------------------------------------------------*
 | id | results                                         |
 +----+-------------------------------------------------+
 | 1  | [{"index":null,"value":"0.1304033435859887"},   |
 |    |  {"index":"I","value":"0.1412163100645339"},    |
 |    |  {"index":"like","value":"0.1412163100645339"}, |
 |    |  {"index":"pie","value":"0.29389333245105953"}] |
 +----+-------------------------------------------------+
 | 2  | [{"index":null,"value":"0.1956050153789831"},   |
 |    |  {"index":"pie","value":"0.14694666622552977"}, |
 |    |  {"index":"yum","value":"0.4236489301936017"}]  |
 +----+-------------------------------------------------+
 | 3  | [{"index":null,"value":"0.1956050153789831"},   |
 |    |  {"index":"I","value":"0.21182446509680086"},   |
 |    |  {"index":"pie","value":"0.14694666622552977"}, |
 |    |  {"index":"yum","value":"0.21182446509680086"}] |
 +----+-------------------------------------------------+
 | 4  | [{"index":null,"value":"0.4694520369095594"},   |
 |    |  {"index":"like","value":"0.1694595720774407"}, |
 |    |  {"index":"pie","value":"0.11755733298042381"}] |
 *----+-------------------------------------------------*/

A consulta a seguir calcula a relevância de até três termos que aparecem pelo menos uma vez em um conjunto de documentos tokenizados:

WITH ExampleTable AS (
  SELECT 1 AS id, ['I', 'like', 'pie', 'pie', 'pie', NULL] AS f UNION ALL
  SELECT 2 AS id, ['yum', 'yum', 'pie', NULL] AS f UNION ALL
  SELECT 3 AS id, ['I', 'yum', 'pie', NULL] AS f UNION ALL
  SELECT 4 AS id, ['you', 'like', 'pie', 'too', NULL] AS f
)
SELECT id, TF_IDF(f, 3, 2) OVER() AS results
FROM ExampleTable
ORDER BY id;

/*----+-------------------------------------------------*
 | id | results                                         |
 +----+-------------------------------------------------+
 | 1  | [{"index":null,"value":"0.12679902142647365"},  |
 |    |  {"index":"I","value":"0.1412163100645339"},    |
 |    |  {"index":"like","value":"0.1412163100645339"}, |
 |    |  {"index":"pie","value":"0.29389333245105953"}] |
 +----+-------------------------------------------------+
 | 2  | [{"index":null,"value":"0.5705955964191315"},   |
 |    |  {"index":"pie","value":"0.14694666622552977"}] |
 +----+-------------------------------------------------+
 | 3  | [{"index":null,"value":"0.380397064279421"},    |
 |    |  {"index":"I","value":"0.21182446509680086"},   |
 |    |  {"index":"pie","value":"0.14694666622552977"}] |
 +----+-------------------------------------------------+
 | 4  | [{"index":null,"value":"0.45647647713530515"},  |
 |    |  {"index":"like","value":"0.1694595720774407"}, |
 |    |  {"index":"pie","value":"0.11755733298042381"}] |
 *----+-------------------------------------------------*/