The ML.BAG_OF_WORDS function

Use a função ML.BAG_OF_WORDS para calcular uma representação de documentos tokenizados como o pacote (multiconjunto) das palavras, desconsiderando a ordem e a gramática das palavras. É possível usar ML.BAG_OF_WORDS na cláusula TRANSFORM.

Sintaxe

ML.BAG_OF_WORDS(
  tokenized_document
  [, top_k]
  [, frequency_threshold]
)
OVER()

Argumentos

ML.BAG_OF_WORDS usa os seguintes argumentos:

  • 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. Para mais informações sobre tokenização no BigQuery, consulte TEXT_ANALYZE.
  • top_k: argumento opcional. Usa um valor INT64, que representa o tamanho do dicionário, excluindo o termo desconhecido. Os termos de top_k que aparecem na maioria dos documentos são adicionados ao dicionário até que esse limite seja atingido. Por exemplo, se esse valor for 20, os 20 principais termos exclusivos que aparecem na maioria dos documentos serão adicionados e nenhum outro termo será adicionado.
  • frequency_threshold: argumento opcional. Usa um valor INT64 que representa o número mínimo de documentos em que um termo precisa aparecer para ser incluído no dicionário. Por exemplo, se esse valor for 3, um termo precisará aparecer pelo menos três vezes no documento tokenizado para ser adicionado ao dicionário.

Os termos são adicionados a um dicionário de termos se atenderem aos critérios de top_k 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 0. O restante do dicionário está em ordem alfabética.

Saída

ML.BAG_OF_WORDS retorna um valor para cada linha na entrada. Cada valor tem o seguinte tipo:

ARRAY<STRUCT<index INT64, value FLOAT64>>

Definições:

  • index: o índice do termo que foi adicionado ao dicionário. Os termos desconhecidos têm um índice de 0.
  • value: as contagens correspondentes no documento.

Cotas

Consulte Cotas e limites de funções de serviço da IA do Cloud.

Exemplo

O exemplo a seguir chama a função ML.BAG_OF_WORDS em uma coluna de entrada f, sem termos desconhecidos:

WITH ExampleTable AS (
  SELECT 1 AS id, ['a', 'b', 'b', 'c'] AS f
  UNION ALL
  SELECT 2 AS id, ['a', 'c'] AS f
)

SELECT ML.BAG_OF_WORDS(f, 32, 1) OVER() AS results
FROM ExampleTable
ORDER BY id;

O resultado será assim: 

+----+---------------------------------------------------------------------------------------+
| id |                                        results                                        |
+----+---------------------------------------------------------------------------------------+
|  1 | [{"index":"1","value":"1.0"},{"index":"2","value":"2.0"},{"index":"3","value":"1.0"}] |
|  2 |                             [{"index":"1","value":"1.0"},{"index":"3","value":"1.0"}] |
+----+---------------------------------------------------------------------------------------+

Não há índice 0 no resultado, porque não há termos desconhecidos.

O exemplo a seguir chama a função ML.BAG_OF_WORDS em uma coluna de entrada f:

WITH ExampleTable AS (
  SELECT 1 AS id, ['a', 'b', 'b', 'b', 'c', 'c', 'c', 'c', 'd', 'd'] AS f
  UNION ALL
  SELECT 2 AS id, ['a', 'c', NULL] AS f
)

SELECT ML.BAG_OF_WORDS(f, 4, 2) OVER() AS results
FROM ExampleTable
ORDER BY id;

O resultado será assim: 

+----+---------------------------------------------------------------------------------------+
| id |                                        results                                        |
+----+---------------------------------------------------------------------------------------+
|  1 | [{"index":"0","value":"5.0"},{"index":"1","value":"1.0"},{"index":"2","value":"4.0"}] |
|  2 | [{"index":"0","value":"1.0"},{"index":"1","value":"1.0"},{"index":"2","value":"1.0"}] |
+----+---------------------------------------------------------------------------------------+

Observe que os valores de b e d não são retornados porque aparecem em apenas um documento quando o valor de frequency_threshold está definido como 2.

O exemplo a seguir chama a função ML.BAG_OF_WORDS com um valor menor de top_k:

WITH ExampleTable AS (
  SELECT 1 AS id, ['a', 'b', 'b', 'c'] AS f
  UNION ALL
  SELECT 2 AS id, ['a', 'c', 'c'] AS f
)

SELECT ML.BAG_OF_WORDS(f, 2, 1) OVER() AS results
FROM ExampleTable
ORDER BY id;

O resultado será assim: 

+----+---------------------------------------------------------------------------------------+
| id |                                        results                                        |
+----+---------------------------------------------------------------------------------------+
|  1 | [{"index":"0","value":"2.0"},{"index":"1","value":"1.0"},{"index":"2","value":"1.0"}] |
|  2 |                             [{"index":"1","value":"1.0"},{"index":"2","value":"2.0"}] |
+----+---------------------------------------------------------------------------------------+

Observe como o valor de b não é retornado porque especificamos que queremos os dois termos principais, e b aparece apenas em um documento.

O exemplo a seguir contém dois termos com a mesma frequência. Um dos termos foi excluído dos resultados devido à ordem alfabética.

WITH ExampleData AS (
  SELECT 1 AS id, ['a', 'b', 'b', 'c', 'd', 'd', 'd'] as f
  UNION ALL
  SELECT 2 AS id, ['a', 'c', 'c', 'd', 'd', 'd'] as f
)

SELECT id, ML.BAG_OF_WORDS(f, 2 ,2) OVER() as result
FROM ExampleData
ORDER BY id;

Os resultados têm a seguinte aparência:

+----+---------------------------------------------------------------------------------------+
| id |                                         result                                        |
+----+---------------------------------------------------------------------------------------+
|  1 | [{"index":"0","value":"5.0"},{"index":"1","value":"1.0"},{"index":"2","value":"1.0"}] |
|  2 | [{"index":"0","value":"3.0"},{"index":"1","value":"1.0"},{"index":"2","value":"2.0"}] |
+----+---------------------------------------------------------------------------------------+

A seguir