# groonga - オープンソースのカラムストア機能付き全文検索エンジン

- English

# 7.3.48. `reference_acquire`

## 7.3.48.1. 概要

バージョン 10.0.4 で追加.

`reference_acquire` は対象オブジェクトの参照を1つ増やします。

このコマンドはリファレンスカウントモードのとき以外は意味がありません。リファレンスカウントモードを有効にするには `GRN_ENABLE_REFERENCE_COUNT=yes` 環境変数を使います。

オブジェクトの参照を1つ増やすとそのオブジェクトは自動的にクローズされません。なぜなら少なくとも1つそのオブジェクトの参照があるからです。短期間に複数の load を実行する場合、リファレンスカウントモードによる自動クローズは性能劣化を引き起こすでしょう。 `reference_acquire` を実行してから複数の load 実行し、 load の後に reference_release を実行するとこの性能劣化を避けることができます。 `reference_acquire` と reference_release の間は自動クローズが無効になります。

性能に影響がある操作を実行したら reference_release を実行しなければいけません。 reference_release を実行しないとリファレンスカウントモードが動きません。

## 7.3.48.2. 構文

このコマンドには2つの引数があります。

すべての引数は省略可能です:

    reference_acquire [target_name=null]
                      [recursive=yes]

## 7.3.48.3. 使い方

引数無しで実行するとすべてのテーブル・カラムの参照を1つ増やすことができます。

実行例:

    reference_acquire
    # [[0, 1337566253.89858, 0.000355720520019531], true]

なにを参照するべきかわかっているなら対象を狭めることができます。

使い方を示すために使うスキーマ定義は以下の通りです。

実行例:

    table_create Users TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Users age COLUMN_SCALAR UInt8
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Users introduction COLUMN_SCALAR ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Ages TABLE_PAT_KEY UInt8
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Ages user_age COLUMN_INDEX Users age
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`Users` テーブルに対して条件なしの複数の select を実行するときは、次のコマンドで `Users` と `Users.age` と `Users.introduction` の参照を1つ増やします。

実行例:

    reference_acquire --target_name Users
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`Users` テーブルに対してインデックスを使う条件で複数の select を実行するときは、次のコマンドで `Users` と `Users.age` と `Users.introduction` と `Ages` （語彙表）と `Ages.user_age` （インデックスカラム）の参照を1つ増やせます。このコマンドは load を実行するときでも適切です。

実行例:

    reference_acquire --target_name Users --recursive dependent
    # [[0, 1337566253.89858, 0.000355720520019531], true]

単に `Users` の参照を1つ増やしたいだけなら、テーブルと `recursive=no` を指定します。

実行例:

    reference_acquire --target_name Users --recursive no
    # [[0, 1337566253.89858, 0.000355720520019531], true]

単に `Users.introduction` の参照を1つ増やしたいだけなら、カラムを指定します。

実行例:

    reference_acquire --target_name Users.introduction
    # [[0, 1337566253.89858, 0.000355720520019531], true]

同じ引数で reference_release を実行すると増やした参照を1つ減らせます。

実行例:

    reference_acquire --target_name Users --recursive dependent
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    # select Users ...
    # load --table Users ...
    reference_release --target_name Users --recursive dependent
    # [[0, 1337566253.89858, 0.000355720520019531], true]

## 7.3.48.4. 引数

このセクションではすべての引数について説明します。

### 7.3.48.4.1. 必須引数

必須の引数はありません。

### 7.3.48.4.2. 省略可能引数

いくつか省略可能な引数があります。

#### 7.3.48.4.2.1. `target_name`

対象オブジェクトの名前を指定します。対象オブジェクトはデータベース、テーブル、カラムのどれかです。

このパラメーターを省略すると、データベースが対象オブジェクトになります。

実行例:

    reference_acquire
    # [[0, 1337566253.89858, 0.000355720520019531], true]

テーブル名を指定すると、そのテーブルが対象オブジェクトになります。

実行例:

    reference_acquire --target_name Users
    # [[0, 1337566253.89858, 0.000355720520019531], true]

カラム名を指定すると、そのカラムが対象オブジェクトになります。

実行例:

    reference_acquire --target_name Users.age
    # [[0, 1337566253.89858, 0.000355720520019531], true]

#### 7.3.48.4.2.2. `recursive`

書き出し対象オブジェクトの子オブジェクトも対象にするかどうかを指定します。

データベースの子オブジェクトはすべてのテーブルとすべてのカラムです。

テーブルの子オブジェクトはそのテーブルのすべてのカラムです。

カラムの子オブジェクトはありません。

`recursive` の値は `yes` または `no` もしくは `dependent` でなければいけません。 `yes` は指定した対象オブジェクトとその子オブジェクトすべてを対象オブジェクトにするという意味です。 `no` は指定した対象オブジェクトのみを対象オブジェクトにするという意味です。`dependent` は指定した対象オブジェクトとその子オブジェクトすべて、参照先のテーブル、インデックスが張られているカラムがある場合、対応するインデックスカラムとそのインデックスカラムのテーブルを対象オブジェクトにするという意味です。

次の `reference_acquire` はデータベースとすべてのテーブルとすべてのカラムの参照を1つ増やします。

実行例:

    reference_acquire --recursive yes
    # [[0, 1337566253.89858, 0.000355720520019531], true]

次の `reference_acquire` は `Users` テーブルだけの参照を1つ増やします。

実行例:

    reference_acquire --target_name Users --recursive no
    # [[0, 1337566253.89858, 0.000355720520019531], true]

他の値（つまり、 `yes` でも `no` でもない値）を指定した場合、または `recursive` パラメーターを指定しない場合は `yes` が使われます。

`recursive` 引数の値が不正なので、次のケースでは `yes` が使われます。

実行例:

    reference_acquire --target_name Users --recursive invalid
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`recursive` パラメーターが指定されていないので、次のケースでは `yes` が使われます。

実行例:

    reference_acquire --target_name Users
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`dependent` は対象オブジェクトとその子オブジェクトの参照を1つ増やすだけではなく、関連するオブジェクトの参照も1つ増やします。関連するオブジェクトは次のとおりです。

- 参照されているテーブル

- 参照されているテーブルのカラム

- 関連するインデックスカラム(対象の `TABLE_NAME` にソースカラムがある)

- 関連するインデックスカラムのテーブル(対象の `TABLE_NAME` にソースカラムがある)

- 関連するインデックスカラムのテーブルのカラム

これは load と select 用に参照を維持するために便利です。

`Users` テーブルに対して複数の load を実行するときは、次のコマンドを使います。

実行例:

    reference_acquire --target_name Users --recursive dependent
    # [[0, 1337566253.89858, 0.000355720520019531], true]

## 7.3.48.5. 戻り値

このコマンドが成功したときは以下のようにボディは `true` になります:

    [HEADER, true]

このコマンドが失敗すると、 `HEADER` にエラーの詳細が含まれます。

`HEADER` については 出力形式 を参照してください。