7.3.48. reference_acquire

7.3.48.1. Summary

New 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.

7.3.48.2. Syntax

This command takes two parameters.

All parameters are optional:

reference_acquire [target_name=null]
                  [recursive=yes]

7.3.48.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.48.4. Parameters

This section describes all parameters.

7.3.48.4.1. Required parameters

There is no required parameter.

7.3.48.4.2. Optional parameters

There are optional parameters.

7.3.48.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.48.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

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

  • 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.48.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.