# groonga - An open-source fulltext search engine and column store.

- 日本語

# 7.21.18. `grn_obj`

## 7.21.18.1. Summary

TODO...

## 7.21.18.2. Example

TODO...

## 7.21.18.3. Reference

`grn_obj`

  TODO...

grn_obj *`grn_obj_column`(grn_ctx *ctx, grn_obj *table, const char *name, unsigned int name_size)

  nameがカラム名の場合、それに対応するtableのカラムを返します。対応するカラムが存在しなければNULLを返します。

  nameはアクセサ文字列の場合、それに対応するaccessorを返します。アクセサ文字列とは、カラム名等を'.'で連結した文字列です。'_id', '_key'は特殊なアクセサで、それぞれレコードID/keyを返します。例) 'col1' / 'col2.col3' / 'col2._id'

  Parameters: | table -- 対象tableを指定します。 name -- カラム名を指定します。

grn_bool `grn_obj_is_builtin`(grn_ctx *ctx, grn_obj *obj)

  Check whether Groonga built-in object.

  Parameters: | ctx -- context obj -- target object
  Returns: | `GRN_TRUE` for built-in groonga object, `GRN_FALSE` otherwise.

grn_obj *`grn_obj_get_value`(grn_ctx *ctx, grn_obj *obj, grn_id id, grn_obj *value)

  objのIDに対応するレコードのvalueを取得します。valueを戻り値として返します。

  Parameters: | obj -- 対象objectを指定します。 id -- 対象レコードのIDを指定します。 value -- 値を格納するバッファ（呼出側で準備する）を指定します。

int `grn_obj_get_values`(grn_ctx *ctx, grn_obj *obj, grn_id offset, void **values)

  objに指定されたカラムについて、offsetに指定されたレコードIDを開始位置として、IDが連続するレコードに対応するカラム値が昇順に格納された配列へのポインタをvaluesにセットします。

  取得できた件数が戻り値として返されます。エラーが発生した場合は -1 が返されます。

  Note

  値が固定長であるカラムのみがobjに指定できます。範囲内のIDに対応するレコードが有効であるとは限りません。delete操作を実行したことのあるテーブルに対しては、`grn_table_at()` などによって各レコードの存否を別途確認しなければなりません。

  Parameters: | obj -- 対象objectを指定します。 offset -- 値を取得する範囲の開始位置となるレコードIDを指定します。 values -- 値の配列がセットされます。

grn_rc `grn_obj_set_value`(grn_ctx *ctx, grn_obj *obj, grn_id id, grn_obj *value, int flags)

  objのIDに対応するレコードの値を更新します。対応するレコードが存在しない場合は `GRN_INVALID_ARGUMENT` を返します。

  - Parameters: | obj -- 対象objectを指定します。 id -- 対象レコードのIDを指定します。 value -- 格納する値を指定します。 flags -- 以下の値を指定できます。
    `GRN_OBJ_SET` `GRN_OBJ_INCR` `GRN_OBJ_DECR` | `GRN_OBJ_APPEND` `GRN_OBJ_PREPEND` `GRN_OBJ_GET` | `GRN_OBJ_COMPARE` `GRN_OBJ_LOCK` `GRN_OBJ_UNLOCK`

`GRN_OBJ_SET_MASK`

`GRN_OBJ_SET`

  レコードの値をvalueと置き換えます。

`GRN_OBJ_INCR`

  レコードの値にvalueを加算します。

`GRN_OBJ_DECR`

  レコードの値にvalueを減算します。

`GRN_OBJ_APPEND`

  レコードの値の末尾にvalueを追加します。

`GRN_OBJ_PREPEND`

  レコードの値の先頭にvalueを追加します。

`GRN_OBJ_GET`

  新しいレコードの値をvalueにセットします。

`GRN_OBJ_COMPARE`

  レコードの値とvalueが等しいか調べます。

`GRN_OBJ_LOCK`

  当該レコードをロックします。`GRN_OBJ_COMPARE` と共に指定された場合は、レコードの値とvalueが等しい場合に限ってロックします。

`GRN_OBJ_UNLOCK`

  当該レコードのロックを解除します。

grn_rc `grn_obj_remove`(grn_ctx *ctx, grn_obj *obj)

  objをメモリから解放し、それが永続オブジェクトであった場合は、該当するファイル一式を削除します。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_rename`(grn_ctx *ctx, grn_obj *obj, const char *name, unsigned int name_size)

  ctxが使用するdbにおいてobjに対応する名前をnameに更新します。objは永続オブジェクトでなければいけません。

  Parameters: | obj -- 対象objectを指定します。 name -- 新しい名前を指定します。 name_size -- nameパラメータのsize（byte）を指定します。

grn_rc `grn_obj_close`(grn_ctx *ctx, grn_obj *obj)

  一時的なobjectであるobjをメモリから解放します。objに属するobjectも再帰的にメモリから解放されます。

  永続的な、table, column, exprなどは解放してはいけません。一般的には、一時的か永続的かを気にしなくてよい `grn_obj_unlink()` を用いるべきです。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_reinit`(grn_ctx *ctx, grn_obj *obj, grn_id domain, unsigned char flags)

  objの型を変更します。

  objは `GRN_OBJ_INIT()` マクロなどで初期化済みでなければいけません。

  Parameters: | obj -- 対象objectを指定します。 domain -- 変更後のobjの型を指定します。 flags -- `GRN_OBJ_VECTOR` を指定するとdomain型の値のベクタを格納するオブジェクトになります。

