Translate

pgroonga · Oct 10, 2015 · 86aa136 · 86aa136
1 parent 8ecfd80
commit 86aa136
Show file tree

Hide file tree

Showing 3 changed files with 117 additions and 82 deletions.
diff --git a/reference/functions/pgroonga-command.md b/reference/functions/pgroonga-command.md
@@ -5,16 +5,104 @@ layout: en
 
 # `pgroonga.command` function
 
+## Summary
+
 `pgroonga.command` function executes a [Groonga command](http://groonga.org/docs/reference/command.html) and returns the result as `text` type value.
 
-Here is `pgroonga.command` signature:
+## Syntax
+
+Here is the syntax of this function:
 
 ```text
-pgroonga.command(command)
+text pgroonga.command(command)
 ```
 
 `command` is a `text` type value. `pgroonga.command` executes `command` as a Groonga command.
 
 Groonga command returns result as JSON. `pgroonga.command` returns the JSON as `text` type value. You can use [JSON functions and operations provided by PostgreSQL](http://www.postgresql.org/docs/current/static/functions-json.html) by casting the result to `json` or `jsonb` type.
 
-See also [examples in tutorial](../../tutorial/#groonga).
+## Usage
+
+See [examples in tutorial](../../tutorial/#groonga).
+
+{: #attention}
+
+## Attention for `select` Groonga command
+
+You need to take care about invalid records when you use [`select` Groonga command](http://groonga.org/docs/reference/commands/select.html).
+
+You may get invalid records when PGroonga index target table processed one or more `DELETE` or `UPDATE` after last `VACUUM`. There are deleted and/or old records exist in Groonga table for the case. If there are deleted or old records, `select` Groonga command may return them.
+
+The followings show this case by example.
+
+Here is the result before updating. There are 3 records:
+
+```sql
+SELECT *
+  FROM json_array_elements(
+         pgroonga.command('select ' ||
+                          pgroonga.table_name('pgroonga_terms_index')
+                         )::json->1->0);
+--                                                    value                                                   
+-- -----------------------------------------------------------------------------------------------------------
+--  [3]
+--  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
+--  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
+--  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
+--  [3,3,"PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。","PostgreSQL","PGroonga"]
+-- (5 行)
+```
+
+Update 1 record:
+
+```sql
+UPDATE terms
+   SET title = 'Mroonga',
+       content = 'MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。',
+       tag = 'MySQL'
+ WHERE id = 3;
+```
+
+Executes `select` Groonga command again. It returns 4 records. 1 record is added because there is the record before updating:
+
+```sql
+SELECT *
+  FROM json_array_elements(
+         pgroonga.command('select ' ||
+                          pgroonga.table_name('pgroonga_terms_index')
+                         )::json->1->0);
+--                                                    value                                                   
+-- -----------------------------------------------------------------------------------------------------------
+--  [4]
+--  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
+--  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
+--  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
+--  [3,3,"PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。","PostgreSQL","PGroonga"]
+--  [4,4,"MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。","MySQL","Mroonga"]
+-- (6 行)
+```
+
+The old record is deleted when `VACUUM` is executed.
+
+Execute `VACUUM` explicitly. And then execute `select` Groonga command again. It returns 3 records. There isn't the old record:
+
+```sql
+VACUUM;
+SELECT *
+  FROM json_array_elements(
+         pgroonga.command('select ' ||
+                          pgroonga.table_name('pgroonga_terms_index')
+                         )::json->1->0);
+--                                                 value                                                 
+-- ------------------------------------------------------------------------------------------------------
+--  [3]
+--  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
+--  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
+--  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
+--  [4,4,"MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。","MySQL","Mroonga"]
+-- (5 行)
+```
+
+## See also
+
+  * [Examples in tutorial](../../tutorial/#groonga).
diff --git a/reference/functions/pgroonga-table-name.md b/reference/functions/pgroonga-table-name.md
@@ -5,9 +5,25 @@ layout: en
 
 # `pgroonga.table_name` function
 
-TODO
+## Summary
 
-You can use weight feature by `select` command.
+`pgroonga.table_name` function converts PGroonga index name to Groonga table name. Groonga table name is useful [`select` Groonga command](http://groonga.org/docs/reference/commands/select.html) by [`pgroonga.command` function](pgroonga-command.html).
+
+You can use weight feature by `select` Groonga command.
+
+## Syntax
+
+Here is the syntax of this function:
+
+```text
+text pgroonga.table_name(pgroonga_index_name)
+```
+
+`pgroonga_index_name` is a `text` type value. It's an index name to be converted to Groonga table name. The index should be created with `USING pgroonga`.
+
+`pgroonga.table_name` returns Groonga table name for `pgroonga_index_name` as `text` type value. If `pgroonga_index_name` doesn't exist or isn't a PGroonga index, `pgroonga.table_name` raises an error.
+
+## Usage
 
 Here are sample schema and data. In the schema, both search target data and output data are index target columns:
 
@@ -82,80 +98,9 @@ SELECT *
 -- (2 rows)
 ```
 
-`select` command in Groonga may help you when `SELECT` statement in SQL is slow.
-
-
-# Attention
-
-レコードを削除・更新している場合は、Groongaのデータベースには削除済み・
-更新前のデータが残っています。
-
-まず、更新前の状態を確認します。レコードは3つです。
-
-```sql
-SELECT *
-  FROM json_array_elements(
-         pgroonga.command('select ' ||
-                          pgroonga.table_name('pgroonga_terms_index')
-                         )::json->1->0);
---                                                    value                                                   
--- -----------------------------------------------------------------------------------------------------------
---  [3]
---  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
---  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
---  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
---  [3,3,"PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。","PostgreSQL","PGroonga"]
--- (5 行)
-```
-
-更新します。
-
-```sql
-UPDATE terms
-   SET title = 'Mroonga',
-       content = 'MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。',
-       tag = 'MySQL'
- WHERE id = 3;
-```
-
-再度`select`コマンドを実行するとレコードが1つ増えて4つになっています。
-これは更新前のレコードも残っているからです。
-
-```sql
-SELECT *
-  FROM json_array_elements(
-         pgroonga.command('select ' ||
-                          pgroonga.table_name('pgroonga_terms_index')
-                         )::json->1->0);
---                                                    value                                                   
--- -----------------------------------------------------------------------------------------------------------
---  [4]
---  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
---  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
---  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
---  [3,3,"PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。","PostgreSQL","PGroonga"]
---  [4,4,"MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。","MySQL","Mroonga"]
--- (6 行)
-```
-
-削除されたレコードは`VACUUM`時に削除されます。明示的に`VACUUM`を実行す
-ると更新前のレコードがなくなって、レコード数は3つになります。
+`select` Groonga command may help you when `SELECT` statement in SQL is slow.
 
-```sql
-VACUUM
-SELECT *
-  FROM json_array_elements(
-         pgroonga.command('select ' ||
-                          pgroonga.table_name('pgroonga_terms_index')
-                         )::json->1->0);
---                                                 value                                                 
--- ------------------------------------------------------------------------------------------------------
---  [3]
---  [["_id","UInt32"],["_key","UInt64"],["content","LongText"],["tag","ShortText"],["title","LongText"]]
---  [1,1,"PostgreSQLはリレーショナル・データベース管理システムです。","PostgreSQL","PostgreSQL"]
---  [2,2,"Groongaは日本語対応の高速な全文検索エンジンです。","Groonga","Groonga"]
---  [4,4,"MroongaはGroongaをバックエンドにしたMySQLのストレージエンジンです。","MySQL","Mroonga"]
--- (5 行)
-```
+## See also
 
-Groongaのデータを直接使うときは気をつけてください。
+  * [`pgroonga.table_name` function description in tutorial](../../tutorial/#pgroonga-table-name).
+  * [Attention when you use `select` Groonga command](pgroonga-command.html#attention).
diff --git a/tutorial/index.md b/tutorial/index.md
@@ -781,11 +781,13 @@ SELECT * FROM json_each(pgroonga.command('status')::json->1);
 
 See [`pgroonga.command` function](../reference/functions/pgroonga-command.html) for more details.
 
+{: #pgroonga-table-name}
+
 ### `pgroonga.table_name` function
 
-PGroonga stores values of index target columns. You can use these values to search and output by Groonga's [select command](http://groonga.org/docs/reference/commands/select.html).
+PGroonga stores values of index target columns. You can use these values to search and output by [`select` Groonga command](http://groonga.org/docs/reference/commands/select.html).
 
-`select` command table name in Groonga. You can use `pgroonga.table_name` function to convert index name in PostgreSQL to table name in Groonga.
+`select` Groonga command needs table name. You can use `pgroonga.table_name` function to convert index name in PostgreSQL to table name in Groonga.
 
 Here is an example to use `select` command with `pgroonga.table_name` function: