テキスト分析関数

GoogleSQL for BigQuery は、次のテキスト分析関数をサポートしています。

関数リスト

名前	概要
`BAG_OF_WORDS`	トークン化されたドキュメントの各用語（トークン）の頻度を取得します。
`TEXT_ANALYZE`	テキストから用語（トークン）を抽出し、トークン化されたドキュメントに変換します。
`TF_IDF`	一連のトークン化されたドキュメントにおける、ある用語（トークン）とトークン化されたドキュメントの関連性を評価します。

`BAG_OF_WORDS`

BAG_OF_WORDS(tokenized_document)

定義

トークン化されたドキュメントの各用語（トークン）の頻度を取得します。

用語の定義

tokenized_document: トークン化されたドキュメントを表す ARRAY<STRING> 値。トークン化されたドキュメントは、テキスト分析に使用される用語（トークン）の集まりです。

戻り値の型

ARRAY<STRUCT<term STRING, count INT64>>

用語の定義:

term: トークン化されたドキュメント内の一意の用語。
count: トークン化されたドキュメントで用語が検出された回数。

例

次のクエリは、2 つのトークン化されたドキュメントにおける用語と、その頻度を生成します。

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]
)

説明

テキストから用語（トークン）を抽出し、トークン化されたドキュメントに変換します。

用語の定義

text: トークン化する入力テキストを表す STRING 値。
analyzer: text を用語（トークン）の配列に変換するためにどのアナライザを使用するかを決定する、オプションの必須名前付き引数。以下に例を示します。
- 'LOG_ANALYZER'（デフォルト）: 区切り文字が検出されると入力を用語に分割し、正規化します。analyzer が指定されていない場合は、デフォルトでこれが使用されます。詳細については、LOG_ANALYZER テキストアナライザをご覧ください。
- 'NO_OP_ANALYZER': テキストを 1 つの用語（トークン）として抽出しますが、正規化は適用しません。詳細については、NO_OP_ANALYZER テキストアナライザをご覧ください。
- 'PATTERN_ANALYZER': 入力を、正規表現に一致する用語に分割します。詳細については、PATTERN_ANALYZER テキストアナライザをご覧ください。
analyzer_options: テキスト分析ルールのリストを JSON 形式の STRING として受け取るオプションの必須名前付き引数。詳細については、テキストアナライザのオプションをご覧ください。

詳細

この関数によって生成されるトークンの順序は保証されません。

アナライザが指定されていない場合、デフォルトで LOG_ANALYZER アナライザが使用されます。

戻り値の型

ARRAY<STRING>

例

次のクエリでは、デフォルトのテキストアナライザ LOG_ANALYZER と入力テキストを使用します。

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' ] |
 *--------------------------------------------------------------------------*/

次のクエリは、入力テキストとともに NO_OP_ANALYZER テキストアナライザを使用します。

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.' |
 *-----------------------------------------------*/

次のクエリは、入力テキストとともに PATTERN_ANALYZER テキストアナライザを使用します。

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' ] |
 *----------------------------------------------------------------*/

アナライザオプションを含むその他の例については、テキスト分析をご覧ください。

アナライザでサポートされているクエリを拡張するために使用できる便利なアナライザの使い方については、テキストアナライザを使用して検索するをご覧ください。

`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()

説明

TF-IDF（用語頻度 - 逆文書頻度）アルゴリズムを使用して、一連のトークン化されたドキュメントにおける、ある用語とトークン化されたドキュメントの関連性を評価します。

用語の定義

tokenized_document: トークン化されたドキュメントを表す ARRAY<STRING> 値。トークン化されたドキュメントは、テキスト分析に使用される用語（トークン）の集まりです。
max_distinct_tokens: 省略可能な引数。負でない INT64 値を取ります。この値は、不明な用語を除いた辞書のサイズを表します。

このしきい値に達するまで、用語は辞書に追加されます。そのため、この値が 20 の場合、最初の 20 個の一意の用語が追加され、その後は追加されません。

この引数を指定しない場合、デフォルト値は 32000 です。この引数を指定する場合、最大値は 1048576 です。
frequency_threshold: 省略可能な引数。負でない INT64 値を取ります。辞書に含めるために、ある用語がトークン化されたドキュメントに出現しなければならない最小回数を表します。そのため、この値が 3 の場合、辞書に追加されるには、トークン化されたドキュメント内で用語が 3 回以上出現する必要があります。

この引数を指定しない場合、デフォルト値は 5 です。

詳細

この関数は、TF-IDF（用語頻度 - 逆文書頻度）アルゴリズムを使用して、一連のトークン化されたドキュメントにおける用語の関連性を計算します。TF-IDF は、「あるドキュメントにおける用語の出現回数（用語頻度）」と、「ドキュメントのコレクション全体における当該用語の逆文書頻度（逆文書頻度）」という 2 つの指標を乗算します。

TDIF:

term frequency * inverse document frequency

用語頻度:

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

逆文書頻度:

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

max_distinct_tokens と frequency_threshold の条件を満たしていれば、用語が辞書に追加されます。条件を満たしていない場合は、不明な用語とみなされます。不明な用語は常に辞書の最初の用語になり、NULL として表されます。辞書の残りの部分は、アルファベット順ではなく、用語頻度順に並べられます。

戻り値の型

ARRAY<STRUCT<term STRING, tf_idf DOUBLE>>

用語の定義:

term: 辞書に追加された固有の用語。
tf_idf: 用語の TF-IDF 計算。

例

次のクエリは、一連のトークン化されたドキュメントに少なくとも 2 回出現する、最大 10 個の用語の関連性を計算します。この例では、名前付き引数が正しい位置で渡されています。10 は max_distinct_tokens を表し、2 は 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"}] |
 *----+-------------------------------------------------*/

次のクエリは、一連のトークン化されたドキュメントに少なくとも 1 回出現する、最大 3 個の用語の関連性を計算します。

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