void `grn_obj_unlink`(grn_ctx *ctx, grn_obj *obj)

  objをメモリから解放します。objに属するobjectも再帰的にメモリから解放されます。

const char *`grn_obj_path`(grn_ctx *ctx, grn_obj *obj)

  objに対応するファイルパスを返します。一時objectならNULLを返します。

  Parameters: | obj -- 対象objectを指定します。

int `grn_obj_name`(grn_ctx *ctx, grn_obj *obj, char *namebuf, int buf_size)

  objの名前の長さを返します。無名objectなら0を返します。

  名前付きのobjectであり、buf_sizeの長さが名前の長以上であった場合は、namebufに該当する名前をコピーします。

  Parameters: | obj -- 対象objectを指定します。 namebuf -- 名前を格納するバッファ（呼出側で準備する）を指定します。 buf_size -- namebufのサイズ（byte長）を指定します。

grn_id `grn_obj_get_range`(grn_ctx *ctx, grn_obj *obj)

  objパラメータのとる値の範囲を表わしているオブジェクトのIDを返します。例えば、`grn_builtin_type` にある `GRN_DB_INT` などを返します。

  Parameters: | obj -- 対象objectを指定します。

int `grn_obj_expire`(grn_ctx *ctx, grn_obj *obj, int threshold)

  objの占有するメモリのうち、可能な領域をthresholdを指標として解放します。

  Parameters: | obj -- 対象objectを指定します。

int `grn_obj_check`(grn_ctx *ctx, grn_obj *obj)

  objに対応するファイルの整合性を検査します。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_lock`(grn_ctx *ctx, grn_obj *obj, grn_id id, int timeout)

  objをlockします。timeout（秒）経過してもlockを取得できない場合は `GRN_RESOURCE_DEADLOCK_AVOIDED` を返します。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_unlock`(grn_ctx *ctx, grn_obj *obj, grn_id id)

  objをunlockします。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_clear_lock`(grn_ctx *ctx, grn_obj *obj)

  強制的にロックをクリアします。

  Parameters: | obj -- 対象objectを指定します。

unsigned int `grn_obj_is_locked`(grn_ctx *ctx, grn_obj *obj)

  objが現在lockされていれば0以外の値を返します。

  Parameters: | obj -- 対象objectを指定します。

int `grn_obj_defrag`(grn_ctx *ctx, grn_obj *obj, int threshold)

  objの占有するDBファイル領域のうち、可能な領域をthresholdを指標としてフラグメントの解消を行います。

  フラグメント解消が実行されたセグメントの数を返します。

  Parameters: | obj -- 対象objectを指定します。

grn_id `grn_obj_id`(grn_ctx *ctx, grn_obj *obj)

  objのidを返します。

  Parameters: | obj -- 対象objectを指定します。

grn_rc `grn_obj_delete_by_id`(grn_ctx *ctx, grn_obj *db, grn_id id, grn_bool removep)

  dbからidに対応するテーブルやカラムなどを削除します。mroonga向けに用意した内部APIです。

  Parameters: | db -- The target database. id -- The object (table, column and so on) ID to be deleted. removep -- If `GRN_TRUE`, clear object cache and remove relation between ID and key in database. Otherwise, just clear object cache.

grn_rc `grn_obj_path_by_id`(grn_ctx *ctx, grn_obj *db, grn_id id, char *buffer)

  dbのidに対応するpathを返します。mroonga向けに用意した内部APIです。

  Parameters: | db -- The target database. id -- The object (table, column and so on) ID to be deleted. buffer -- path string corresponding to the id will be set in this buffer.

grn_rc `grn_obj_cast_by_id`(grn_ctx *ctx, grn_obj *source, grn_obj *destination, grn_bool add_record_if_not_exist)

  It casts value of `source` to value with type of `destination`. Casted value is appended to `destination`.

  Both `source` and `destination` must be bulk.

  If `destination` is a reference type bulk. (Reference type bulk means that type of `destination` is a table.) `add_record_if_not_exist` is used. If `source` value doesn't exist in the table that is a type of `destination`. The `source` value is added to the table.

  Parameters: | ctx -- The context object. source -- The bulk to be casted. destination -- The bulk to specify cast target type and store casted value. add_record_if_not_exist -- Whether adding a new record if `source` value doesn't exist in cast target table. This parameter is only used when `destination` is a reference type bulk.
  Returns: | `GRN_SUCCESS` on success, not `GRN_SUCCESS` on error.