Skip to main content
`Ctrl`+`K`

# 7.3.51. `reference_acquire`

## 7.3.51.1. Summary

Added in version 10.0.4.

`reference_acquire` acquires a reference of target objects.

This command is meaningless unless you use the reference count mode. You can enable the reference count mode by the `GRN_ENABLE_REFERENCE_COUNT=yes` environment variable.

If you acquires a reference of an object, the object isn’t closed automatically because you have at least one reference of the object. If you need to call multiple load in a short time, auto close by the reference count mode will degrade performance. You can avoid the performance degrading by calling `reference_acquire` before multiple load and calling reference_release after multiple load. Between `reference_acquire` and reference_release, auto close is disabled.

You must call reference_release after you finish performance impact operations. If you don’t call reference_release, the reference count mode doesn’t work.

You can use auto_release_count instead of calling reference_release. You can release acquired references automatically by auto_release_count. But you need to tune suitable auto_release_count value. If you specify too large number, auto close isn’t triggered. If you specify too small number, auto close is triggered before performance impact operations are finished.

## 7.3.51.2. Syntax

This command takes two parameters.

All parameters are optional:

    reference_acquire [target_name=null]
                      [recursive=yes]
                      [auto_release_count=0]

## 7.3.51.3. Usage

You can acquire a reference of the all objects with no arguments:

Execution example:

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

If you know what should be referred, you can narrow targets.

Here is a schema definition to show usage:

Execution example:

    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]

If you want to call multiple select without any condition against `Users` table, the following command acquires a reference of `Users`, `Users.age` and `Users.introduction`:

Execution example:

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

If you want to call multiple select with condition that uses indexes against `Users` table, the following command acquires a reference of `Users`, `Users.age`, `Users.introduction`, `Ages` (lexicon) and `Ages.user_age` (index column). This command is suitable for load too:

Execution example:

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

If you want to just refer `Users`, you can specify a table with `recursive=no`:

Execution example:

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

If you want to just refer `Users.introduction`, you can specify a column:

Execution example:

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

You can release acquired references by calling reference_release with the same arguments:

Execution example:

    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.51.4. Parameters

This section describes all parameters.

### 7.3.51.4.1. Required parameters

There is no required parameter.

### 7.3.51.4.2. Optional parameters

There are optional parameters.

#### 7.3.51.4.2.1. `target_name`

Specifies a target object name. Target object is one of database, table or column.

If you omit this parameter, database is the target object:

Execution example:

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

If you specify a table name, the table is the target object:

Execution example:

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

If you specify a column name, the column is the target object:

Execution example:

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

#### 7.3.51.4.2.2. `recursive`

Specifies whether child objects of the target object are also target objects.

Child objects of database are all tables and all columns.

Child objects of table are all its columns.

Child objects of column are nothing.

`recursive` value must be `yes`, `no` or `dependent`. `yes` means that all of the specified target object and child objects are the target objects. `no` means that only the specified target object is the target object. `dependent` means that all of the specified target object, child objects, corresponding table of index column and corresponding index column are the target objects.

The following `reference_acquire` acquires a reference of all tables and all columns:

Execution example:

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

The following `reference_acquire` acquires a reference of only `Users` table:

Execution example:

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

If you specify other value (not `yes` neither `no`) or omit `recursive` parameter, `yes` is used.

`yes` is used in the following case because invalid `recursive` argument is specified:

Execution example:

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

`yes` is used in the following case because `recursive` parameter isn’t specified:

Execution example:

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

`dependent` acquires a reference of not only the target object and the child objects but also related objects. The related objects are:

- A referenced table

- Data columns of referenced tables

- A related index column (There is source column in target `TABLE_NAME`)

- A table of related index column (There is source column in target `TABLE_NAME`)

- Data columns of tables of related index columns

It is useful to keep reference for load and select.

If you want to call multiple load for `Users` table, you can use the following command:

Execution example:

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

#### 7.3.51.4.2.3. `auto_release_count`

Added in version 10.0.9.

You can release acquired references automatically by `auto_release_count`.

If `auto_release_count` is 1 or greater, acquired references are automatically after the following `auto_release_count` commands are processed. You must not call corresponding reference_release when you use `auto_release_count`.

In the following example, the acquired reference of `Users` is released automatically after the second `status` is processed:

    reference_acquire --target_name Users --auto_release_count 2
    status # Users is still referred.
    status # Users' reference is released after this command is processed.

The same recursive is used when acquired references are released automatically. You don’t need to care about recursive.

`auto_release_count` is safe with table_remove, column_remove and database_unmap. If one of them are called, registered auto release hook is removed internally.

## 7.3.51.5. Return value

The command returns `true` as body on success such as:

    [HEADER, true]

If the command fails, error details are in `HEADER`.

See Output format for `HEADER`.