null+****@clear*****
null+****@clear*****
2011年 10月 28日 (金) 06:35:27 JST
Kazuhiko 2011-10-27 21:35:27 +0000 (Thu, 27 Oct 2011)
New Revision: 85de2fe5a150e61f109e14213262e0198a49311f
Log:
translate some documents in English.
Added files:
doc/en/Makefile.am
doc/en/make.bat
doc/en/source/characteristic.rst
doc/en/source/conf.py
doc/en/source/developer.rst
doc/en/source/developer/debug.rst
doc/en/source/developer/release.rst
doc/en/source/index.rst
doc/en/source/install.rst
doc/en/source/news.rst
doc/en/source/reference.rst
doc/en/source/userguide.rst
doc/en/source/userguide/storage.rst
doc/en/source/userguide/wrapper.rst
doc/en/sphinx2github.sh
Modified files:
configure.ac
doc/Makefile.am
Modified: configure.ac (+2 -0)
===================================================================
--- configure.ac 2011-10-27 19:31:14 +0000 (2ec9ea4)
+++ configure.ac 2011-10-27 21:35:27 +0000 (9906134)
@@ -273,6 +273,7 @@ AC_SUBST(SPHINX_BUILD)
if test "$enable_document" = "auto"; then
if test "$ac_sphinx_available" = "yes" -o \
+ -f "$srcdir/doc/en/html-build-stamp" -o \
-f "$srcdir/doc/ja/html-build-stamp"; then
enable_document="yes"
else
@@ -305,6 +306,7 @@ AC_CONFIG_FILES([
rpm/fedora/Makefile
yum/Makefile
doc/Makefile
+ doc/en/Makefile
doc/ja/Makefile
])
AC_OUTPUT([
Modified: doc/Makefile.am (+1 -1)
===================================================================
--- doc/Makefile.am 2011-10-27 19:31:14 +0000 (38057c6)
+++ doc/Makefile.am 2011-10-27 21:35:27 +0000 (6b1c7b9)
@@ -1 +1 @@
-SUBDIRS = ja
+SUBDIRS = en ja
Added: doc/en/Makefile.am (+186 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/Makefile.am 2011-10-27 21:35:27 +0000 (f910ab3)
@@ -0,0 +1,186 @@
+docdir = $(pkgdatadir)/doc
+doc_endir = $(docdir)/en
+
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+PAPER =
+BUILDDIR = .
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+# ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) source
+
+RUN_SPHINX_BUILD = env VERSION=$(VERSION) $(SPHINX_BUILD)
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean-local:
+ -rm -rf $(BUILDDIR)/doctree
+ -rm -rf $(BUILDDIR)/html
+ -rm -rf $(BUILDDIR)/dirhtml
+ -rm -rf $(BUILDDIR)/pickle
+ -rm -rf $(BUILDDIR)/json
+ -rm -rf $(BUILDDIR)/htmlhelp
+ -rm -rf $(BUILDDIR)/qthelp
+ -rm -rf $(BUILDDIR)/latex
+ -rm -rf $(BUILDDIR)/changes
+ -rm -rf $(BUILDDIR)/linkcheck
+ -rm -rf $(BUILDDIR)/doctest
+ -rm -rf $(BUILDDIR)/pdf
+
+html-local:
+ $(RUN_SPHINX_BUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(RUN_SPHINX_BUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+ $(RUN_SPHINX_BUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(RUN_SPHINX_BUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(RUN_SPHINX_BUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(RUN_SPHINX_BUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/groonga.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/groonga.qhc"
+
+latex:
+ $(RUN_SPHINX_BUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ $(RUN_SPHINX_BUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(RUN_SPHINX_BUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(RUN_SPHINX_BUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+pdf-local:
+ $(RUN_SPHINX_BUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
+ @echo
+ @echo "Build finished. The PDF files are in $(BUILDDIR)/pdf."
+
+if ENABLE_DOCUMENT
+dist-hook:
+ @touch $(distdir)/html-build-stamp
+
+nobase_dist_doc_en_DATA = \
+ $(source_files) \
+ $(html_files)
+
+# find source -type f -not -name '*.pyc' | sort | sed -e 's,^,\t,g'
+source_files = \
+ source/images/storage-mode.png \
+ source/images/storage-mode.svg \
+ source/images/wrapper-mode.png \
+ source/images/wrapper-mode.svg \
+ source/characteristic.rst \
+ source/conf.py \
+ source/developer.rst \
+ source/developer/debug.rst \
+ source/developer/release.rst \
+ source/index.rst \
+ source/install.rst \
+ source/news.rst \
+ source/reference.rst \
+ source/userguide.rst \
+ source/userguide/storage.rst \
+ source/userguide/wrapper.rst
+
+# find html -type f | sort | sed -e 's,^,\t,g'
+html_files = \
+ html/.buildinfo \
+ html/_images/storage-mode.png \
+ html/_images/wrapper-mode.png \
+ html/_sources/characteristic.txt \
+ html/_sources/developer.txt \
+ html/_sources/developer/debug.txt \
+ html/_sources/developer/release.txt \
+ html/_sources/index.txt \
+ html/_sources/install.txt \
+ html/_sources/news.txt \
+ html/_sources/reference.txt \
+ html/_sources/userguide.txt \
+ html/_sources/userguide/storage.txt \
+ html/_sources/userguide/wrapper.txt \
+ html/_static/basic.css \
+ html/_static/default.css \
+ html/_static/doctools.js \
+ html/_static/file.png \
+ html/_static/jquery.js \
+ html/_static/minus.png \
+ html/_static/plus.png \
+ html/_static/pygments.css \
+ html/_static/searchtools.js \
+ html/_static/sidebar.js \
+ html/_static/translations.js \
+ html/_static/underscore.js \
+ html/characteristic.html \
+ html/developer.html \
+ html/developer/debug.html \
+ html/developer/release.html \
+ html/genindex.html \
+ html/index.html \
+ html/install.html \
+ html/news.html \
+ html/objects.inv \
+ html/reference.html \
+ html/search.html \
+ html/searchindex.js \
+ html/userguide.html \
+ html/userguide/storage.html \
+ html/userguide/wrapper.html
+
+$(html_files): html-build-stamp
+html-build-stamp:
+ $(MAKE) html
+endif
Added: doc/en/make.bat (+155 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/make.bat 2011-10-27 21:35:27 +0000 (692f053)
@@ -0,0 +1,155 @@
+ ＠ ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\groongastorageengine.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\groongastorageengine.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
Added: doc/en/source/characteristic.rst (+80 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/characteristic.rst 2011-10-27 21:35:27 +0000 (d6151ea)
@@ -0,0 +1,80 @@
+.. highlightlang:: none
+
+The characteristics of groonga storage engine
+=============================================
+
+What is groonga storage engine?
+-------------------------------
+Groonga storage engine is a MySQL storage engine based on groonga, the full text search engine.
+
+In MySQL 5.1 or later, Pluggable Storage Engine interface is introduced, and we can use custom storage engines easily. So we implement groonga storage engine, so that we can use groonga through MySQL.
+
+By using groonga storage engine, you can use groonga with SQL.
+
+The successor of Tritonn
+------------------------
+
+To support Japanese full text search, Tritonn was developed by embedding Senna, the predecessor of groonga, in MySQL.
+Groonga storage engine is its successor.
+
+Running as a MySQL plugin
+-------------------------
+
+Since Tritonn was the modified version of MySQL, we need to build it by ourselves or use binary files provided by Tritonn project, thus we cannot use the official binary files provided by MySQL.
+
+On the other hand, groonga storage engine is an independent program (shared library) using Pluggable Storage Engine interface, and we can dynamically load it on MySQL's official binary.
+So we can use it more easily than Tritonn.
+
+Faster index update
+-------------------
+
+Comparing to Senna, groonga has much better throughput in adding or updating index.
+
+Groonga storage engine also has the benefit of this performance improvement.
+
+Faster search
+-------------
+
+In Tritonn, we use MyISAM storage engine, thus we have a exclusive table lock by updating data (and index), and it prevents the performance of search.
+
+But in groonga storage engine, we no longer have this issue, and the performance of search is better especially in frequent data update cases.
+
+Geolocation search
+------------------
+
+Groonga supports not only the full text search, but also the fast geolocation search using index.
+And MySQL also has the syntax for geolocation search.
+With groonga storage engine, you can use groonga's fast geolocation search by using MySQL's geolocation SQL syntax.
+
+Sharing the same groonga storage
+--------------------------------
+
+Groonga storage engine stores the data by using groonga's DB API.
+And its storage file's format is same as that of the file that is managed by groonga itself only.
+Therefore you can share the same groonga storage like below.
+
+* Store data through groonga storage engine (MySQL) and search from groonga server.
+* Store data through groonga server and search from groonga storage engine (MySQL).
+
+And groonga's storage file can be shared with multi-processes and multi-threads, so that we can invoke several search queries to the same storage file simultaneously.
+
+Associate with other storage engines
+------------------------------------
+
+Groonga storage engine has two running modes.
+
+One is "storage mode", that is the default mode, and we use groonga for both storing data and searching.
+With this mode, you can have full benefits of groonga described above, like fast data update, lock-free full text search and geolocation search.
+But it does not support transactions.
+
+Another one is "wrapper mode", that adds full text search function on other storage engines like MyISAM or InnoDB.
+With this mode, you can use groonga's fast full text search with having the benefits of the storage engine, ex. transaction in InnoDB.
+But you cannot have benefits from groonga's read-lock free characteristic.
+And you might have the performance bottle neck in the storage engine in updating data.
+
+Supported platforms
+-------------------
+
+We currently support the following platforms.
+
+* Linux x86_64 (Intel64/AMD64)
Added: doc/en/source/conf.py (+229 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/conf.py 2011-10-27 21:35:27 +0000 (3207fbb)
@@ -0,0 +1,229 @@
+# -*- coding: utf-8 -*-
+#
+# groonga storage engine documentation build configuration file, created by
+# sphinx-quickstart on Tue Aug 03 14:53:35 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+from datetime import datetime
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'groonga storage engine'
+copyright = u'2009-' + unicode(datetime.today().year) + u', groonga project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
+# The short X.Y version.
+version = os.environ["VERSION"]
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = "en"
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+ 'rightsidebar': 'true',
+ 'stickysidebar': 'true',
+# 'relbarbgcolor': '#ED4517',
+# 'relbartextcolor': 'white',
+# 'relbarlinkcolor': '#F8F0FF',
+# 'footerbgcolor': '#ED4517',
+# 'footertextcolor': 'white',
+# 'sidebarbgcolor': '#FFd587',
+# 'sidebartextcolor': '#ED4517',
+# 'sidebarlinkcolor': '#666666',
+ 'bodyfont': '#666666',
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = False
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'groongastorageenginedoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'groongastorageengine.tex', u'groonga storage engine Documentation',
+ u'groonga project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'groongastorageengine', u'groonga storage engine Documentation',
+ [u'groonga project'], 1)
+]
Added: doc/en/source/developer.rst (+174 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/developer.rst 2011-10-27 21:35:27 +0000 (240709f)
@@ -0,0 +1,174 @@
+.. highlightlang:: none
+
+Developer's guide
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ developer/debug
+ developer/release
+
+How we are developing
+---------------------
+
+We, the groonga storage engine development project, are doing Ticket Driven Development by using a BTS named Redmine.
+
+The location of our Redmine site is the following.
+
+http://redmine.groonga.org/projects/show/mroonga
+
+Developments are done per ticket.
+
+We would like to ask developers to register on the site above.
+
+Roadmaps
+--------------------
+
+You can see our roadmaps in the following page. Generally speaking, we develop based on the roadmap.
+
+http://redmine.groonga.org/projects/mroonga/roadmap
+
+We decide our roadmaps by discussing in off-line or on-line meetings.
+
+Roadmaps specify the list of adding features in each version.
+
+Source code management
+----------------------
+
+We manage the source code using git on github.
+
+http://github.com/mroonga/mroonga
+
+If you want to contribute, please make clone in read/write mode, and then commit and push please.
+
+If you still do not have your account on github.com, please register.
+
+Process of development
+----------------------
+
+We would like to develop in the following procedure.
+
+1. Create a new ticket and add a description
+2. Discuss in the development meating and update roadmaps
+3. Assign the ticket, and the assignee starts development
+4. Implement features or fix bugs, then push to the repository if needed
+5. Add and run test codes, then push to the repository
+6. Review the implementation and tests, and go back to 4. if needed
+7. Add or update documents, then push to the repository
+8. Close the ticket
+
+We welcome your ideas about new features or changes of specifications.
+Please create a ticket first and describe your idea there.
+
+For adding and running test codes, please refer the description below.
+
+Generally speaking, we want to ask the assignee to handle whole the process, like design, implementation, test and documentations.
+
+Then you ask other developers to review (especially in case of adding new features), and when it passes you add or update documents and the ticket can be closed.
+
+For adding and updating documents, please refer the description below.
+
+Release
+-------
+
+We release the software when all tickets of the roadmap are closed.
+
+We do the following to release.
+
+* Create source packages
+* Create binary packages
+* Update documents on http://mroonga.github.com
+* Announce the release
+
+(This section will be moved to :doc:`developer/release`).
+
+Development environment
+-----------------------
+
+Currently we are assuming the following development environments.
+
+* Linux x86_64
+* glibc 2.5
+* MySQL 5.5
+* groonga 1.2
+* cutter 1.1 (for C/C++ unit tests)
+* sphinx 1.0 (for documents)
+
+glibc 2.5 is used in Red Hat Enterprise Linux 5.
+
+Contents of the source tree
+---------------------------
+
+There are just a few source files for now, and we would like to keep it simple as possible.
+
+ha_mroonga.h
+ The header file of groonga storage engine
+
+ha_mroonga.cc
+ The implementation of groonga storage engine
+
+mrnsys.h
+ The header file of utility functions
+
+mrnsys.c
+ The implementation of utility functions
+
+test/sql/
+ The directory for tests by SQL
+
+test/sql/t/
+ SQL test scripts, that are also the definition of currently available SQL statements
+
+test/sql/r/
+ The expected results of SQL tests, that are also the definition of the current specification of supported SQL
+
+test/unit/
+ The directory for per-function unit tests by C/C++
+
+doc/ja/
+ Documents in sphinx format
+
+Since we are still in the early stage of the development of groonga storage engine, we will not make the documents of the specification of SQL queries for now.
+
+Alternatively we consider our SQL tests and its expected results as the list of features and the definition of their specifications.
+
+Adding and running tests
+------------------------
+
+We use two kinds of regression tests to manage the quality of groonga storage engine.
+
+SQL tests
+ When you add features or fix bugs that can be confirmed by SQL queries, please always add SQL tests. You might think that performance improvements cannot be confirmed with SQL, but some can be still well tested by using status variables or information_schema plugin etc.
+
+C/C++ unit tests
+ They are function level regression tests using cutter. When you add features that cannot differ SQL queries' results, like utility functions, please add tests here.
+
+Before pushing to the repository, please always run the regression tests and confirm that you don't introduce any degradation.
+
+You can invoke these two kinds of tests by "make check".
+
+SQL tests are implemented as "sub test suite" for "mysql-test" in MySQL's regression tests. For the detail about how to add test cases or how to modify expected result files, please refer the following MySQL document.
+
+http://dev.mysql.com/doc/mysqltest/2.0/en/index.html
+
+For the detail about C/C++ unit tests, please refer the following cutter document.
+
+http://cutter.sourceforge.net/
+
+Adding and updating documents
+-----------------------------
+
+We use sphinx for the documentation of groonga storage engine.
+
+We write documents in ReStructuredText format and we convert them to HTML etc.
+
+The source files of documents are files having .rst extension in "doc/ja/source" directory.
+
+When you add or modify them, please try to buid by "make html" etc. and confirm that no syntax error happens.
+
+Documents are published in http://mroonga.github.com . Since we are using github's web site feature, they will be updated each time when HTML files are pushed to http://github.com/mroonga/mroonga.github.com repository. We push to mroonga.github.com repository after confirming the consistency between documents and current released version.
+
+So you can just push to mroonga repository to push documents for each ticket.
+
+To avoid the issue that directory names of sphinx's output cannot be used in github, we prepare sphinx2github.sh script in "doc/en/source" directory. When you commit to mroonga.github.com repository, please modify sphinx's output files by using this script beforehand.
Added: doc/en/source/developer/debug.rst (+80 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/developer/debug.rst 2011-10-27 21:35:27 +0000 (79fadf9)
@@ -0,0 +1,80 @@
+.. highlightlang:: none
+
+How to debug
+============
+
+Building for debugging
+-----------------------
+
+Whe you build software for debugging, you can get more information like symbol resolutions in gdb.
+So we build both MySQL and groonga storage engine for debugging in development.
+
+.. note::
+
+ If you build one of them for debugging, the size of structures etc. might be different, and you might not be able to load groonga storage engine, or assertions don't work in running.
+
+How to build MySQL for debugging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As you can see in `MySQL :: MySQL 5.5 Reference Manual :: 2.9.2 Installing MySQL from a Standard Source Distribution`_, you can build MySQL for debugging by passing ``-DWITH_DEBUG=yes`` option in CMAKE options.
+
+The procedure from download to build is the following. ::
+
+ % mkdir -p ~/work/
+ % cd ~/work/
+ % wget http://ftp.jaist.ac.jp/pub/mysql/Downloads/MySQL-5.5/mysql-5.5.13.tar.gz
+ % tar xvzf mysql-5.5.13.tar.gz
+ % cd mysql-5.5.13
+ % cmake . -DCMAKE_INSTALL_PREFIX=/tmp/local -DWITH_DEBUG=yes
+ % make
+
+.. _`MySQL :: MySQL 5.5 Reference Manual :: 2.9.2 Installing MySQL from a Standard Source Distribution`: http://dev.mysql.com/doc/refman/5.5/en/installing-source-distribution.html
+
+How tom build groonga storage engine for debugging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can build groonga storage engine for debugging by passing ``--with-debug`` in configure options.
+
+The procedure from cloning repository to build is the following. ::
+
+ % cd ~/work/
+ % git clone git****@githu*****:mroonga/mroonga.git
+ % cd mroonga
+ % ./autogen.sh
+ % ./configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0" --with-debug --prefix=/tmp/local --with-mysql-source=$HOME/work/mysql-5.5.13 --with-mysql-config=$HOME/work/mysql-5.5.13/scripts/mysql_config
+ % make
+
+Whe you successfully build both, please invoke tests like the following.
+If you get ``[pass]`` for all tests, you succeeded to build for debugging. ::
+
+ % test/run-sql-test.sh
+
+More about run-sql-test.sh
+--------------------------
+
+run-sql-test.sh is our friend for debugging.
+Here we show some examples of its usage.
+
+Run the specified test only
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you invoke run-sql-test.sh without any option, all tests under ``test/sql/t/`` will be invoked.
+
+So if you want to run certain tests only, you can specify the test name in --do-test option. ::
+
+ ./test/run-sql-test.sh --do-test=foobar
+
+See the trace
+^^^^^^^^^^^^^
+
+When you run tests by adding ``--debug`` option like the following, function calls information is recorded.
+This information is stored in ``${MySQL's working directory}/${MySQL version}/mysql-test/var/log/mysqld.1.trace``.
+
+When you add a new function, it would be a good idea to put it in the beginning of MRN_DBUG_ENTER_FUNCTION function and record its calls.
+
+Invoking GDB
+^^^^^^^^^^^^
+
+By adding ``--gdb`` option, you can debug with GDB when you run tests. ::
+
+ ./test/run-sql-test.sh --gdb
Added: doc/en/source/developer/release.rst (+197 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/developer/release.rst 2011-10-27 21:35:27 +0000 (4fd3a42)
@@ -0,0 +1,197 @@
+.. highlightlang:: none
+
+Release procedure (XXX not yet translated)
+=================
+
+変更点の記述
+------------
+
+まず ``doc/ja/source/news.rst`` に変更点をまとめます。
+
+次に、バージョンを確かめます。
+
+例えば ``git tag`` の結果が次のようになっていたとき ::
+
+ $ git tag
+ v0.1
+ v0.2
+ v0.3
+ v0.3a
+ v0.4
+ v0.5
+ v0.6
+
+次のようにすると、タグ ``v0.6`` 以降のコミットを閲覧できます。 ::
+
+ $ git log -p --reverse v0.6..
+
+配布用ファイルのアップロード
+----------------------------
+
+次に、配布用の ``tar.gz`` ファイルを作成します。 ::
+
+ $ make dist
+
+そして、作成された ``tar.gz`` ファイルを https://github.com/mroonga/mroonga/downloads よりアップロードします。
+
+パッケージの作成
+----------------
+
+Linux 用にパッケージを作成する必要があります。パッケージは以下の 2 種類に分けることが可能です。
+
+1. Debian 系
+2. Red Hat 系
+
+.. note::
+
+ 現在のところ、パッケージの作成は Debian GNU/Linux (Ubuntu も可) でしか行えません。
+
+Debian 系
++++++++++
+
+.. note::
+
+ 以下の作業は初回パッケージ作成時のみ必要です。初回パッケージ作成時にはパッケージ作成に必要なソフトウェアをインストールします。::
+
+ $ sudo apt-get install -y debootstrap
+
+まず apt ディレクトリに移動します。 ::
+
+ $ cd apt
+
+その後、次のようにすれば一連のリリース作業（build update sign upload）が行われますが、途中で失敗することもあります。 ::
+
+ $ make release
+
+そのため head コマンドなどで Makefile.am の内容を確認し、順番に作業を行っていくほうが良いこともあります。 ::
+
+ $ make build
+ $ make update
+ $ make sign
+ $ make upload
+
+make build に PARALLEL=yes とするとビルドが並列に走り、作業がより高速に行えます。
+
+また make build CODES=lucid などとすると、ビルド対象を指定することができます。
+
+このように Makefile.am を書き換えずにコマンドライン引数でビルドの挙動を変更する方法は、知っておいて損はないでしょう。
+
+Red Hat 系
+++++++++++
+
+.. note::
+
+ 以下の作業は初回パッケージ作成時のみ必要です。初回パッケージ作成時にはパッケージ作成に必要なソフトウェアをインストールします。::
+
+ $ sudo apt-get install -y rinse createrepo rpm
+
+まず yum ディレクトリに移動する。
+
+その後、次のようにすれば一連のリリース作業（build sign update upload）が行われますが、途中で失敗することもあります。 ::
+
+ $ make release
+
+そのため head コマンドなどで Makefile.am の内容を確認し、順番に作業を行っていくほうが良いこともあります。 ::
+
+ $ make build
+ $ make sign
+ $ make update
+ $ make upload
+
+タグを打つ
+----------
+
+``make tag`` とするとタグが打たれます。 ::
+
+ $ make tag
+ $ git push --tags origin
+
+ドキュメントのアップロード
+--------------------------
+
+1. GitHub からドキュメントアップロード用のリポジトリ (mroonga.github.com) を clone
+2. mroonga/doc/ja/sphinx2github.sh を実行し mroonga/doc/ja/html 内のディレクトリ名を GitHub (Jekyll) 用に変更
+3. mroonga/doc/ja/html 内のファイルを 1. で clone した mroonga.github.com にコピー
+4. mroonga.github.com へコミットを行い GitHub へ push
+
+リリースメールの送信
+--------------------
+
+メーリングリスト (ml****@mysql*****) にリリースメールを流します。メッセージ内容のテンプレートを以下に示します。 ::
+
+ ドキュメント(インストールガイド含む)
+ http://mroonga.github.com/
+
+ ダウンロード
+ http://github.com/mroonga/mroonga/downloads
+
+ groongaストレージエンジンとは、全文検索エンジンであるgroonga
+ をベースとしたMySQLのストレージエンジンです。Tritonnの後継プ
+ ロジェクトとなります。
+
+
+ 最近のトピックス
+ ================
+
+ # <<<ユーモアを交えて最近のトピックスを>>>
+
+ 先月開催されたMySQL Conference 2011でgroongaストレージエンジ
+ ンについて発表してきました。（私じゃなくて開発チームのみなさ
+ んが。）英語ですが、以下の発表資料があるので興味がある方はご
+ 覧ください。
+
+ http://groonga.org/ja/publication/
+
+
+ いろいろ試してくれている方もいらっしゃるようでありがとうござ
+ います。いちいさんなど使った感想を公開してくれていてとても参
+ 考になります。ありがとうございます。
+ http://d.hatena.ne.jp/ichii386/20110427/1303852054
+
+ （↓の変更点にあるとおり、今回のリリースからauto_increment機
+ 能が追加されています。）
+
+
+ ただ、「REPLACE INTO処理が完了せずにコネクションを消費する」
+ のようなバグレポートがあるように、うまく動かないケースもある
+ ようなので、試していただける方は注意してください。
+ http://redmine.groonga.org/issues/910
+
+ 今日リリースしたgroonga 1.2.2でマルチスレッド・マルチプロセ
+ ス時にデータ破損してしまう問題を修正しているので、最新の
+ groongaと組み合わせると問題が解決しているかもしれません。
+
+ 使ってみて、なにか問題があったら報告してもらえると助かります。
+
+ # <<<<以下 news.rst に書かれている内容を貼り付ける>>>
+
+ 変更点
+ ======
+
+ 0.5からの変更点は以下の通りです。
+ http://mroonga.github.com/news.html#release-0-6
+
+ 改良
+ ----
+
+ auto_increment機能の追加。#670
+ 不必要な”duplicated _id on insert”というエラーメッセージを抑制。 #910（←は未修正）
+ CentOSで利用しているMySQLのバージョンを5.5.10から5.5.12へアップデート。
+ Ubuntu 11.04 Natty Narwhalサポートの追加。
+ Ubuntu 10.10 Maverick Meerkatサポートの削除。
+ Fedora 15サポートの追加。
+ Fedora 14サポートの削除。
+
+ 修正
+ ----
+
+ ORDER BY LIMITの高速化が機能しないケースがある問題の修正。#845
+ デバッグビルド時のメモリリークを修正。
+ 提供しているCentOS用パッケージをOracle提供MySQLパッケージと一緒に使うとクラッシュする問題を修正。
+
+ 感謝
+ ----
+
+ Mitsuhiro Shibuyaさん
+ Hiroki Minetaさん
+ @kodakaさん
Added: doc/en/source/index.rst (+27 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/index.rst 2011-10-27 21:35:27 +0000 (9579869)
@@ -0,0 +1,27 @@
+.. groonga storage engine documentation master file, created by
+ sphinx-quickstart on Tue Aug 03 14:53:35 2010.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+groonga storage engine
+======================
+
+For the release history: :doc:`news`
+
+.. toctree::
+ :maxdepth: 3
+ :numbered:
+
+ characteristic
+ install
+ userguide
+ reference
+ developer
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
Added: doc/en/source/install.rst (+262 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/install.rst 2011-10-27 21:35:27 +0000 (6cbfb70)
@@ -0,0 +1,262 @@
+.. highlightlang:: none
+
+Installation Guide
+==================
+
+バイナリパッケージを使用したインストールではgroonga関連パッケージと共にMySQL関連のパッケージもインストールされます。
+
+それぞれの環境毎にインストール方法を説明します。
+
+Debian GNU/Linux squeeze
+------------------------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+/etc/apt/sources.list.d/groonga.list::
+
+ deb http://packages.groonga.org/debian/ squeeze main
+ deb-src http://packages.groonga.org/debian/ squeeze main
+
+インストール::
+
+ % sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 1C837F31
+ % sudo aptitude update
+ % sudo aptitude -V -D -y install mysql-server-groonga
+
+Debian GNU/Linux wheezy
+-----------------------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+/etc/apt/sources.list.d/groonga.list::
+
+ deb http://packages.groonga.org/debian/ wheezy main
+ deb-src http://packages.groonga.org/debian/ wheezy main
+
+インストール::
+
+ % sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 1C837F31
+ % sudo aptitude update
+ % sudo aptitude -V -D -y install mysql-server-groonga
+
+Debian GNU/Linux sid
+--------------------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+/etc/apt/sources.list.d/groonga.list::
+
+ deb http://packages.groonga.org/debian/ unstable main
+ deb-src http://packages.groonga.org/debian/ unstable main
+
+インストール::
+
+ % sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 1C837F31
+ % sudo aptitude update
+ % sudo aptitude -V -D -y install mysql-server-groonga
+
+Ubuntu 10.04 LTS Lucid Lynx
+---------------------------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+.. note::
+
+ Ubuntu本家のuniverseセクションもインストール対象としておくこと
+
+/etc/apt/sources.list.d/groonga.list::
+
+ deb http://packages.groonga.org/ubuntu/ lucid universe
+ deb-src http://packages.groonga.org/ubuntu/ lucid universe
+
+インストール::
+
+ % sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 1C837F31
+ % sudo aptitude update
+ % sudo aptitude -V -D -y install mysql-server-groonga
+
+Ubuntu 11.04 Natty Narwhal
+--------------------------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+.. note::
+
+ Ubuntu本家のuniverseセクションもインストール対象としておくこと
+
+/etc/apt/sources.list.d/groonga.list::
+
+ deb http://packages.groonga.org/ubuntu/ natty universe
+ deb-src http://packages.groonga.org/ubuntu/ natty universe
+
+インストール::
+
+ % sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 1C837F31
+ % sudo aptitude update
+ % sudo aptitude -V -D -y install mysql-server-groonga
+
+CentOS 5
+--------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+既にディストリビューション由来のMySQLパッケージがインストール済みの場合には事前に削除する必要があります。
+
+既存のMySQLパッケージを削除::
+
+ % sudo yum remove mysql*
+
+インストール::
+
+ % sudo rpm -ivh http://packages.groonga.org/centos/groonga-repository-1.0.0-0.noarch.rpm
+ % sudo yum update
+ % sudo yum install -y mysql-groonga
+
+CentOS 6
+--------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+CentOS 6用のパッケージはCentOS 5用のパッケージと違い、ディストリビューション由来のMySQLパッケージ（MySQL 5.1系）を利用します。そのため、ディストリビューション由来のMySQLを削除する必要はありません。
+
+インストール::
+
+ % sudo rpm -ivh http://packages.groonga.org/centos/groonga-repository-1.0.0-0.noarch.rpm
+ % sudo yum update
+ % sudo yum install -y mysql-groonga
+
+Fedora 15
+---------
+
+.. note::
+
+ amd64版のみ提供でi386版は未提供。
+
+インストール::
+
+ % sudo rpm -ivh http://packages.groonga.org/fedora/groonga-repository-1.0.0-0.noarch.rpm
+ % sudo yum update
+ % sudo yum install -y mysql-groonga
+
+ソースコードからのインストール
+------------------------------
+
+ソースコードからインストールする方法を説明します。パッケージ
+がない環境ではソースコードからインストールすることになります。
+
+形態素解析(MeCab)について
++++++++++++++++++++++++++
+
+形態素単位でトークナイズした全文検索索引を使用したい場合は、
+groongaのインストール前に `MeCab <http://mecab.sourceforge.net/>`_
+をインストールしてください。
+
+ダウンロード
+++++++++++++
+
+リリース版のソースコードを利用する場合は `GitHubのダウンロードページ <http://github.com/mroonga/mroonga/downloads>`_ からtarballをダウンロードしてください。
+
+最新のソースコードを利用する場合は `GitHub <https://github.com/mroonga/mroonga/>`_ からcloneして `./autogen.sh` を実行してください。（GNU Autotoolsが必要です。）この方法は開発に慣れた方向けなので、そうでない方はtarballを使うことをお勧めします。::
+
+ % git clone https://github.com/mroonga/mroonga.git
+ % mroonga
+ % ./autogen.sh
+
+前提条件
+++++++++
+
+MySQLおよびgroongaが既にインストールされている必要があります。
+
+またgroongaストレージエンジンをビルドするためにはMySQLのソースコードも必要です。
+
+MySQLのインストール
++++++++++++++++++++
+
+MySQL 5.5最新版のソースコードをダウンロードし、ビルド＆インストールして下さい。
+
+http://dev.mysql.com/downloads/mysql/
+
+mysql-5.5.16を使用し、以下にソースディレクトリが展開されているものと仮定します。 ::
+
+ /usr/local/src/mysql-5.5.16
+
+MySQLのバイナリが以下にインストールされているものと仮定します。 ::
+
+ /usr/local/mysql
+
+groongaのインストール
++++++++++++++++++++++
+
+groongaの最新版をビルド＆インストールして下さい。
+
+http://groonga.org/docs/
+
+ここでは/usr/libなどの標準パスにlibgroongaがインストールされているものと仮定します。
+
+groongaストレージエンジンのビルド
++++++++++++++++++++++++++++++++++
+
+以下のように ``--with-mysql-source`` でMySQLソースコードディレクトリ、 ``--with-mysql-config`` でmysql_configコマンドのパスを指定してconfigureを実行します。 ::
+
+ ./configure \
+ --with-mysql-source=/usr/local/src/mysql-5.5.16 \
+ --with-mysql-config=/usr/local/mysql/bin/mysql_config
+
+groongaを/usr/libなど標準のパス以外にインストールした場合はPKG_CONFIG_PATHを指定する必要があります。例えば、ｰｰprefix=$HOME/localでgroongaをインストールした場合は以下のようにします。::
+
+ ./configure \
+ PKG_CONFIG_PATH=$HOME/local/lib/pkgconfig \
+ --with-mysql-source=/usr/local/src/mysql-5.5.16 \
+ --with-mysql-config=/usr/local/mysql/bin/mysql_config
+
+その後、"make"を実行します。 ::
+
+ make
+
+groongaストレージエンジンのインストール
++++++++++++++++++++++++++++++++++++++++
+
+"make install"を実行するとMySQLのプラグイン用ディレクトリにha_groonga.soが配置されます。 ::
+
+ make install
+
+その後、mysqldを起動し、mysqlクライアントで接続して"INSTALL PLUGIN"コマンドでインストールします。 ::
+
+ mysql> INSTALL PLUGIN groonga SONAME 'ha_groonga.so';
+
+以下のように"SHOW ENGINES"コマンドで"groonga"が表示されればgroongaストレージエンジンのインストールは完了です。 ::
+
+ mysql> SHOW ENGINES;
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ | Engine | Support | Comment | Transactions | XA | Savepoints |
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ | groonga | YES | Fulltext search, column base | NO | NO | NO |
+ | MRG_MYISAM | YES | Collection of identical MyISAM tables | NO | NO | NO |
+ | CSV | YES | CSV storage engine | NO | NO | NO |
+ | MyISAM | DEFAULT | Default engine as of MySQL 3.23 with great performance | NO | NO | NO |
+ | InnoDB | YES | Supports transactions, row-level locking, and foreign keys | YES | YES | YES |
+ | MEMORY | YES | Hash based, stored in memory, useful for temporary tables | NO | NO | NO |
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ 6 rows in set (0.00 sec)
+
+続いてUDF(ユーザ定義関数)をインストールします。
+
+INSERTを行った際にgroongaにより割当てられるレコードIDを取得するためのlast_insert_grn_id関数をインストールします。
+
+以下のようにCREATE FUNCTIONを実行します。 ::
+
+ mysql> CREATE FUNCTION last_insert_grn_id RETURNS INTEGER soname 'ha_groonga.so';
Added: doc/en/source/news.rst (+254 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/news.rst 2011-10-27 21:35:27 +0000 (12ee9a2)
@@ -0,0 +1,254 @@
+.. highlightlang:: none
+
+Recent news
+===========
+
+.. _release-1-0-1:
+
+1.0.1 released - 2011/10/29
+---------------------------
+
+The important changes in this release are the enhancement of geolocation search and the improvement of dynamic index modification in storage mode.
+
+Improvements
+++++++++++++
+
+* [storage mode][wrapper mode] support reopening a database by `flush tables`.
+* [wrapper mode] support geolocation index. (Only Point type can be stored in a column. Search using index is only available for MBRContains).
+* [benchmark] add `groonga_dry_write` variable to specify not to write to groonga database, that is useful to check bottle neckes in benchmarks.
+* mention MySQL version in the installation guide for CentOS 6. [proposed by @yoshi_ken]
+* [geolocation] improve performance by skip needless processes.
+* add `--disable-fast-mutexes` configure option to ignore fast mutexes even if mysql_config says it is enabled.
+* [storage mode] support `create index`.
+* [storage mode] support `drop index`.
+* [storage mode] support multi columns index for full text search.
+* support MySQL 5.5.17.
+* support groonga 1.2.7. (1.2.6 or below are no longer supported).
+
+Bug fixes
++++++++++
+
+* fix a bug that we have no results if we specify '+' at the beginning of the query in boolean mode. [reported by Hajime Nishiyama]
+* [Fedora] fix package dependencies. [reported by Takahiro Nagai]
+* [Fedora] fix a problem that we get undefined symol error when the plugin is loaded. [reported by Takahiro Nagai]
+
+Acknowledgements
+++++++++++++++++
+
+* @yoshi_ken
+* Hajime Nishiyama
+* Takahiro Nagai
+
+.. _release-1-0-0:
+
+1.0.0 リリース - 2011/09/29
+---------------------------
+
+初回リリースから約1年経って、初のメジャーリリース！
+
+改良
+++++
+
+* [ラッパーモード] drop index対応。 #1040
+* [ストレージモード] GEOMETRY対応。（ただし、カラムに保存できる型はPointのみ対応。インデックスを利用した位置検索はMBRContainsのみ対応。） #1041
+* [ストレージモード] マルチカラムインデックスに対応。 #455
+* [ストレージモード][ラッパーモード] 全文検索用パーサー（トークナイザー）のカスタマイズに対応。 #592
+* configureにデフォルトの全文検索用パーサーを指定する `--with-default-parser` オプションを追加。
+* 実行時にデフォルトの全文検索用パーサーを指定する `groonga_default_parser` 変数を追加。
+* [ラッパーモード] ストレージモードで実装している `order` と `limit` が指定された場合に必要のないレコードを返さないようにする高速化に対応。
+* [ストレージモード] 1つの `select` 中での複数の `match against` 指定に対応。
+* [非互換][ストレージモード] `_score` カラムの削除。代わりにMySQL標準の書き方である `match against` を使ってください。
+* [ラッパーモード] プライマリキーの更新に対応。
+* MySQL 5.5.16に対応。
+* CentOS 6に対応。
+* groonga 1.2.6に対応。（1.2.5以下のサポートを削除。）
+
+修正
+++++
+
+* [Ubuntu] Lucid上でインストールエラーが発生する問題を修正。 （Isao Sugimotoさんが報告）
+* auto_incrementを使った場合にテキストデータが壊れる問題を修正。 （@zaubermaerchenさんが報告） #1072
+* [Ubuntu] Lucid上でテーブルを削除するとクラッシュする問題を修正。 #1063 （Isao Sugimotoさんが報告）
+* MySQLと同じビルドオプションを使っていなかった問題を修正。 GitHub#4 (groongaのGitHubのIssues) （Tomohiro MITSUMUNEさんが報告）
+
+感謝
+++++
+
+* Isao Sugimotoさん
+* @zaubermaerchenさん
+* Tomohiro MITSUMUNEさん
+
+.. _release-0-9:
+
+0.9 リリース - 2011/08/29
+-------------------------
+
+改良
+++++
+
+* MySQL 5.1.58に対応。
+* MySQL 5.6.3に対応。
+
+.. _release-0-8:
+
+0.8 リリース - 2011/07/29
+-------------------------
+
+改良
+++++
+
+* [deb] プラグインインストール時のエラーを無視するようにした。
+* [ラッパーモード] マルチカラムインデックスのサポート。 #1031
+* [ラッパーモード] 大量レコードの全文検索に対応。 #1032
+* [ラッパーモード] MyISAM対応。 #1033
+
+.. _release-0-7:
+
+0.7 リリース - 2011/06/29
+-------------------------
+
+改良
+++++
+
+* 既存のストレージエンジンに全文検索機能を追加する :doc:`userguide/wrapper` の追加。
+* MySQL 5.5.13サポートの追加。 #984
+* 安定してきたので、groongaのデフォルトログレベルをDUMPからNOTICEに変更。
+* Mac OS Xでのビルドをサポート。（@issmさんが報告）
+
+修正
+++++
+
+* 常にデバッグモードでビルドされる問題を修正。（@supistarさんが報告）
+
+感謝
+++++
+
+* @issmさん
+* @supistarさん
+
+.. _release-0-6:
+
+0.6 リリース - 2011/05/29
+-------------------------
+
+改良
+++++
+
+* auto_increment機能の追加。#670
+* 不必要な"duplicated _id on insert"というエラーメッセージを
+ 抑制。 #910（←は未修正）
+* CentOSで利用しているMySQLのバージョンを5.5.10から5.5.12へ
+ アップデート。
+* Ubuntu 11.04 Natty Narwhalサポートの追加。
+* Ubuntu 10.10 Maverick Meerkatサポートの削除。
+* Fedora 15サポートの追加。
+* Fedora 14サポートの削除。
+
+修正
+++++
+
+* ORDER BY LIMITの高速化が機能しないケースがある問題の修正。#845
+* デバッグビルド時のメモリリークを修正。
+* 提供しているCentOS用パッケージをOracle提供MySQLパッケージ
+ と一緒に使うとクラッシュする問題を修正。
+
+感謝
+++++
+
+* Mitsuhiro Shibuyaさん
+* Hiroki Minetaさん
+* @kodakaさん
+
+0.5 リリース - 2011/03/29
+-------------------------
+
+改良
+++++
+
+* "uninstall plugin"対応 #741
+* MariaDB対応 （かずひこさんが提案）
+* 不要なデバッグシンボルを削除
+* MySQL 5.5への対応強化。
+* エラーメッセージの改良
+
+感謝
+++++
+
+* かずひこさん
+
+0.4 リリース - 2010/11/29
+-------------------------
+
+改良
+++++
+
+* 全文検索のスコア取得機能の追加。
+* レコードIDへのアクセス機能の追加。
+* 直近のレコードIDを参照するためのUDFの追加。
+* インデックスによる範囲検索機能の追加。
+* 全文検索におけるORDER BY LIMITパタンの高速化。
+* ``groonga_fast_order_limit`` ステータス変数の追加。
+* ログ出力機能の設定強化。
+* ``groonga_log_level`` システム変数の追加。
+* 全文検索機能の強化(NOT MATCH AGAINST対応)。
+* MySQL 5.5への対応。
+
+感謝
+++++
+
+* とみたまさひろさん
+
+0.3 リリース - 2010/10/29
+-------------------------
+
+改良
+++++
+
+* エラーメッセージの出力を実装。
+* カラムの刈り込みの実装を強化。
+* 行カウント高速化機能の実装。
+* ``groonga_count_skip`` ステータス変数の追加。
+* ユーザガイドドキュメントの追加。
+
+変更
+++++
+
+* インデックス作成時にNORMALIZEフラグを付与。
+
+修正
+++++
+
+* LIMITなどを用いた場合にカーソルが正しくクローズされない問題の修正。
+
+0.2 リリース - 2010/09/29
+-------------------------
+
+改良
+++++
+
+* packages.groonga.orgでのバイナリパッケージ配布開始。aptitude/yumによるインストールが可能に。
+* バイナリログの出力に対応。
+
+変更
+++++
+
+* 共有ライブラリの名前を"libgroonga_storage_engine.so"から"ha_groonga.so"に変更。
+* configureオプションの ``--with-mysql`` および ``--libdir`` を削除。
+* configureオプションの ``--with-mysql-source`` および ``--with-mysql-config`` を追加。
+
+修正
+++++
+
+* ヘッダファイルのincludeパスを修正。
+* "SHOW CREATE TABLE"に出力されるENGINE名を修正。
+
+感謝
+++++
+
+* とみたまさひろさん
+
+
+0.1 リリース - 2010/08/19
+-------------------------
+
+初回テストリリース
Added: doc/en/source/reference.rst (+55 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/reference.rst 2011-10-27 21:35:27 +0000 (adbb291)
@@ -0,0 +1,55 @@
+.. highlightlang:: none
+
+Reference
+=========
+
+List of available SQL commands
+------------------------------
+
+You can see many SQL examples in the following directory of groonga storage engine's source tree. ::
+
+ test/sql/t
+
+List of files ::
+
+ auto_increment.test insert.test
+ binlog.test insert_wrapper.test
+ btree.test last_insert_grn_id.test
+ count_performance.test log_level.test
+ create_table.test order_limit_performance.test
+ create_table_wrapper.test replace.test
+ delete.test select_all.test
+ delete_wrapper.test select_pkey.test
+ drop_database.test select_secondary_key.test
+ drop_table.test show_create_table.test
+ flush_logs.test show_table_status.test
+ fulltext.test tinyint.test
+ fulltext_wrapper.test update.test
+ hash.test update_wrapper.test
+ information_schema.test
+
+All SQL statements written there are currently available ones.
+
+(Or we can say that any SQL statements that are not written there are not supported.)
+
+List of server variables
+------------------------
+
+No server variable is added for now.
+
+List of status variables
+------------------------
+
+Here are the explanations of status variables that are introduced by groonga storage engine.
+
+groonga_count_skip
+^^^^^^^^^^^^^^^^^^
+
+This value is increased when 'fast line count feature' is used.
+You can use this value to check if the feature is working when you enable it.
+
+groonga_fast_order_limit
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This value is increased when 'fast ORDER BY LIMIT feature' is used.
+You can use this value to check if the feature is working when you enable it.
Added: doc/en/source/userguide.rst (+75 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/userguide.rst 2011-10-27 21:35:27 +0000 (4221560)
@@ -0,0 +1,75 @@
+.. highlightlang:: none
+
+User's guide
+============
+
+Please read the following to see how to install : :doc:`install`
+
+How to check the installation
+-----------------------------
+
+The way to start or stop MySQL server is just same as the normal MySQL.
+
+After invoking the MySQL server, connect to it by mysql command. If you set password, you need to add '-p' option. ::
+
+ shell> mysql -uroot test
+
+By using SHOW ENGINES command, you can check if groonga storage engine is installed. ::
+
+ mysql> SHOW ENGINES;
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ | Engine | Support | Comment | Transactions | XA | Savepoints |
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ | groonga | YES | Fulltext search, column base | NO | NO | NO |
+ | MRG_MYISAM | YES | Collection of identical MyISAM tables | NO | NO | NO |
+ | CSV | YES | CSV storage engine | NO | NO | NO |
+ | MyISAM | DEFAULT | Default engine as of MySQL 3.23 with great performance | NO | NO | NO |
+ | InnoDB | YES | Supports transactions, row-level locking, and foreign keys | YES | YES | YES |
+ | MEMORY | YES | Hash based, stored in memory, useful for temporary tables | NO | NO | NO |
+ +------------+---------+------------------------------------------------------------+--------------+------+------------+
+ 6 rows in set (0.00 sec)
+
+If you see "groonga" storage engine like above, the installation is well done.
+
+If not installed, invoke INSTALL PLUGIN command like below. ::
+
+ mysql> INSTALL PLUGIN groonga SONAME 'ha_groonga.so';
+
+Running modes
+-------------
+
+groonga storage engine can run in the following two modes.
+
+* storage mode
+* wrapper mode
+
+With the storage mode, we use groonga for both of the full text search function and the data storage.
+Since all functions of storage engine are realised with groonga, aggregations are fast, that is one of groonga's advantages, and you can manage the database directly by ``groonga`` command.
+
+The structure of the storage mode is the following. You use it instead of existing storage engines like MyISAM or InnoDB
+
+.. figure:: ../../images/storage-mode.png
+ :alt: storage mode
+ :align: center
+
+With the wrapper mode, groonga is used for full text search function only, and another existing storage engine like InnoDB is used for storing data.
+By using wrapper mode, you combine InnoDB that is well-use as the storage engine and groonga that is a proven full text search engine, and you can use it as the stable database having the fast full text search function.
+
+The structure of the wrapper mode is the following. Full text search related operations are done by groonga storage engine, and other operations are done by existing storage engines like MyISAM, InnoDB etc.
+Groonga storage engine is located between SQL Handler that processes SQL and an existing storage engine, thus all data goes through groonga storage engine.
+With this way, full text search indexing etc. are done transparently.
+
+.. figure:: ../../images/wrapper-mode.png
+ :alt: wrapper mode
+ :align: center
+
+Usage of each mode
+------------------
+
+Please see the following pages for the usage of each mode.
+
+.. toctree::
+ :maxdepth: 2
+
+ userguide/storage.rst
+ userguide/wrapper.rst
Added: doc/en/source/userguide/storage.rst (+429 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/userguide/storage.rst 2011-10-27 21:35:27 +0000 (d8f0339)
@@ -0,0 +1,429 @@
+.. highlightlang:: none
+
+ストレージモード
+================
+
+ここでは groonga ストレージエンジンにおけるストレージモードの利用方法を説明します。
+
+全文検索の利用方法
+------------------
+
+インストールが確認できたら、テーブルを1つ作成してみましょう。 ``ENGINE = groonga`` とgroongaストレージエンジンを指定するところがポイントです。::
+
+ mysql> CREATE TABLE diaries (
+ -> id INT PRIMARY KEY AUTO_INCREMENT,
+ -> content VARCHAR(255),
+ -> FULLTEXT INDEX (content)
+ -> ) ENGINE = groonga DEFAULT CHARSET utf8;
+ Query OK, 0 rows affected (0.10 sec)
+
+INSERTでデータを投入してみましょう。 ::
+
+ mysql> INSERT INTO diaries (content) VALUES ("明日の天気は晴れでしょう。");
+ Query OK, 1 row affected (0.01 sec)
+
+ mysql> INSERT INTO diaries (content) VALUES ("明日の天気は雨でしょう。");
+ Query OK, 1 row affected (0.00 sec)
+
+全文検索を実行してみます。 ::
+
+ mysql> SELECT * FROM diaries WHERE MATCH(content) AGAINST("晴れ");
+ +----+-----------------------------------------+
+ | id | content |
+ +----+-----------------------------------------+
+ | 1 | 明日の天気は晴れでしょう。 |
+ +----+-----------------------------------------+
+ 1 row in set (0.00 sec)
+
+おぉぉー。検索できましたね。
+
+検索スコアの取得方法
+--------------------
+
+.. note::
+
+ 1.0.0以前のgroongaストレージエンジンではMySQLの標準的な検索スコアの取得方法ではなく、 ``_score`` という専用のカラムを作成するという独自の方法でした。1.0.0からはMySQLの標準的な取得方法になっています。
+
+全文検索を行う際、指定したキーワードにより内容が一致するレコードを上位に表示したいというような場合があります。そうしたケースでは検索スコアを利用します。
+
+検索スコアはMySQLの標準的な方法 [#score]_ で取得できます。つまり、SELECTの取得するカラム名を指定するところやORDER BYのところにMATCH...AGAINSTを指定します。
+
+それでは実際にやってみましょう。::
+
+ mysql> INSERT INTO diaries (content) VALUES ("今日は晴れました。明日も晴れるでしょう。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO diaries (content) VALUES ("今日は晴れましたが、明日は雨でしょう。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> SELECT *, MATCH (content) AGAINST ("晴れ") FROM diaries WHERE MATCH (content) AGAINST ("晴れ") ORDER BY MATCH (content) AGAINST ("晴れ") DESC;
+ +----+--------------------------------------------------------------+------------------------------------+
+ | id | content | MATCH (content) AGAINST ("晴れ") |
+ +----+--------------------------------------------------------------+------------------------------------+
+ | 3 | 今日は晴れました。明日も晴れるでしょう。 | 2 |
+ | 1 | 明日の天気は晴れでしょう。 | 1 |
+ | 4 | 今日は晴れましたが、明日は雨でしょう。 | 1 |
+ +----+--------------------------------------------------------------+------------------------------------+
+ 3 rows in set (0.00 sec)
+
+検索対象の文字列 ``晴れ`` をより多く含む、すなわち検索スコアの高い ``id = 3`` のメッセージが上に来ていることが確認できます。また、SELECT句にMATCH AGAINSTを記述しているため、検索スコアも取得できています。
+
+属性名を変更したい場合は ``AS`` を使って下さい。 ::
+
+ mysql> SELECT *, MATCH (content) AGAINST ("晴れ") AS score FROM diaries WHERE MATCH (content) AGAINST ("晴れ") ORDER BY MATCH (content) AGAINST ("晴れ") DESC;
+ +----+--------------------------------------------------------------+------------------------------------+
+ | id | content | MATCH (content) AGAINST ("晴れ") |
+ +----+--------------------------------------------------------------+------------------------------------+
+ | 3 | 今日は晴れました。明日も晴れるでしょう。 | 2 |
+ | 1 | 明日の天気は晴れでしょう。 | 1 |
+ | 4 | 今日は晴れましたが、明日は雨でしょう。 | 1 |
+ +----+--------------------------------------------------------------+------------------------------------+
+ 3 rows in set (0.00 sec)
+
+
+全文検索用パーサの変更
+----------------------
+
+MySQLは全文検索用のパーサ [#parser]_ を指定する以下のような構文を持っています。::
+
+ FULLTEXT INDEX (content) WITH PARSER パーサ名
+
+しかし、この構文を利用する場合は、あらかじめすべてのパーサをMySQLに登録しておく必要があります。一方、groongaはトークナイザー（MySQLでいうパーサ）を動的に追加することができます。そのため、groognaストレージエンジンでもこの構文を採用するとgroonga側に動的に追加されたトークナイザーに対応できなくなります。groongaに動的に追加されるトークナイザーにはMeCabを用いたトークナイザーもあり、この制限に縛られることは利便性を損なうと判断し、以下のようなコメントを用いた独自の構文を採用することにしました。::
+
+ FULLTEXT INDEX (content) COMMENT 'parser "TokenMecab"'
+
+.. note::
+
+ ``FULLTEXT INDEX`` に ``COMMENT`` を指定できるのはMySQL 5.5からになります。MySQL 5.1を利用している場合は後述の ``groonga_default_parser`` 変数を利用してください。
+
+パーサに指定できるのは以下の値です。
+
+TokenBigram
+ バイグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、3文字以上のトークンも存在する。これはノイズを減らすためである。
+
+ デフォルト値。
+
+TokenMecab
+ MeCabを用いてトークナイズする。groongaがMeCabサポート付きでビルドされている必要がある。
+
+TokenBigramSplitSymbol
+ バイグラムでトークナイズする。TokenBigramと異なり、記号が連続していても特別扱いして1つのトークンとして扱わず通常のバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolを利用すると「Is it really!?!?!?」の「!?!?!?」の部分に「!?」でマッチする。TokenBigramの場合は「!?!?!?」でないとマッチしない。
+
+TokenBigramSplitSymbolAlpha
+ バイグラムでトークナイズする。TokenBigramSplitSymbolに加えて、連続したアルファベットも特別扱いせずに通常のバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolAlphaを利用すると「Is it really?」に「real」でマッチする。TokenBigramの場合は「really」でないとマッチしない。
+
+TokenBigramSplitSymbolAlphaDigit
+ バイグラムでトークナイズする。TokenBigramSplitSymbolAlphaに加えて、連続した数字も特別扱いせずに通常のバイグラムの処理を行う。つまり、すべての字種を特別扱いせずにバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolAlphaDigitを利用すると「090-0123-4567」に「567」でマッチする。TokenBigramの場合は「4567」でないとマッチしない。
+
+TokenBigramIgnoreBlank
+ バイグラムでトークナイズする。TokenBigramと異なり、空白を無視して処理する。
+
+ TokenBigramではなくTokenBigramIgnoreBlankを利用すると「み な さ ん 注 目」に「みなさん」でマッチする。TokenBigramの場合は「み な さ ん」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbol
+ バイグラムでトークナイズする。TokenBigramSymbolと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolではなくTokenBigramIgnoreBlankSplitSymbolを利用すると「! !? ??」に「???」でマッチする。TokenBigramSplitBlankの場合は「? ??」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbolAlpha
+ バイグラムでトークナイズする。TokenBigramSymbolAlphaと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolAlphaではなくTokenBigramIgnoreBlankSplitSymbolAlphaを利用すると「I am a pen.」に「ama」でマッチする。TokenBigramSplitBlankAlphaの場合は「am a」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbolAlphaDigit
+ バイグラムでトークナイズする。TokenBigramSymbolAlphaDigitと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolAlphaDigitではなくTokenBigramIgnoreBlankSplitSymbolAlphaDigitを利用すると「090 0123 4567」に「9001」でマッチする。TokenBigramSplitBlankAlphaDigitの場合は「90 01」でないとマッチしない。
+
+TokenDelimit
+ 空白区切りでトークナイズする。
+
+ 「映画 ホラー 話題」は「映画」・「ホラー」・「話題」にトークナイズされる。
+
+TokenDelimitNull
+ null文字（\\0）区切りでトークナイズする。
+
+ 「映画\\0ホラー\\0話題」は「映画」・「ホラー」・「話題」にトークナイズされる。
+
+TokenUnigram
+ ユニグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、2文字以上のトークンも存在する。これはノイズを減らすためである。
+
+TokenTrigram
+ トリグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、4文字以上のトークンも存在する。これはノイズを減らすためである。
+
+デフォルトのパーサは ``configure`` の ``--with-default-parser`` オプションでビルド時に指定することができます。::
+
+ ./configure --with-default-parser TokenMecab ...
+
+また、my.cnfまたはSQL内で ``groonga_default_parser`` 変数を指定することでも指定できます。my.cnfで指定するとMySQLを再起動しても値は変更されたままですが、反映させるために再起動しなければいけません。一方、SQLで指定した場合はすぐに設定が反映されますが、MySQLが再起動すると設定は失われます。
+
+my.cnf::
+
+ [mysqld]
+ groonga_default_parser=TokenMecab
+
+SQL::
+
+ mysql> SET GLOBAL groonga_default_parser = TokenMecab;
+ Query OK, 0 rows affected (0.00 sec)
+
+位置情報検索の利用方法
+----------------------
+
+ストレージモードでは全文検索だけではなく位置情報検索も高速に実行できます。ただし、MyISAMとは異なりデータとして格納できるのはPOINT型のみです。LINEなどの他のデータ型は保存できません。また、インデックスを用いた高速な検索に対応しているのはMBRContainsだけです。MBRDisjointなどには対応していません。
+
+位置情報検索を利用する場合のテーブル定義はMyISAMと同様にPOINT型のカラムを定義し、そのカラムに対してSPATIAL INDEXを指定します。::
+
+ mysql> CREATE TABLE shops (
+ -> id INT PRIMARY KEY AUTO_INCREMENT,
+ -> name VARCHAR(255),
+ -> location POINT NOT NULL,
+ -> SPATIAL INDEX (location)
+ -> ) ENGINE = groonga;
+ Query OK, 0 rows affected (0.06 sec)
+
+データの登録方法もMyISAMのときと同様にGeomFromText()関数を使って文字列からPOINT型の値を作成します。::
+
+ mysql> INSERT INTO shops VALUES (null, '根津のたいやき', GeomFromText('POINT(139.762573 35.720253)'));
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO shops VALUES (null, '浪花家', GeomFromText('POINT(139.796234 35.730061)'));
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO shops VALUES (null, '柳屋 たい焼き', GeomFromText('POINT(139.783981 35.685341)'));
+ Query OK, 1 row affected (0.00 sec)
+
+池袋駅（139.7101 35.7292）が左上の点、東京駅（139.7662 35.6815）が右下の点となるような長方形内にあるお店を探す場合は以下のようなSELECTになります。::
+
+ mysql> SELECT id, name, AsText(location) FROM shops WHERE MBRContains(GeomFromText('LineString(139.7101 35.7292, 139.7662 35.6815)'), location);
+ +----+-----------------------+------------------------------------------+
+ | id | name | AsText(location) |
+ +----+-----------------------+------------------------------------------+
+ | 1 | 根津のたいやき | POINT(139.762572777778 35.7202527777778) |
+ +----+-----------------------+------------------------------------------+
+ 1 row in set (0.00 sec)
+
+位置情報で検索できていますね！
+
+レコードIDの取得方法
+--------------------
+
+groongaではテーブルにレコードを追加した際にレコードを一意に識別するための番号が割当てられます。
+
+groongaストレージエンジンではアプリケーションの開発を容易にするため、このレコードIDをSQLで取得できるようになっています。
+
+レコードIDを取得するためには、テーブル定義時に ``_id`` という名前のカラムを作成して下さい。 ::
+
+ mysql> CREATE TABLE memos (
+ -> _id INT,
+ > content VARCHAR(255),
+ -> UNIQUE KEY (_id) USING HASH
+ -> ) ENGINE = groonga;
+ Query OK, 0 rows affected (0.04 sec)
+
+_idカラムのデータ型は整数型(TINYINT、SMALLINT、MEDIUMINT、INT、BIGINT)である必要があります。
+
+また_idカラムにはインデックスを作成することが可能ですが、HASH形式である必要があります。
+
+INSERTでテーブルにレコードを追加してみましょう。_idカラムは仮想カラムとして実装されており、また_idの値であるレコードIDはgroongaにより割当てられるため、SQLによる更新時に値を指定することはできません。
+更新対象から外すか、値に ``null`` を使用する必要があります。 ::
+
+ mysql> INSERT INTO memos VALUES (null, "今夜はさんま。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO memos VALUES (null, "明日はgroongaをアップデート。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO memos VALUES (null, "帰りにおだんご。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> INSERT INTO memos VALUES (null, "金曜日は肉の日。");
+ Query OK, 1 row affected (0.00 sec)
+
+レコードIDを取得するには、_idカラムを含むようにしてSELECTを行います。 ::
+
+ mysql> SELECT * FROM memos;
+ +------+------------------------------------------+
+ | _id | content |
+ +------+------------------------------------------+
+ | 1 | 今夜はさんま。 |
+ | 2 | 明日はgroongaをアップデート。 |
+ | 3 | 帰りにおだんご。 |
+ | 4 | 金曜日は肉の日。 |
+ +------+------------------------------------------+
+ 4 rows in set (0.00 sec)
+
+また直前のINSERTにより割当てられたレコードIDについては、last_insert_grn_id関数により取得することもできます。 ::
+
+ mysql> INSERT INTO memos VALUES (null, "冷蔵庫に牛乳が残り1本。");
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> SELECT last_insert_grn_id();
+ +----------------------+
+ | last_insert_grn_id() |
+ +----------------------+
+ | 5 |
+ +----------------------+
+ 1 row in set (0.00 sec)
+
+last_insert_grn_id関数はユーザ定義関数(UDF)としてgroongaストレージエンジンに含まれていますが、インストール時にCREATE FUNCTIONでMySQLに追加していない場合には、以下の関数定義DDLを実行しておく必要があります。 ::
+
+ mysql> CREATE FUNCTION last_insert_grn_id RETURNS INTEGER SONAME 'ha_groonga.so';
+
+ご覧のように_idカラムやlast_insert_grn_id関数を通じてレコードIDを取得することができました。ここで取得したレコードIDは後続のUPDATEなどのSQL文で利用すると便利です。 ::
+
+ mysql> UPDATE memos SET content = "冷蔵庫に牛乳はまだたくさんある。" WHERE _id = last_insert_grn_id();
+ Query OK, 1 row affected (0.00 sec)
+ Rows matched: 1 Changed: 1 Warnings: 0
+
+ログ出力
+--------
+
+groongaストレージエンジンではデフォルトでログの出力を行うようになっています。
+
+ログファイルはMySQLのデータディレクトリ直下に ``groonga.log`` というファイル名で出力されます。
+
+以下はログの出力例です。 ::
+
+ 2010-10-07 17:32:39.209379|n|b1858f80|groonga-storage-engine started.
+ 2010-10-07 17:32:44.934048|d|46953940|hash get not found (key=test)
+ 2010-10-07 17:32:44.936113|d|46953940|hash put (key=test)
+
+ログのデフォルトの出力レベルはNOTICE（必要な情報のみ出力。デバッグ情報などは出力しない）となっております。
+
+ログの出力レベルは ``groonga_log_level`` というシステム変数で確認することができます（グローバル変数）。またSET文で動的に出力レベルを変更することもできます。 ::
+
+ mysql> SHOW VARIABLES LIKE 'groonga_log_level';
+ +-------------------+--------+
+ | Variable_name | Value |
+ +-------------------+--------+
+ | groonga_log_level | NOTICE |
+ +-------------------+--------+
+ 1 row in set (0.00 sec)
+
+ mysql> SET GLOBAL groonga_log_level=DUMP;
+ Query OK, 0 rows affected (0.00 sec)
+
+ mysql> SHOW VARIABLES LIKE 'groonga_log_level';
+ +-------------------+-------+
+ | Variable_name | Value |
+ +-------------------+-------+
+ | groonga_log_level | DUMP |
+ +-------------------+-------+
+ 1 row in set (0.00 sec)
+
+設定可能なログレベルは以下の通りです。
+
+* NONE
+* EMERG
+* ALERT
+* CRIT
+* ERROR
+* WARNING
+* NOTICE
+* INFO
+* DEBUG
+* DUMP
+
+またFLUSH LOGSでログの再オープンを行うことができます。MySQLサーバを停止せずにログのローテートを行いたいような場合には、以下の手順で実行すると良いでしょう。
+
+1. ``groonga.log`` ファイルの名前を変更（OSコマンドのmvなどで）
+2. MySQLサーバに対して"FLUSH LOGS"を実行（mysqlコマンドあるいはmysqladminコマンドにて）
+
+カラムの刈り込み
+----------------
+
+groongaでは各カラムごとにファイルを分けてデータを格納する「カラムストア方式」が採用されており、groongaストレージエンジンではこの特性を活かすためにテーブルアクセス時に必要なカラムに対してのみアクセスを行う実装を行っています。
+
+この高速化の仕組みはgroongaストレージエンジン内部で自動的に行われるため、特に設定などを行う必要はありません。
+
+例えば以下のようにカラムが20個定義されているテーブルが存在するものと仮定します。 ::
+
+ CREATE TABLE t1 (
+ c1 INT PRIMARY KEY AUTO_INCREMENT,
+ c2 INT,
+ c3 INT,
+ ...
+ c11 VARCHAR(20),
+ c12 VARCHAR(20),
+ ...
+ c20 DATETIME
+ ) ENGINE = groonga DEFAULT CHARSET utf8;
+
+この時、以下のようなSELECT文が発行される場合、groongaストレージエンジンではSELECT句およびWHERE句で参照しているカラムに対してのみデータの読み取りを行ってSQL文を処理します（内部的に不要なカラムに対してはアクセスしません）。 ::
+
+ SELECT c1, c2, c11 FROM t1 WHERE c2 = XX AND c12 = "XXX";
+
+このケースではc1,c2,c11,c12に対してのみアクセスが行われ、SQL文が高速に処理されることになります。
+
+行カウント高速化
+----------------
+
+COUNT(\*)などの行カウントを行う場合と通常のSELECTによるデータ参照を行う場合に対して、従来よりMySQLではストレージエンジンの呼び出しを行う部分(=ストレージエンジンインタフェース)における区別が存在していないため、行数をカウントするだけで良いような場合にもレコードアクセス（SELECTの結果には含まれないデータへのアクセス）が行われる問題があります。
+
+groongaストレージエンジンの前身であるTritonn(MySQL+Senna)ではこの問題に対して"2indパッチ"という不要なレコードアクセスを省略する仕組みを独自に実装してこの性能問題を回避していました。
+
+これに引き続き、groongaストレージエンジンでも行カウントを高速化するための仕組みを実装しています。
+
+例えば以下のSELECT文では不要なカラムデータの読み取りは省略され、必要最小限のコストで行カウントの結果を返すことができます。 ::
+
+ SELECT COUNT(*) FROM t1 WHERE MATCH(c2) AGAINST("hoge");
+
+行カウント高速化の処理が行われたかどうかはステータス変数で確認することもできます。::
+
+ mysql> SHOW STATUS LIKE 'groonga_count_skip';
+ +--------------------+-------+
+ | Variable_name | Value |
+ +--------------------+-------+
+ | groonga_count_skip | 1 |
+ +--------------------+-------+
+ 1 row in set (0.00 sec)
+
+行カウント高速化の処理が行われる度に ``groonga_count_skip`` ステータス変数がインクリメントされます。
+
+備考：この高速化機能はインデックスを用いて実装されています。現在のところインデックスアクセスのみでレコードが特定できるパタンでのみ有効に機能します。
+
+全文検索時の ORDER BY LIMIT 高速化
+----------------------------------
+
+一般的にMySQLでは"ORDER BY"はインデックス経由のレコード参照が行えればほぼノーコストで処理可能であり、"LIMIT"は検索結果が大量にヒットする場合でも処理対象を限定することでコストを一定に抑える効果があります。
+
+しかし例えば全文検索のスコアの降順+LIMITのように"ORDER BY"の処理の際にインデックスが効かないクエリの場合、検索ヒット件数に比例したコストがかかってしまうため、特に大量の検索がヒットするようなキーワード検索においてクエリ処理に極端に時間がかかってしまうケースがあります。
+
+Tritonnではこの問題に対して特に対応はできていませんでしたが、最新レポジトリではsen_records_sort関数を活用してSennaからの読み出しをスコアの降順に対応させることでSQLクエリからORDER BY句を取り除く(※スコア降順を指定していたケースに対してのみ有効)回避方法を導入しました。
+
+groongaストレージエンジンでも ORDER BY LIMIT を高速化するための仕組みを実装しています。
+
+例えば以下のSELECT文では ORDER BY LIMIT は、groonga内で処理され、必要最小限のレコードだけをMySQLに返却しています。 ::
+
+ SELECT * FROM t1 WHERE MATCH(c2) AGAINST("hoge") ORDER BY c1 LIMIT 1;
+
+ORDER BY LIMIT 高速化の処理が行われたかどうかはステータス変数で確認することもできます。::
+
+ mysql> SHOW STATUS LIKE 'groonga_fast_order_limit';
+ +--------------------------+-------+
+ | Variable_name | Value |
+ +--------------------------+-------+
+ | groonga_fast_order_limit | 1 |
+ +--------------------------+-------+
+ 1 row in set (0.00 sec)
+
+ORDER BY LIMIT 高速化の処理が行われる度に ``groonga_fast_order_limit`` ステータス変数がインクリメントされます。
+
+備考：この高速化機能は、「select ... match against order by _score desc limit X, Y」を狙い撃ちした高速化で、現在のところ以下の条件が成立した場合に機能します。
+
+* where句がmatch...againstのみ
+* joinしていない
+* limitの指定がある
+* order byの指定がカラム(_id含む)またはwhere句に指定したmatch...againstである
+
+.. rubric:: 脚注
+
+.. [#score] `MySQL 5.1 リファレンスマニュアル :: 11 関数と演算子 :: 11.7 全文検索関数 <http://dev.mysql.com/doc/refman/5.1/ja/fulltext-search.html>`_
+.. [#parser] groongaではトークナイザーと呼んでいる。
Added: doc/en/source/userguide/wrapper.rst (+321 -0) 100644
===================================================================
--- /dev/null
+++ doc/en/source/userguide/wrapper.rst 2011-10-27 21:35:27 +0000 (12723db)
@@ -0,0 +1,321 @@
+.. highlightlang:: none
+
+ラッパーモード
+==============
+
+ここでは groonga ストレージエンジンにおけるラッパーモードの利用方法を説明します。
+
+ラッパーモードの利用方法
+------------------------
+
+ラッパーモードでは、既存のストレージエンジンをラップするかたちで groonga ストレージエンジンが動作します。ラップする対象となるストレージエンジンは、現在のところ SQL のコメントを利用して ``COMMENT = 'engine "innodb"'`` のように指定するようになっています。
+
+.. note::
+
+ 現在のところ、ラッパーモードではテーブルに必ずプライマリーキーを設定する必要があります。ストレージモードはこの限りではありません。
+
+.. note::
+
+ ラッパーモードでは現在ストレージモードでサポートされていない、以下をサポートしています。
+ * null値
+
+全文検索の利用方法
+------------------
+
+それでは早速 groonga ストレージエンジンのラッパーモードを利用して、テーブルを1つ作成してみましょう。 ::
+
+ mysql> CREATE TABLE diaries (
+ -> id INT PRIMARY KEY AUTO_INCREMENT,
+ -> content VARCHAR(255),
+ -> FULLTEXT INDEX (content)
+ -> ) ENGINE = groonga COMMENT = 'engine "innodb"' DEFAULT CHARSET utf8;
+ Query OK, 0 rows affected (0.52 sec)
+
+次に INSERT でデータを投入してみましょう。 ::
+
+ mysql> INSERT INTO diaries (content) VALUES ("明日の天気は晴れでしょう。");
+ Query OK, 1 row affected (0.26 sec)
+
+ mysql> INSERT INTO diaries (content) VALUES ("明日の天気は雨でしょう。");
+ Query OK, 1 row affected (0.29 sec)
+
+データの投入が終了したら、全文検索を実行してみます。 ::
+
+ mysql> SELECT * FROM diaries WHERE MATCH(content) AGAINST("晴れ");
+ +----+-----------------------------------------+
+ | id | content |
+ +----+-----------------------------------------+
+ | 1 | 明日の天気は晴れでしょう。 |
+ +----+-----------------------------------------+
+ 1 row in set (0.00 sec)
+
+お、検索できましたね。
+
+検索スコアの取得方法
+--------------------
+
+全文検索を行う際、指定したキーワードにより内容が一致するレコードを上位に表示したいというような場合があります。そうしたケースでは検索スコアを利用します。
+
+検索スコアはMySQLの標準的な方法で取得 [#score]_ できます。つまり、SELECTの取得するカラム名を指定するところやORDER BYのところにMATCH...AGAINSTを指定します。
+
+それでは実際にやってみましょう。::
+
+ mysql> INSERT INTO diaries (content) VALUES ("今日は晴れました。明日も晴れるでしょう。");
+ Query OK, 1 row affected (0.18 sec)
+
+ mysql> INSERT INTO diaries (content) VALUES ("今日は晴れましたが、明日は雨でしょう。");
+ Query OK, 1 row affected (0.46 sec)
+
+ mysql> SELECT *, MATCH (content) AGAINST ("晴れ") FROM diaries WHERE MATCH (content) AGAINST ("晴れ") ORDER BY MATCH (content) AGAINST ("晴れ") DESC;
+ +----+--------------------------------------------------------------+------------------------------------+
+ | id | content | MATCH (content) AGAINST ("晴れ") |
+ +----+--------------------------------------------------------------+------------------------------------+
+ | 3 | 今日は晴れました。明日も晴れるでしょう。 | 2 |
+ | 1 | 明日の天気は晴れでしょう。 | 1 |
+ | 4 | 今日は晴れましたが、明日は雨でしょう。 | 1 |
+ +----+--------------------------------------------------------------+------------------------------------+
+ 3 rows in set (0.01 sec)
+
+
+検索対象の文字列 ``晴れ`` をより多く含む、すなわち検索スコアの高い ``id = 3`` のメッセージが上に来ていることが確認できます。また、SELECT句にMATCH AGAINSTを記述しているため、検索スコアも取得できています。
+
+属性名を変更したい場合は ``AS`` を使って下さい。 ::
+
+ mysql> SELECT *, MATCH (content) AGAINST ("晴れ") AS score FROM diaries WHERE MATCH (content) AGAINST ("晴れ") ORDER BY MATCH (content) AGAINST ("晴れ") DESC;
+ +----+--------------------------------------------------------------+-------+
+ | id | content | score |
+ +----+--------------------------------------------------------------+-------+
+ | 3 | 今日は晴れました。明日も晴れるでしょう。 | 2 |
+ | 1 | 明日の天気は晴れでしょう。 | 1 |
+ | 4 | 今日は晴れましたが、明日は雨でしょう。 | 1 |
+ +----+--------------------------------------------------------------+-------+
+ 3 rows in set (0.00 sec)
+
+全文検索用パーサの変更
+----------------------
+
+MySQLは全文検索用のパーサ [#parser]_ を指定する以下のような構文を持っています。::
+
+ FULLTEXT INDEX (content) WITH PARSER パーサ名
+
+しかし、この構文を利用する場合は、あらかじめすべてのパーサをMySQLに登録しておく必要があります。一方、groongaはトークナイザー（MySQLでいうパーサ）を動的に追加することができます。そのため、groognaストレージエンジンでもこの構文を採用するとgroonga側に動的に追加されたトークナイザーに対応できなくなります。groongaに動的に追加されるトークナイザーにはMeCabを用いたトークナイザーもあり、この制限に縛られることは利便性を損なうと判断し、以下のようなコメントを用いた独自の構文を採用することにしました。::
+
+ FULLTEXT INDEX (content) COMMENT 'parser "TokenMecab"'
+
+.. note::
+
+ ``FULLTEXT INDEX`` に ``COMMENT`` を指定できるのはMySQL 5.5からになります。MySQL 5.1を利用している場合は後述の ``groonga_default_parser`` 変数を利用してください。
+
+パーサに指定できるのは以下の値です。
+
+TokenBigram
+ バイグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、3文字以上のトークンも存在する。これはノイズを減らすためである。
+
+ デフォルト値。
+
+TokenMecab
+ MeCabを用いてトークナイズする。groongaがMeCabサポート付きでビルドされている必要がある。
+
+TokenBigramSplitSymbol
+ バイグラムでトークナイズする。TokenBigramと異なり、記号が連続していても特別扱いして1つのトークンとして扱わず通常のバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolを利用すると「Is it really!?!?!?」の「!?!?!?」の部分に「!?」でマッチする。TokenBigramの場合は「!?!?!?」でないとマッチしない。
+
+TokenBigramSplitSymbolAlpha
+ バイグラムでトークナイズする。TokenBigramSplitSymbolに加えて、連続したアルファベットも特別扱いせずに通常のバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolAlphaを利用すると「Is it really?」に「real」でマッチする。TokenBigramの場合は「really」でないとマッチしない。
+
+TokenBigramSplitSymbolAlphaDigit
+ バイグラムでトークナイズする。TokenBigramSplitSymbolAlphaに加えて、連続した数字も特別扱いせずに通常のバイグラムの処理を行う。つまり、すべての字種を特別扱いせずにバイグラムの処理を行う。
+
+ TokenBigramではなくTokenBigramSplitSymbolAlphaDigitを利用すると「090-0123-4567」に「567」でマッチする。TokenBigramの場合は「4567」でないとマッチしない。
+
+TokenBigramIgnoreBlank
+ バイグラムでトークナイズする。TokenBigramと異なり、空白を無視して処理する。
+
+ TokenBigramではなくTokenBigramIgnoreBlankを利用すると「み な さ ん 注 目」に「みなさん」でマッチする。TokenBigramの場合は「み な さ ん」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbol
+ バイグラムでトークナイズする。TokenBigramSymbolと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolではなくTokenBigramIgnoreBlankSplitSymbolを利用すると「! !? ??」に「???」でマッチする。TokenBigramSplitBlankの場合は「? ??」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbolAlpha
+ バイグラムでトークナイズする。TokenBigramSymbolAlphaと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolAlphaではなくTokenBigramIgnoreBlankSplitSymbolAlphaを利用すると「I am a pen.」に「ama」でマッチする。TokenBigramSplitBlankAlphaの場合は「am a」でないとマッチしない。
+
+TokenBigramIgnoreBlankSplitSymbolAlphaDigit
+ バイグラムでトークナイズする。TokenBigramSymbolAlphaDigitと異なり、空白を無視して処理する。
+
+ TokenBigramSplitSymbolAlphaDigitではなくTokenBigramIgnoreBlankSplitSymbolAlphaDigitを利用すると「090 0123 4567」に「9001」でマッチする。TokenBigramSplitBlankAlphaDigitの場合は「90 01」でないとマッチしない。
+
+TokenDelimit
+ 空白区切りでトークナイズする。
+
+ 「映画 ホラー 話題」は「映画」・「ホラー」・「話題」にトークナイズされる。
+
+TokenDelimitNull
+ null文字（\\0）区切りでトークナイズする。
+
+ 「映画\\0ホラー\\0話題」は「映画」・「ホラー」・「話題」にトークナイズされる。
+
+TokenUnigram
+ ユニグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、2文字以上のトークンも存在する。これはノイズを減らすためである。
+
+TokenTrigram
+ トリグラムでトークナイズする。ただし、連続したアルファベット・連続した数字・連続した記号はそれぞれ1つのトークンとして扱う。そのため、4文字以上のトークンも存在する。これはノイズを減らすためである。
+
+デフォルトのパーサは ``configure`` の ``--with-default-parser`` オプションでビルド時に指定することができます。::
+
+ ./configure --with-default-parser TokenMecab ...
+
+また、my.cnfまたはSQL内で ``groonga_default_parser`` 変数を指定することでも指定できます。my.cnfで指定するとMySQLを再起動しても値は変更されたままですが、反映させるために再起動しなければいけません。一方、SQLで指定した場合はすぐに設定が反映されますが、MySQLが再起動すると設定は失われます。
+
+my.cnf::
+
+ [mysqld]
+ groonga_default_parser=TokenMecab
+
+SQL::
+
+ mysql> SET GLOBAL groonga_default_parser = TokenMecab;
+ Query OK, 0 rows affected (0.00 sec)
+
+..
+ 位置情報検索の利用方法
+ ----------------------
+
+ ラッパーモードではラップ対象のストレージエンジンに全文検索機能だけではなく位置情報検索機能も追加します。ただし、インデックスを用いた高速な検索に対応しているのはMBRContainsだけです。MBRDisjointなどには対応していません。
+
+ 位置情報検索を利用する場合のテーブル定義はMyISAMと同様にPOINT型のカラムを定義し、そのカラムに対してSPATIAL INDEXを指定します。::
+
+ mysql> CREATE TABLE shops (
+ -> id INT PRIMARY KEY AUTO_INCREMENT,
+ -> name VARCHAR(255),
+ -> location POINT NOT NULL,
+ -> SPATIAL INDEX (location)
+ -> ) ENGINE = groonga COMMENT = 'engine "innodb"';
+ Query OK, 0 rows affected (0.34 sec)
+
+ データの登録方法もMyISAMのときと同様にGeomFromText()関数を使って文字列からPOINT型の値を作成します。::
+
+ mysql> INSERT INTO shops VALUES (null, '根津のたいやき', GeomFromText('POINT(139.762573 35.720253)'));
+ Query OK, 1 row affected (0.26 sec)
+
+ mysql> INSERT INTO shops VALUES (null, '浪花家', GeomFromText('POINT(139.796234 35.730061)'));
+ Query OK, 1 row affected (0.06 sec)
+
+ mysql> INSERT INTO shops VALUES (null, '柳屋 たい焼き', GeomFromText('POINT(139.783981 35.685341)'));
+ Query OK, 1 row affected (0.02 sec)
+
+ 池袋駅（139.7101 35.7292）が左上の点、東京駅（139.7662 35.6815）が右下の点となるような長方形内にあるお店を探す場合は以下のようなSELECTになります。::
+
+ mysql> SELECT id, name, AsText(location) FROM shops WHERE MBRContains(GeomFromText('LineString(139.7101 35.7292, 139.7662 35.6815)'), location);
+ +----+-----------------------+------------------------------------------+
+ | id | name | AsText(location) |
+ +----+-----------------------+------------------------------------------+
+ | 1 | 根津のたいやき | POINT(139.762572777778 35.7202527777778) |
+ +----+-----------------------+------------------------------------------+
+ 1 row in set (0.00 sec)
+
+ 位置情報で検索できていますね！
+
+ログ出力
+--------
+
+groongaストレージエンジンではデフォルトでログの出力を行うようになっています。
+
+ログファイルはMySQLのデータディレクトリ（/var/lib/mysql/ など）直下に ``groonga.log`` というファイル名で出力されます。
+
+以下はログの出力例です。 ::
+
+ 2011-06-24 11:11:31.282121|n|6bdea740|groonga-storage-engine started.
+ 2011-06-24 11:11:31.282154|n|6bdea740|log level is 'NOTICE'
+ 2011-06-24 11:30:58.485508|n|3cda6700|DDL:table_create x
+ 2011-06-24 11:31:05.131690|n|cee84700|DDL:obj_remove x
+ 2011-06-24 13:37:31.692572|n|86ceb700|DDL:column_create t1_0001 c2
+ 2011-06-24 13:37:31.781556|n|86ceb700|DDL:set_source t1_0001.c2 t1.c2
+ 2011-06-24 13:49:27.767387|n|5cd1f700|DDL:obj_remove t1_0001
+ 2011-06-24 14:33:55.867480| |8cd59700|96a20c50|:18446744072478952540 filter(2)
+
+ログのデフォルトの出力レベルは NOTICE （必要な情報のみ出力。デバッグ情報などは出力しない）となっています。
+
+ログの出力レベルは ``groonga_log_level`` というシステム変数で確認することができます（グローバル変数）。またSET文で動的に出力レベルを変更することもできます。 ::
+
+ mysql> SHOW VARIABLES LIKE 'groonga_log_level';
+ +-------------------+--------+
+ | Variable_name | Value |
+ +-------------------+--------+
+ | groonga_log_level | NOTICE |
+ +-------------------+--------+
+ 1 row in set (0.00 sec)
+
+ mysql> SET GLOBAL groonga_log_level=DUMP;
+ Query OK, 0 rows affected (0.05 sec)
+
+ mysql> SHOW VARIABLES LIKE 'groonga_log_level';
+ +-------------------+-------+
+ | Variable_name | Value |
+ +-------------------+-------+
+ | groonga_log_level | DUMP |
+ +-------------------+-------+
+ 1 row in set (0.00 sec)
+
+設定可能なログレベルは以下の通りです。
+
+* NONE
+* EMERG
+* ALERT
+* CRIT
+* ERROR
+* WARNING
+* NOTICE
+* INFO
+* DEBUG
+* DUMP
+
+またFLUSH LOGSでログの再オープンを行うことができます。MySQLサーバを停止せずにログのローテートを行いたいような場合には、以下の手順で実行すると良いでしょう。
+
+1. ``groonga.log`` ファイルの名前を変更（OSコマンドのmvなどで）
+2. MySQLサーバに対して"FLUSH LOGS"を実行（mysqlコマンドあるいはmysqladminコマンドにて）
+
+全文検索時の ORDER BY LIMIT 高速化
+----------------------------------
+
+一般的にMySQLでは"ORDER BY"はインデックス経由のレコード参照が行えればほぼノーコストで処理可能であり、"LIMIT"は検索結果が大量にヒットする場合でも処理対象を限定することでコストを一定に抑える効果があります。
+
+しかし例えば全文検索のスコアの降順+LIMITのように"ORDER BY"の処理の際にインデックスが効かないクエリの場合、検索ヒット件数に比例したコストがかかってしまうため、特に大量の検索がヒットするようなキーワード検索においてクエリ処理に極端に時間がかかってしまうケースがあります。
+
+Tritonnではこの問題に対して特に対応はできていませんでしたが、最新レポジトリではsen_records_sort関数を活用してSennaからの読み出しをスコアの降順に対応させることでSQLクエリからORDER BY句を取り除く(※スコア降順を指定していたケースに対してのみ有効)回避方法を導入しました。
+
+groongaストレージエンジンでも ORDER BY LIMIT を高速化するための仕組みを実装しています。
+
+例えば以下のSELECT文では ORDER BY LIMIT は、groonga内で処理され、必要最小限のレコードだけをMySQLに返却しています。 ::
+
+ SELECT * FROM t1 WHERE MATCH(c2) AGAINST("hoge") ORDER BY c1 LIMIT 1;
+
+ORDER BY LIMIT 高速化の処理が行われたかどうかはステータス変数で確認することもできます。::
+
+ mysql> SHOW STATUS LIKE 'groonga_fast_order_limit';
+ +--------------------------+-------+
+ | Variable_name | Value |
+ +--------------------------+-------+
+ | groonga_fast_order_limit | 1 |
+ +--------------------------+-------+
+ 1 row in set (0.00 sec)
+
+ORDER BY LIMIT 高速化の処理が行われる度に ``groonga_fast_order_limit`` ステータス変数がインクリメントされます。
+
+備考：この高速化機能は、「select ... match against order by _score desc limit X, Y」を狙い撃ちした高速化で、現在のところ以下の条件が成立した場合に機能します。
+
+* where句がmatch...againstのみ
+* joinしていない
+* limitの指定がある
+* order byの指定がカラム(_id含む)またはwhere句に指定したmatch...againstである
+
+.. rubric:: 脚注
+
+.. [#score] `MySQL 5.1 リファレンスマニュアル :: 11 関数と演算子 :: 11.7 全文検索関数 <http://dev.mysql.com/doc/refman/5.1/ja/fulltext-search.html>`_
+.. [#parser] groongaではトークナイザーと呼んでいる。
Added: doc/en/sphinx2github.sh (+27 -0) 100755
===================================================================
--- /dev/null
+++ doc/en/sphinx2github.sh 2011-10-27 21:35:27 +0000 (0075987)
@@ -0,0 +1,27 @@
+#!/bin/sh
+
+rename()
+{
+ old_name=$1
+ new_name=$2
+
+ if [ -d $old_name ]; then
+ rm -rf $new_name
+ mv $old_name $new_name
+ fi
+}
+
+cd html
+
+rename _static static
+rename _sources sources
+rename _images images
+
+file_names=$(find . -name "*.html")
+for file_name in $file_names; do
+ sed -e 's/_static/static/g' $file_name |
+ sed -e 's/_sources/sources/g' |
+ sed -e 's/_images/images/g' > buf.txt
+ cp buf.txt $file_name
+ rm -f buf.txt
+done