Translate

reference/functions/pgroonga-score.md

@@ -5,9 +5,9 @@ layout: en
 
 # `pgroonga.score` function
 
-You can use `pgroonga.score` function to retrieve score as number. Score is how the record is precise.
+You can use `pgroonga.score` function to get precision as a number. If a record is more precision against searched query, the record has more higher number.
 
-You need to add the column that is specified as primary key to index targets to use `pgroonga.score` function. If your PGroonga index doesn't have the column that is specified as primary key, `pgroonga.score` function always returns `0`.
+You need to add primary key column into `pgroonga` index to use `pgroonga.score` function. If you don't add primary key column into `pgroonga` index, `pgroonga.score` function always returns `0`.
 
 `pgroonga.score` function always returns `0` when full text search isn't performed by index. In other words, `pgroonga.score` function always returns `0` when full text search is performed by sequential scan.
 

reference/functions/pgroonga-snippet-html.md

@@ -0,0 +1,24 @@
+---
+title: pgroonga.snippet function
+layout: en
+---
+
+# `pgroonga.snippet` function
+
+Here is `pgroonga.snippet_html` signature:
+
+```text
+pgroonga.snippet_html(target, ARRAY[keyword1, keyword2, ...])
+```
+
+`target` is a `text` type value. `pgroonga.snippet_html` extracts keywords with around texts from `target`.
+
+`keyword1`, `keyword2`, `...` are an array of `text` type. The keywords to be extracted from `target`. You must specify one or more keywords.
+
+`pgroonga.snippet_html` returns an array of `text` type.
+
+Element in the returned array is a text around keyword. The keyword is surround with `<span class="keyword">` and `</span>`. `<`, `>`, `&` and `"` in `target` is HTML escaped.
+
+The maximum size of part of `target` in each element is 200 bytes. It's unit is byte not the number of characters. Each element may be lager than 200 bytes because each element includes `<span class="keyword">` and `</span>` and may have HTML escaped values. If '<' is HTML escaped to `&lt;`, the byte size is increased to 4 from 1.
+
+See also [examples in tutorial](../../tutorial/#snippet).

tutorial/index.md

@@ -188,7 +188,54 @@ SELECT *, pgroonga.score(score_memos)
 -- (2 rows)
 ```
 
-See [pgroonga.score function](../reference/functions/pgroonga-score.html) for more details such as how to compute precision.
+See [`pgroonga.score` function](../reference/functions/pgroonga-score.html) for more details such as how to compute precision.
+
+{: #snippet}
+
+### Snippet (KWIC, keyword in context)
+
+You can use `pgroonga.snippet_html` function to get texts around keywords from search target text. It's also known as [KWIC](https://en.wikipedia.org/wiki/Key_Word_in_Context) (keyword in context). You can see it in search result on Web search engine.
+
+Here is a sample text for description. It's a description about Groonga.
+
+> Groonga is a fast and accurate full text search engine based on inverted index. One of the characteristics of Groonga is that a newly registered document instantly appears in search results. Also, Groonga allows updates without read locks. These characteristics result in superior performance on real-time applications.
+
+
+There are some `fast` keywords. `pgroonga.snippet_html` extracts texts around `fast`. Keywords in extracted texts are surround with `<span class="keyword">` and `</span>`.
+
+`html` in `pgroonga.snippet_html` means that this function returns result for HTML output.
+
+Here is the result of `pgroonga.snippet_html` against the above text:
+
+> Groonga is a <span class="keyword">fast</span> and accurate full text search engine based on inverted index. One of the characteristics of Groonga is that a newly registered document instantly appears in search results. Also, Gro
+
+This function can be used for all texts. It's not only for search result by PGroonga.
+
+Here is a sample SQL that describe about it. You can use the function in the following `SELECT` that doesn't have `FROM`. Note that [`unnest`](http://www.postgresql.org/docs/current/static/functions-array.html) is a PostgreSQL function that converts an array to rows.
+
+```sql
+SELECT unnest(pgroonga.snippet_html(
+  'Groonga is a fast and accurate full text search engine based on ' ||
+  'inverted index. One of the characteristics of Groonga is that a ' ||
+  'newly registered document instantly appears in search results. ' ||
+  'Also, Groonga allows updates without read locks. These characteristics ' ||
+  'result in superior performance on real-time applications.' ||
+  '\n' ||
+  '\n' ||
+  'Groonga is also a column-oriented database management system (DBMS). ' ||
+  'Compared with well-known row-oriented systems, such as MySQL and ' ||
+  'PostgreSQL, column-oriented systems are more suited for aggregate ' ||
+  'queries. Due to this advantage, Groonga can cover weakness of ' ||
+  'row-oriented systems.',
+  ARRAY['fast', 'PostgreSQL']));
+                                                                                 --                                unnest                                                                                                                 
+-- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+--  Groonga is a <span class="keyword">fast</span> and accurate full text search engine based on inverted index. One of the characteristics of Groonga is that a newly registered document instantly appears in search results. Also, Gro
+--  ase management system (DBMS). Compared with well-known row-oriented systems, such as MySQL and <span class="keyword">PostgreSQL</span>, column-oriented systems are more suited for aggregate queries. Due to this advantage, Groonga
+-- (2 rows)
+```
+
+See [`pgroonga.snippet_html` function](../reference/functions/pgroonga-snippet-html.html) for more details.
 
 ## Equality condition and comparison conditions