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

- English

# 7.3.40. `object_inspect`

## 7.3.40.1. 概要

バージョン 6.0.0 で追加.

`object_inspect` はオブジェクトを調査します。オブジェクトの詳細を確認することができます。

例：

> - オブジェクトがテーブルの場合、テーブル内のレコード数を確認できます。
> - オブジェクトがカラムの場合、値の型を確認できます。

## 7.3.40.2. 構文

このコマンドの引数は1つで省略できます:

    object_inspect [name=null]

## 7.3.40.3. 使い方

`name` で指定したデータベース内のオブジェクトを調査できます。

実行例:

    table_create Users TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    load --table Users
    [
    {"_key": "Alice"}
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 1]
    object_inspect Users
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   {
    #     "disk_usage": 16842752,
    #     "name": "Users",
    #     "n_records": 1,
    #     "value": {
    #       "type": null
    #     },
    #     "key": {
    #       "total_size": 5,
    #       "max_total_size": 4294967295,
    #       "type": {
    #         "size": 4096,
    #         "type": {
    #           "id": 32,
    #           "name": "type"
    #         },
    #         "id": 14,
    #         "name": "ShortText"
    #       }
    #     },
    #     "type": {
    #       "id": 48,
    #       "name": "table:hash_key"
    #     },
    #     "id": 256
    #   }
    # ]

`object_inspect Users` は以下の情報を返します。

> - テーブル名： `"name": Users`
> - 総キーサイズ： `"key": {"total_size": 5}` （ `"Alice"` は5バイトのデータです。）
> - 最大総キーサイズ： `"key": {"max_total_size": 4294967295}`
> - などなど。

`name` を指定しないとデータベースを調査できます。

実行例:

    object_inspect
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   {
    #     "disk_usage": 22347776,
    #     "name_table": {
    #       "disk_usage": 1052672,
    #       "name": "",
    #       "n_records": 256,
    #       "value": null,
    #       "key": {
    #         "type": null
    #       },
    #       "type": {
    #         "id": 50,
    #         "name": "table:dat_key"
    #       },
    #       "id": 0
    #     },
    #     "type": {
    #       "id": 55,
    #       "name": "db"
    #     }
    #   }
    # ]

`object_inspect` は以下の情報を返します。

> - オブジェクトの名前管理をしているテーブルの種類： `"key": {"type": {"name": "table:dat_key"}}`
> - などなど。

## 7.3.40.4. 引数

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

### 7.3.40.4.1. 必須引数

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

### 7.3.40.4.2. 省略可能引数

省略可能な引数が1つあります。

#### 7.3.40.4.2.1. `name`

調査対象のオブジェクト名を指定してください。

`name` を指定しないとデータベースを調査します。

## 7.3.40.5. 戻り値

このコマンドはボディとしてオブジェクト（たとえばテーブル）の詳細を含んだオブジェクト（ネストしたキーと値のペア）を返します。:

    [HEADER, object]

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

オブジェクトの詳細のフォーマットはオブジェクトの種類に依存します。たとえば、テーブルはキーの情報を含みますが、関数はキーの情報を含みません。

### 7.3.40.5.1. データベース

データベースを調査すると次の情報を返します。:

    {
      "type": {
        "id": DATABASE_TYPE_ID,
        "name": DATABASE_TYPE_NAME
      },
      "name_table": DATABASE_NAME_TABLE
    }

#### 7.3.40.5.1.1. `DATABASE_TYPE_ID`

`DATABASE_TYPE_ID` は常に `55` です。

#### 7.3.40.5.1.2. `DATABASE_TYPE_NAME`

`DATABASE_TYPE_NAME` は常に `"db"` です。

#### 7.3.40.5.1.3. `DATABASE_NAME_TABLE`

`DATABASE_NAME_TABLE` はデータベース内のオブジェクト名を管理するテーブルです。このテーブルは TABLE_PAT_KEY または TABLE_DAT_KEY です。通常、 TABLE_DAT_KEY です。

フォーマットの詳細は テーブル を参照してください。

### 7.3.40.5.2. テーブル

テーブルを調査すると次の情報を返します。:

    {
      "id": TABLE_ID,
      "name": TABLE_NAME,
      "type": {
        "id": TABLE_TYPE_ID,
        "name": TABLE_TYPE_NAME
      },
      "key": {
        "type": TABLE_KEY_TYPE,
        "total_size": TABLE_KEY_TOTAL_SIZE
        "max_total_size": TABLE_KEY_MAX_TOTAL_SIZE
      },
      "value": {
        "type": TABLE_VALUE_TYPE,
      },
      "n_records": TABLE_N_RECORDS
    }

いくつか例外があります。

> - TABLE_NO_KEY はキーの情報を返しません。なぜならキーを持っていないからです。
> - TABLE_DAT_KEY は値の情報を返しません。なぜなら値を持っていないからです。

#### 7.3.40.5.2.1. `TABLE_ID`

調査対象のテーブルのID。

#### 7.3.40.5.2.2. `TABLE_NAME`

調査対象のテーブルの名前。

#### 7.3.40.5.2.3. `TABLE_TYPE_ID`

調査対象のテーブルの種類のID

以下は種類のIDのリストです。

テーブルの種類 | ID
--- | ---
TABLE_HASH_KEY | `48`
TABLE_PAT_KEY | `49`
TABLE_DAT_KEY | `50`
TABLE_NO_KEY | `51`

#### 7.3.40.5.2.4. `TABLE_TYPE_NAME`

調査対象のテーブルの種類の名前。

以下は種類の名前のリストです。

テーブルの種類 | 名前
--- | ---
TABLE_HASH_KEY | `"table:hash_key"`
TABLE_PAT_KEY | `"table:pat_key"`
TABLE_DAT_KEY | `"table:dat_key"`
TABLE_NO_KEY | `"table:no_key"`

#### 7.3.40.5.2.5. `TABLE_KEY_TYPE`

調査対象のテーブルのキーの型。

フォーマットの詳細は 型 を参照してください。

#### 7.3.40.5.2.6. `TABLE_KEY_TOTAL_SIZE`

調査対象のテーブルの総キーサイズ。単位はバイト。

#### 7.3.40.5.2.7. `TABLE_KEY_MAX_TOTAL_SIZE`

調査対象のテーブルの最大総キーサイズ。単位はバイト。

#### 7.3.40.5.2.8. `TABLE_VALUE_TYPE`

調査対象のテーブルの値の型。

フォーマットの詳細は 型 を参照してください。

#### 7.3.40.5.2.9. `TABLE_N_RECORDS`

調査対象のテーブルのレコード数。

64bitの正の整数です。

### 7.3.40.5.3. カラム

バージョン 7.0.2 で追加.

データカラム（スカラーカラムとベクターカラム）を調査すると次の情報を返します。:

    {
      "id": COLUMN_ID,
      "name": COLUMN_NAME
      "table": COLUMN_TABLE,
      "full_name": COLUMN_FULL_NAME,
      "type": {
        "name": COLUMN_TYPE_NAME,
        "raw": {
          "id": COLUMN_TYPE_RAW_ID,
          "name": COLUMN_TYPE_RAW_NAME
        }
      },
      "value": {
        "type": COLUMN_VALUE_TYPE,
        "compress": DATA_COLUMN_VALUE_COMPRESS_METHOD,
      }
    }

インデックスカラムはデータカラムと似ていますがいくつか違いがあります。

> - インデックスカラムの情報にはキー `value.compress` がありません。
> - インデックスカラムの情報にはキー `value.section` があります。
> - インデックスカラムの情報にはキー `value.weight` があります。
> - インデックスカラムの情報にはキー `value.position` があります。
> - インデックスカラムの情報にはキー `value.size` があります。
> - インデックスカラムの情報にはキー `value.statistics` があります。
> - インデックスカラムの情報にはキー `sources` があります。

インデックスカラムを調査すると次の情報を返します。

    {
      "id": COLUMN_ID,
      "name": COLUMN_NAME
      "table": COLUMN_TABLE,
      "full_name": COLUMN_FULL_NAME,
      "type": {
        "name": COLUMN_TYPE_NAME,
        "raw": {
          "id": COLUMN_TYPE_RAW_ID,
          "name": COLUMN_TYPE_RAW_NAME
        }
      },
      "value": {
        "type": COLUMN_VALUE_TYPE,
        "section": INDEX_COLUMN_VALUE_SECTION,
        "weight": INDEX_COLUMN_VALUE_WEIGHT,
        "position": INDEX_COLUMN_VALUE_POSITION,
        "size": INDEX_COLUMN_VALUE_SIZE,
        "statistics": {
          "max_section_id": INDEX_COLUMN_VALUE_STATISTICS_MAX_SECTION_ID,
          "n_garbage_segments": INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS,
          "max_array_segment_id": INDEX_COLUMN_VALUE_STATISTICS_MAX_ARRAY_SEGMENT_ID,
          "n_array_segments": INDEX_COLUMN_VALUE_STATISTICS_N_ARRAY_SEGMENTS,
          "max_buffer_segment_id": INDEX_COLUMN_VALUE_STATISTICS_MAX_BUFFER_SEGMENT_ID,
          "n_buffer_segments": INDEX_COLUMN_VALUE_STATISTICS_N_BUFFER_SEGMENTS,
          "max_in_use_physical_segment_id": INDEX_COLUMN_VALUE_STATISTICS_MAX_IN_USE_PHYSICAL_SEGMENT_ID,
          "n_unmanaged_segments": INDEX_COLUMN_VALUE_STATISTICS_N_UNMANAGED_SEGMENTS,
          "total_chunk_size": INDEX_COLUMN_VALUE_STATISTICS_TOTAL_CHUNK_SIZE,
          "max_in_use_chunk_id": INDEX_COLUMN_VALUE_STATISTICS_MAX_IN_USE_CHUNK_ID,
          "n_garbage_chunks": INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_CHUNKS
        }
      },
      "sources": [
        {
          "id": INDEX_COLUMN_SOURCE_ID,
          "name": INDEX_COLUMN_SOURCE_NAME,
          "table": INDEX_COLUMN_SOURCE_TABLE,
          "full_name": INDEX_COLUMN_SOURCE_FULL_NAME
        },
        ...
      ]
    }

#### 7.3.40.5.3.1. `COLUMN_ID`

調査対象のカラムのID。

#### 7.3.40.5.3.2. `COLUMN_NAME`

調査対象のカラムの名前。

テーブル名は含みません。カラム名のみを含みます。

`TABLE_NAME.COLUMN_NAME` スタイルの完全なカラム名を欲しい場合は代わりに COLUMN_FULL_NAME を使ってください。

#### 7.3.40.5.3.3. `COLUMN_TABLE`

調査対象のカラムのテーブル。

フォーマットの詳細は テーブル を参照してください。

#### 7.3.40.5.3.4. `COLUMN_FULL_NAME`

調査対象のカラムの完全な名前。

`テーブル名.カラム名` という書式でテーブル名とカラム名を両方含みます。

カラム名だけが欲しい場合は代わりに COLUMN_NAME を使ってください。

#### 7.3.40.5.3.5. `COLUMN_TYPE_NAME`

調査対象のカラムの種類の名前。

以下は種類の名前のリストです。

カラムの種類 | 名前
--- | ---
スカラーカラム | `"scalar"`
ベクターカラム | `"vector"`
インデックスカラム | `"index"`

#### 7.3.40.5.3.6. `COLUMN_TYPE_RAW_ID`

調査対象のカラムの未加工の種類のID

以下は未加工の種類のIDのリストです。

カラムの未加工の種類 | ID
--- | ---
固定長サイズカラム | `64`
可変長サイズカラム | `65`
インデックスカラム | `72`

#### 7.3.40.5.3.7. `COLUMN_TYPE_RAW_NAME`

調査対象のカラムの未加工の種類の名前。

以下は未加工の種類の名前のリストです。

カラムの未加工の種類 | 名前
--- | ---
固定長サイズカラム | `"column:fix_size"`
可変長サイズカラム | `"column:var_size"`
インデックスカラム | `"column:index"`

#### 7.3.40.5.3.8. `COLUMN_VALUE_TYPE`

調査対象のカラムの値の型。

フォーマットの詳細は 型 を参照してください。

#### 7.3.40.5.3.9. `DATA_COLUMN_VALUE_COMPRESS_METHOD`

調査対象のデータカラムの値の圧縮方法です。

以下は圧縮方法のリストです。

圧縮方法 | 値
--- | ---
zlib | `"zlib"`
LZ4 | `"lz4"`
Zstandard | `"zstd"`
なし | `null`

#### 7.3.40.5.3.10. `INDEX_COLUMN_VALUE_SECTION`

調査対象のカラムが `WITH_SECTION` フラグ付きで作ったカラムかどうかを返します。 `WITH_SECTION` フラグ付きでカラムを作ったときは `true` 、そうでないときは `false` になります。

参考

flags

#### 7.3.40.5.3.11. `INDEX_COLUMN_VALUE_WEIGHT`

調査対象のカラムが `WITH_WEIGHT` フラグ付きで作ったカラムかどうかを返します。 `WITH_WEIGHT` フラグ付きでカラムを作ったときは `true` 、そうでないときは `false` になります。

参考

flags

#### 7.3.40.5.3.12. `INDEX_COLUMN_VALUE_POSITION`

調査対象のカラムが `WITH_POSITION` フラグ付きで作ったカラムかどうかを返します。 `WITH_POSITION` フラグ付きでカラムを作ったときは `true` 、そうでないときは `false` になります。

参考

flags

#### 7.3.40.5.3.13. `INDEX_COLUMN_VALUE_SIZE`

調査対象のインデックスカラムのサイズ。インデックスのサイズは flags で指定できます。

以下がインデックスカラムのサイズのリストです。

インデックスカラムのサイズ | 値
--- | ---
`INDEX_SMALL` | `"small"`
`INDEX_MEDIUM` | `"medium"`
デフォルト | `"normal"`

#### 7.3.40.5.3.14. `INDEX_COLUMN_VALUE_STATISTICS_MAX_SECTION_ID`

調査対象のインデックスカラム最大セクションID。

`WITH_SECTION` フラグなしで作ったインデックスの場合は常に `0` になります。

`WITH_SECTION` フラグ付きで作ったインデックスカラムの場合は `0` 以上になります。空の `WITH_SECTION` 指定のインデックスカラムは `0` になります。空でない `WITH_SECTION` 指定のインデックスカラムは `1` 以上になります。

`WITH_SECTION` 指定のインデックスカラムの最大値はソースカラム数です。

#### 7.3.40.5.3.15. `INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS`

調査対象のインデックスカラム内のゴミセグメントの数。

インデックスカラムは使われなくなったセグメント（内部で確保している領域）を再利用します。このセグメントのことを「ゴミセグメント」と呼びます。

最大値は最大セグメント数です。最大セグメント数はインデックスサイズに依ります。

インデックスカラムのサイズ | 最大セグメント数
--- | ---
`INDEX_SMALL` | `2**9` (512)
`INDEX_MEDIUM` | `2**16` (65536)
デフォルト | `2**17` (131072)

#### 7.3.40.5.3.16. `INDEX_COLUMN_VALUE_STATISTICS_MAX_ARRAY_SEGMENT_ID`

調査対象のインデックスカラム内の「array」に使用しているセグメントのうち一番大きいIDの値。

「array」は「buffer」を管理するために使っています。

この値の最大値は最大セグメント数です。最大セグメント数は INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS を見てください。

#### 7.3.40.5.3.17. `INDEX_COLUMN_VALUE_STATISTICS_MAX_ARRAY_SEGMENT_ID`

調査対象のインデックスカラム内の「array」に使っているセグメント数。

「array」は「buffer」を管理するために使っています。

最大値は `最大セグメント数 - 「buffer」に使っているセグメント数` です。最大セグメント数は INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS を見てください。

#### 7.3.40.5.3.18. `INDEX_COLUMN_VALUE_STATISTICS_MAX_BUFFER_SEGMENT_ID`

調査対象のインデックスカラム内の「buffer」に使っている最大セグメントID。

「buffer」はポスティングリストを保存する場所です。

この値の最大値は最大セグメント数です。最大セグメント数は INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS を見てください。

#### 7.3.40.5.3.19. `INDEX_COLUMN_VALUE_STATISTICS_MAX_BUFFER_SEGMENT_ID`

調査対象のインデックスカラム内の「buffer」に使っている最大セグメント数。

「buffer」はポスティングリストを保存する場所です。

最大値は `最大セグメント数 - 「array」に使っているセグメント数` です。最大セグメント数は INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS を見てください。

#### 7.3.40.5.3.20. `INDEX_COLUMN_VALUE_STATISTICS_MAX_IN_USE_PHYSICAL_SEGMENT_ID`

調査対象のインデックスカラム内の「ゴミセグメント」、「arrayセグメント」「bufferセグメント」全体で使っているセグメントの最大ID。

この値の最大値は最大セグメント数です。最大セグメント数は INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_SEGMENTS を見てください。

#### 7.3.40.5.3.21. `INDEX_COLUMN_VALUE_STATISTICS_N_UNMANAGED_SEGMENTS`

調査対象のインデックスカラム内の未管理のセグメント数。

`0` であるべきです。

#### 7.3.40.5.3.22. `INDEX_COLUMN_VALUE_STATISTICS_TOTAL_CHUNK_SIZE`

調査対象のインデックスカラム内の総「チャンク」サイズ。

「chunk」はポスティングリストを保存する場所です。「buffer」は変更可能ですが、「chunk」は変更不可です。「chunk」は「buffer」よりも空間効率がよいです。「buffer」は「chunk」よりも更新効率がよいです。

小さなポスティングリストは「buffer」に保存します。「buffer」内のポスティングリストが大きくなると「chunk」に移動します。

最大値は `1チャンクあたりの最大サイズ * 最大チャンク数` 数です。ただし、オーバーヘッドがあるためすべての領域を使い切ることはできないでしょう。

1チャンクあたりの最大サイズは `2 ** 22` バイト（4MiB）です。最大チャンク数はインデックスサイズに依存します。

インデックスカラムのサイズ | 最大チャンク数
--- | ---
`INDEX_SMALL` | `2**10` (1024)
`INDEX_MEDIUM` | `2**14` (16384)
デフォルト | `2**18` (262144)

#### 7.3.40.5.3.23. `INDEX_COLUMN_VALUE_STATISTICS_MAX_IN_USE_CHUNK_ID`

調査対象のインデックスカラム内で使っている最大「chunk」ID。

最大値は最大チャンク数です。最大チャンク数は INDEX_COLUMN_VALUE_STATISTICS_TOTAL_CHUNK_SIZE を見てください。

#### 7.3.40.5.3.24. `INDEX_COLUMN_VALUE_STATISTICS_N_GARBAGE_CHUNKS`

調査対象のインデックスカラム内のゴミ「chunk」の配列です。

ゴミ「chunk」は14個の領域で管理されています。次のように配列ですべての領域のゴミ「chunk」の数を示します。:

    [
      N_GARBAGE_CHUNKS_IN_SPACE0,
      N_GARBAGE_CHUNKS_IN_SPACE1,
      ...
      N_GARBAGE_CHUNKS_IN_SPACE13
    ]

各領域の最大値は最大チャンク数です。最大チャンク数は INDEX_COLUMN_VALUE_STATISTICS_TOTAL_CHUNK_SIZE を見てください。

#### 7.3.40.5.3.25. `INDEX_COLUMN_SOURCE_ID`

調査対象のインデックスカラム内のソースカラムのID。

#### 7.3.40.5.3.26. `INDEX_COLUMN_SOURCE_NAME`

調査対象のインデックスカラムのソースカラムの名前。

テーブル名は含みません。カラム名のみを含みます。

`TABLE_NAME.COLUMN_NAME` スタイルの完全なカラム名を欲しい場合は代わりに INDEX_COLUMN_SOURCE_FULL_NAME を使ってください。

#### 7.3.40.5.3.27. `INDEX_COLUMN_SOURCE_TABLE`

調査対象のインデックスカラム内のソースカラムのテーブル。

フォーマットの詳細は テーブル を参照してください。

#### 7.3.40.5.3.28. `INDEX_COLUMN_SOURCE_FULL_NAME`

調査対象のインデックスカラム内のソースカラムの完全な名前。

`テーブル名.カラム名` という書式でテーブル名とカラム名を両方含みます。

カラム名だけが必要な場合は代わりに INDEX_COLUMN_SOURCE_NAME を使ってください。

#### 7.3.40.5.3.29. 型

型を調査すると次の情報を返します。

    {
      "id": TYPE_ID,
      "name": TYPE_NAME,
      "type": {
        "id": TYPE_ID_OF_TYPE,
        "name": TYPE_NAME_OF_TYPE
      },
      "size": TYPE_SIZE
    }

#### 7.3.40.5.3.30. `TYPE_ID`

対象の型のIDです。

以下は組み込みの型のIDのリストです。

型 | ID
--- | ---
Bool | `3`
Int8 | `4`
UInt8 | `5`
Int16 | `6`
UInt16 | `7`
Int32 | `8`
UInt32 | `9`
Int64 | `10`
UInt64 | `11`
Float | `12`
Time | `13`
ShortText | `14`
Text | `15`
LongText | `16`
TokyoGeoPoint | `17`
WGS84GeoPoint | `18`

#### 7.3.40.5.3.31. `TYPE_NAME`

調査対象の型の名前。

以下は組み込みの型の名前のリストです。

> - Bool
> - Int8
> - UInt8
> - Int16
> - UInt16
> - Int32
> - UInt32
> - Int64
> - UInt64
> - Float
> - Time
> - ShortText
> - Text
> - LongText
> - TokyoGeoPoint
> - WGS84GeoPoint

#### 7.3.40.5.3.32. `TYPE_ID_OF_TYPE`

`TYPE_ID_OF_TYPE` は常に `32` です。

#### 7.3.40.5.3.33. `TYPE_NAME_OF_TYPE`

`TYPE_NAME_OF_TYPE` は常に `type` です。

#### 7.3.40.5.3.34. `TYPE_SIZE`

`TYPE_SIZE` は調査対象の型のサイズです。単位はバイトです。調査対象の型が可変長型の場合は、サイズは最大サイズという意味です。