<commit_before>===========================
Direct I/OのTSVファイル連携
===========================

この文書では、Direct I/Oを使ってTSVフォーマットのファイルをインポート/エクスポートするための拡張機能の使い方について説明します。

Mavenアーティファクト
=====================
Direct I/OのTSVファイル連携モジュールはAsakusa FrameworkのMavenリポジトリに
グループID ``com.asakusafw.sandbox`` を持つMavenアーティファクトとして登録されています。

..  list-table:: Direct I/OのTSVファイル連携で使用するMavenアーティファクト
    :widths: 5 5 
    :header-rows: 1

    * - グループID
      - アーティファクトID
    * - ``com.asakusafw.sandbox``
      - ``asakusa-directio-dmdl-ext``

TSVファイル連携モジュールの利用方法
===================================

Gradleプロジェクト
------------------
GradleプロジェクトでTSVファイル連携モジュールを使用する場合は
``build.gradle`` の ``dependencies`` ブロック内に ``compile`` 依存関係(コンフィグレーション)に対して
依存定義を追加します。

..  code-block:: groovy

    dependencies {
        ...
        compile group: 'com.asakusafw.sandbox', name: 'asakusa-directio-dmdl-ext', version: asakusafw.asakusafwVersion

Mavenプロジェクト
=================
MavenプロジェクトでTSVファイル連携モジュールを使用する場合は
Direct I/O用アーキタイプ ``asakusa-archetype-directio`` から作成したプロジェクトの ``pom.xml`` に以下の依存性定義を追加します。

..  code-block:: xml

	<dependencies>
        ...
		<dependency>
			<groupId>com.asakusafw.sandbox</groupId>
			<artifactId>asakusa-directio-dmdl-ext</artifactId>
			<version>${asakusafw.version}</version>
			<scope>compile</scope>
		</dependency>

モデルクラスの生成
==================

DMDLに対するTSVファイル用拡張属性の追加
---------------------------------------
TSVファイル連携を行うために、DMDLに対してTSVファイルを扱うことを示す拡張属性を追加します。

各モデルのDMDLスクリプトに対して、モデル名の記述行の前行に拡張属性 ``@directio.tsv`` を付与します。

以下にTSVファイルを扱う場合のDMDLスクリプトの例を示します。

..  code-block:: sh

    "テーブルEX1"
    ...
    @directio.tsv
    ex1 = {
        "SID"
        sid : LONG;
        "VALUE"
        value : INT;
        "STRING"
        string : TEXT;
    };

TSV形式の設定
~~~~~~~~~~~~~
``@directio.tsv`` 属性には、次のような要素を指定できます。

..  list-table:: TSV形式の設定
    :widths: 10 10 20 60
    :header-rows: 1

    * - 要素
      - 型
      - 既定値
      - 内容
    * - ``charset``
      - 文字列
      - ``"UTF-8"``
      - ファイルの文字エンコーディング
    * - ``has_header``
      - 論理値
      - ``FALSE``
      - ``TRUE`` に設定すると、読み込み時に先頭行をスキップし、書き込み時にモデルの定義内容に応じたヘッダ行を生成する。
    * - ``compression``
      - 文字列
      - なし
      - ファイルの圧縮コーデック

``compression`` には、 ``"gzip"`` または ``org.apache.hadoop.io.compress.CompressionCodec`` のサブタイプのクラス名を指定します [#]_ 。
ここで指定した圧縮形式で対象のファイルが読み書きされるようになりますが、代わりにファイルの分割読み出しが行われなくなります。

以下はDMDLスクリプトの記述例です。

..  code-block:: none

    @directio.tsv(
        charset = "ISO-2022-JP",
        has_header = TRUE,
        compression = "gzip",
    )
    model = {
        ...
    };

..  [#] ``org.apache.hadoop.io.compress.DefaultCodec`` などが標準で用意されています

ヘッダの設定
~~~~~~~~~~~~
`TSV形式の設定`_ でヘッダを有効にしている場合、出力の一行目にプロパティ名が表示されます。
ここで表示される内容を変更するには、それぞれのプロパティに ``@directio.tsv.field`` 属性を指定し、さらに ``name`` 要素でフィールド名を指定します。

以下はヘッダの内容の付加したDMDLスクリプトの記述例です。

..  code-block:: none

    @directio.tsv
    document = {
        "the name of this document"
        @directio.tsv.field(name = "題名")
        name : TEXT;<commit_msg>Add allow-linefeed for Direct I/O TSV (#420,#434).<commit_after>===========================
Direct I/OのTSVファイル連携
===========================

この文書では、Direct I/Oを使ってTSVフォーマットのファイルをインポート/エクスポートするための拡張機能の使い方について説明します。

Mavenアーティファクト
=====================
Direct I/OのTSVファイル連携モジュールはAsakusa FrameworkのMavenリポジトリに
グループID ``com.asakusafw.sandbox`` を持つMavenアーティファクトとして登録されています。

..  list-table:: Direct I/OのTSVファイル連携で使用するMavenアーティファクト
    :widths: 5 5 
    :header-rows: 1

    * - グループID
      - アーティファクトID
    * - ``com.asakusafw.sandbox``
      - ``asakusa-directio-dmdl-ext``

TSVファイル連携モジュールの利用方法
===================================

Gradleプロジェクト
------------------
GradleプロジェクトでTSVファイル連携モジュールを使用する場合は
``build.gradle`` の ``dependencies`` ブロック内に ``compile`` 依存関係(コンフィグレーション)に対して
依存定義を追加します。

..  code-block:: groovy

    dependencies {
        ...
        compile group: 'com.asakusafw.sandbox', name: 'asakusa-directio-dmdl-ext', version: asakusafw.asakusafwVersion

Mavenプロジェクト
=================
MavenプロジェクトでTSVファイル連携モジュールを使用する場合は
Direct I/O用アーキタイプ ``asakusa-archetype-directio`` から作成したプロジェクトの ``pom.xml`` に以下の依存性定義を追加します。

..  code-block:: xml

	<dependencies>
        ...
		<dependency>
			<groupId>com.asakusafw.sandbox</groupId>
			<artifactId>asakusa-directio-dmdl-ext</artifactId>
			<version>${asakusafw.version}</version>
			<scope>compile</scope>
		</dependency>

モデルクラスの生成
==================

DMDLに対するTSVファイル用拡張属性の追加
---------------------------------------
TSVファイル連携を行うために、DMDLに対してTSVファイルを扱うことを示す拡張属性を追加します。

各モデルのDMDLスクリプトに対して、モデル名の記述行の前行に拡張属性 ``@directio.tsv`` を付与します。

以下にTSVファイルを扱う場合のDMDLスクリプトの例を示します。

..  code-block:: sh

    "テーブルEX1"
    ...
    @directio.tsv
    ex1 = {
        "SID"
        sid : LONG;
        "VALUE"
        value : INT;
        "STRING"
        string : TEXT;
    };

TSV形式の設定
~~~~~~~~~~~~~
``@directio.tsv`` 属性には、次のような要素を指定できます。

..  list-table:: TSV形式の設定
    :widths: 10 10 20 60
    :header-rows: 1

    * - 要素
      - 型
      - 既定値
      - 内容
    * - ``charset``
      - 文字列
      - ``"UTF-8"``
      - ファイルの文字エンコーディング
    * - ``allow_linefeed``
      - 論理値
      - ``FALSE``
      - ``TRUE`` で値内にLFを含められる。 ``FALSE`` で不許可
    * - ``has_header``
      - 論理値
      - ``FALSE``
      - ``TRUE`` に設定すると、読み込み時に先頭行をスキップし、書き込み時にモデルの定義内容に応じたヘッダ行を生成する。
    * - ``compression``
      - 文字列
      - なし
      - ファイルの圧縮コーデック

``compression`` には、 ``"gzip"`` または ``org.apache.hadoop.io.compress.CompressionCodec`` のサブタイプのクラス名を指定します [#]_ 。
ここで指定した圧縮形式で対象のファイルが読み書きされるようになりますが、代わりにファイルの分割読み出しが行われなくなります。

..  attention::
    デフォルトでは ``allow_linefeed`` には ``FALSE`` が設定されていて、文字列の内部などに改行文字 LF を含められないようになっています。
    この設定を ``TRUE`` にすることでLFを含められるようになりますが、代わりに :ref:`directio-input-split` が行われなくなります。

以下はDMDLスクリプトの記述例です。

..  code-block:: none

    @directio.tsv(
        charset = "ISO-2022-JP",
        has_header = TRUE,
        compression = "gzip",
    )
    model = {
        ...
    };

..  [#] ``org.apache.hadoop.io.compress.DefaultCodec`` などが標準で用意されています

ヘッダの設定
~~~~~~~~~~~~
`TSV形式の設定`_ でヘッダを有効にしている場合、出力の一行目にプロパティ名が表示されます。
ここで表示される内容を変更するには、それぞれのプロパティに ``@directio.tsv.field`` 属性を指定し、さらに ``name`` 要素でフィールド名を指定します。

以下はヘッダの内容の付加したDMDLスクリプトの記述例です。

..  code-block:: none

    @directio.tsv
    document = {
        "the name of this document"
        @directio.tsv.field(name = "題名")
        name : TEXT;
{'fraction_non_alphanumeric': 0.19387432901799811, 'fraction_numerical': 0.006946637196084623, 'mean_word_length': 3.045338441890166, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 25, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7472797', 'n_tokens_mistral': 3660, 'n_tokens_neox': 3450, 'n_words': 333}