.\" Man page generated from reStructuredText. . .TH "GROONGA" "1" "September 28, 2014" "4.0.6" "Groonga" .SH NAME groonga \- Groonga documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .INDENT 0.0 .IP \(bu 2 \fBnews\fP .UNINDENT .SH CHARACTERISTICS OF GROONGA .SS Groonga overview .sp 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. .sp 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. .sp The basic functions of Groonga are provided in a C library. Also, libraries for using Groonga in other languages, such as Ruby, are provided by related projects. In addition, groonga\-based storage engines are provided for MySQL and PostgreSQL. These libraries and storage engines allow any application to use Groonga. See \fI\%usage examples\fP\&. .SS Full text search and Instant update .sp In widely used DBMSs, updates are immediately processed, for example, a newly registered record appears in the result of the next query. In contrast, some full text search engines do not support instant updates, because it is difficult to dynamically update inverted indexes, the underlying data structure. .sp Groonga also uses inverted indexes but supports instant updates. In addition, Groonga allows you to search documents even when updating the document collection. Due to these superior characteristics, Groonga is very flexible as a full text search engine. Also, Groonga always shows good performance because it divides a large task, inverted index merging, into smaller tasks. .SS Column store and aggregate query .sp People can collect more than enough data in the Internet era. However, it is difficult to extract informative knowledge from a large database, and such a task requires a many\-sided analysis through trial and error. For example, search refinement by date, time and location may reveal hidden patterns. Aggregate queries are useful to perform this kind of tasks. .sp An aggregate query groups search results by specified column values and then counts the number of records in each group. For example, an aggregate query in which a location column is specified counts the number of records per location. Making a graph from the result of an aggregate query against a date column is an easy way to visualize changes over time. Also, a combination of refinement by location and an aggregate query against a date column allows visualization of changes over time in specific location. Thus refinement and aggregation are important to perform data mining. .sp A column\-oriented architecture allows Groonga to efficiently process aggregate queries because a column\-oriented database, which stores records by column, allows an aggregate query to access only a specified column. On the other hand, an aggregate query on a row\-oriented database, which stores records by row, has to access neighbor columns, even though those columns are not required. .SS Inverted index and tokenizer .sp An inverted index is a traditional data structure used for large\-scale full text search. A search engine based on inverted index extracts index terms from a document when it is added. Then in retrieval, a query is divided into index terms to find documents containing those index terms. In this way, index terms play an important role in full text search and thus the way of extracting index terms is a key to a better search engine. .sp A tokenizer is a module to extract index terms. A Japanese full text search engine commonly uses a word\-based tokenizer (hereafter referred to as a word tokenizer) and/or a character\-based n\-gram tokenizer (hereafter referred to as an n\-gram tokenizer). A word tokenizer\-based search engine is superior in time, space and precision, which is the fraction of relevant documents in a search result. On the other hand, an n\-gram tokenizer\-based search engine is superior in recall, which is the fraction of retrieved documents in the perfect search result. The best choice depends on the application in practice. .sp Groonga supports both word and n\-gram tokenizers. The simplest built\-in tokenizer uses spaces as word delimiters. Built\-in n\-gram tokenizers (n = 1, 2, 3) are also available by default. In addition, a yet another built\-in word tokenizer is available if MeCab, a part\-of\-speech and morphological analyzer, is embedded. Note that a tokenizer is pluggable and you can develop your own tokenizer, such as a tokenizer based on another part\-of\-speech tagger or a named\-entity recognizer. .SS Sharable storage and read lock\-free .sp Multi\-core processors are mainstream today and the number of cores per processor is increasing. In order to exploit multiple cores, executing multiple queries in parallel or dividing a query into sub\-queries for parallel processing is becoming more important. .sp A database of Groonga can be shared with multiple threads/processes. Also, multiple threads/processes can execute read queries in parallel even when another thread/process is executing an update query because Groonga uses read lock\-free data structures. This feature is suited to a real\-time application that needs to update a database while executing read queries. In addition, Groonga allows you to build flexible systems. For example, a database can receive read queries through the built\-in HTTP server of Groonga while accepting update queries through MySQL. .SS Geo\-location (latitude and longitude) search .sp Location services are getting more convenient because of mobile devices with GPS. For example, if you are going to have lunch or dinner at a nearby restaurant, a local search service for restaurants may be very useful, and for such services, fast geo\-location search is becoming more important. .sp Groonga provides inverted index\-based fast geo\-location search, which supports a query to find points in a rectangle or circle. Groonga gives high priority to points near the center of an area. Also, Groonga supports distance measurement and you can sort points by distance from any point. .SS Groonga library .sp The basic functions of Groonga are provided in a C library and any application can use Groonga as a full text search engine or a column\-oriented database. Also, libraries for languages other than C/C++, such as Ruby, are provided in related projects. See \fI\%related projects\fP for details. .SS Groonga server .sp Groonga provides a built\-in server command which supports HTTP, the memcached binary protocol and the Groonga Query Transfer Protocol (GQTP). Also, a Groonga server supports query caching, which significantly reduces response time for repeated read queries. Using this command, Groonga is available even on a server that does not allow you to install new libraries. .SS Mroonga storage engine .sp Groonga works not only as an independent column\-oriented DBMS but also as storage engines of well\-known DBMSs. For example, \fI\%Mroonga\fP is a MySQL pluggable storage engine using Groonga. By using Mroonga, you can use Groonga for column\-oriented storage and full text search. A combination of a built\-in storage engine, MyISAM or InnoDB, and a Groonga\-based full text search engine is also available. All the combinations have good and bad points and the best one depends on the application. See \fI\%related projects\fP for details. .SH INSTALL .sp This section describes how to install Groonga on each environment. There are packages for major platforms. It\(aqs recommended that you use package instead of building Groonga by yourself. But don\(aqt warry. There is a document about building Groonga from source. .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS Windows .sp This section describes how to install Groonga on Windows. You can install Groogna by extracting a zip package or running an installer. .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS Installer .sp For 32\-bit environment, download x86 executable binary from packages.groonga.org: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://packages.groonga.org/windows/groonga/groonga\-4.0.6\-x86.exe\fP .UNINDENT .UNINDENT .UNINDENT .sp Then run it. .sp For 64\-bit environment, download x64 executable binary from packages.goronga.org: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://packages.groonga.org/windows/groonga/groonga\-4.0.6\-x64.exe\fP .UNINDENT .UNINDENT .UNINDENT .sp Then run it. .sp Use command prompt in start menu to run \fB/reference/executables/groonga\fP\&. .SS zip .sp For 32\-bit environment, download x86 zip archive from packages.groonga.org: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://packages.groonga.org/windows/groonga/groonga\-4.0.6\-x86.zip\fP .UNINDENT .UNINDENT .UNINDENT .sp Then extract it. .sp For 64\-bit environment, download x64 zip archive from packages.groonga.org: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://packages.groonga.org/windows/groonga/groonga\-4.0.6\-x64.zip\fP .UNINDENT .UNINDENT .UNINDENT .sp Then extract it. .sp You can find \fB/reference/executables/groonga\fP in \fBbin\fP folder. .SS Build from source .sp First, you need to install required tools for building Groonga on Windows. Here are required tools: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Microsoft Visual Studio 2010 Express\fP .IP \(bu 2 \fI\%CMake\fP .UNINDENT .UNINDENT .UNINDENT .sp Download zipped source from packages.groonga.org: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://packages.groonga.org/source/groonga/groonga\-4.0.6.zip\fP .UNINDENT .UNINDENT .UNINDENT .sp Then extract it. .sp Move to the Groonga\(aqs source folder: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > cd c:\eUsers\e%USERNAME%\eDownloads\egroonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure by \fBcmake\fP\&. The following commnad line is for 64\-bit version. To build 32\-bit version, use \fB\-G "Visual Studio 10"\fP parameter instead: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-4.0.6> cmake . \-G "Visual Studio 10 Win64" \-DCMAKE_INSTALL_PREFIX=C:\egroonga .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-4.0.6> cmake \-\-build . \-\-config Release .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-4.0.6> cmake \-\-build . \-\-config Release \-\-target Install .ft P .fi .UNINDENT .UNINDENT .sp After the above steps, \fB/reference/executables/groonga\fP is found in \fBc:\egroonga\ebin\egroonga.exe\fP\&. .SS Mac OS X .sp This section describes how to install Groonga on Mac OS X. You can install Groonga by \fI\%MacPorts\fP or \fI\%Homebrew\fP\&. .SS MacPorts .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo port install groonga .ft P .fi .UNINDENT .UNINDENT .SS Homebrew .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % brew install groonga .ft P .fi .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, specify \fB\-\-with\-mecab\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % brew install groonga \-\-with\-mecab .ft P .fi .UNINDENT .UNINDENT .SS Build from source .sp Install \fI\%Xcode\fP\&. .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-O http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j$(/usr/sbin/sysctl \-n hw.ncpu) .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS Debian GNU/Linux .sp This section describes how to install Groonga related deb packages on Debian GNU/Linux. You can install them by \fBapt\fP\&. .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS wheezy .sp Add the Groonga apt repository. .sp /etc/apt/sources.list.d/groonga.list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb http://packages.groonga.org/debian/ wheezy main deb\-src http://packages.groonga.org/debian/ wheezy main .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get update % sudo apt\-get install \-y \-\-allow\-unauthenticated groonga\-keyring % sudo apt\-get update % sudo apt\-get install \-y \-V groonga .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-y \-V groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, install groonga\-munin\-plugins package. .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-y \-V groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-y \-V groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS Build from source .sp Install required packages to build Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-y \-V wget tar build\-essential zlib1g\-dev liblzo2\-dev libmsgpack\-dev libzmq\-dev libevent\-dev libmecab\-dev .ft P .fi .UNINDENT .UNINDENT .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j$(grep \(aq^processor\(aq /proc/cpuinfo | wc \-l) .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS Ubuntu .sp This section describes how to install Groonga related deb packages on Ubuntu. You can install them by \fBapt\fP\&. .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS PPA (Personal Package Archive) .sp The Groonga APT repository for Ubuntu uses PPA (Personal Package Archive) on Launchpad. You can install Groonga by APT from the PPA. .sp Here are supported Ubuntu versions: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 12.04 LTS Precise Pangolin .IP \(bu 2 13.10 Saucy Salamander .IP \(bu 2 14.04 LTS Trusty Tahr .UNINDENT .UNINDENT .UNINDENT .sp Enable the universe repository to install Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-y install software\-properties\-common % sudo add\-apt\-repository \-y universe .ft P .fi .UNINDENT .UNINDENT .sp Add the \fBppa:groonga/ppa\fP PPA to your system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo add\-apt\-repository \-y ppa:groonga/ppa % sudo apt\-get update .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-y install groonga .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-y install groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, install groonga\-munin\-plugins package. .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-y install groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as Groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-y install groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS Build from source .sp Install required packages to build Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get \-V \-y install wget tar build\-essential zlib1g\-dev liblzo2\-dev libmsgpack\-dev libzmq\-dev libevent\-dev libmecab\-dev .ft P .fi .UNINDENT .UNINDENT .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j$(grep \(aq^processor\(aq /proc/cpuinfo | wc \-l) .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS CentOS .sp This section describes how to install Groonga related RPM packages on CentOS. You can install them by \fByum\fP\&. .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS CentOS 5 .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/centos/groonga\-release\-1.1.0\-1.noarch.rpm % sudo yum makecache % sudo yum install \-y groonga .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor Groonga status by Munin, install groonga\-munin\-plugins package. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga\-munin\-plugins package requires munin\-node package that isn\(aqt included in the official CentOS repository. You need to enable \fI\%Repoforge (RPMforge)\fP repository or \fI\%EPEL\fP repository to install it by \fByum\fP\&. .sp Enable Repoforge (RPMforge) repository on i386 environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.3\-1.el5.rf.i386.rpm % sudo rpm \-ivh rpmforge\-release\-0.5.2\-2.el5.rf.i386.rpm .ft P .fi .UNINDENT .UNINDENT .sp Enable Repoforge (RPMforge) repository on x86_64 environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.3\-1.el5.rf.x86_64.rpm % sudo rpm \-ivh rpmforge\-release\-0.5.2\-2.el5.rf.x86_64.rpm .ft P .fi .UNINDENT .UNINDENT .sp Enable EPEL repository on any environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://download.fedoraproject.org/pub/epel/5/i386/epel\-release\-5\-4.noarch.rpm % sudo rpm \-ivh epel\-release\-5\-4.noarch.rpm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as Groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS CentOS 6 .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/centos/groonga\-release\-1.1.0\-1.noarch.rpm % sudo yum makecache % sudo yum install \-y groonga .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor Groonga status by Munin, install groonga\-munin\-plugins package. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga\-munin\-plugins package requires munin\-node package that isn\(aqt included in the official CentOS repository. You need to enable \fI\%EPEL\fP repository to install it by \fByum\fP\&. .sp Enable EPEL repository on any environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo rpm \-ivh http://download.fedoraproject.org/pub/epel/6/i386/epel\-release\-6\-8.noarch.rpm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as Groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS CentOS 7 .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/centos/groonga\-release\-1.1.0\-1.noarch.rpm % sudo yum makecache % sudo yum install \-y groonga .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor Groonga status by Munin, install groonga\-munin\-plugins package. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga\-munin\-plugins package requires munin\-node package that isn\(aqt included in the official CentOS repository. You need to enable \fI\%EPEL\fP repository to install it by \fByum\fP\&. .sp Enable EPEL repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y epel\-release .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as Groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS Build from source .sp Install required packages to build Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y wget tar gcc\-c++ make mecab\-devel .ft P .fi .UNINDENT .UNINDENT .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j$(grep \(aq^processor\(aq /proc/cpuinfo | wc \-l) .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS Fedora .sp This section describes how to install Groonga related RPM packages on Fedora. You can install them by \fByum\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since Groonga 3.0.2 release, Groonga related RPM pakcages are in the official Fedora yum repository (Fedora 18). So you can use them instead of the Groonga yum repository now. There is some exceptions to use the Groonga yum repository because mecab dictionaries (mecab\-ipadic or mecab\-jumandic) are provided by the Groonga yum repository. .UNINDENT .UNINDENT .sp We distribute both 32\-bit and 64\-bit packages but we strongly recommend a 64\-bit package for server. You should use a 32\-bit package just only for tests or development. You will encounter an out of memory error with a 32\-bit package even if you just process medium size data. .SS Fedora 20 .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga .ft P .fi .UNINDENT .UNINDENT .sp Note that additional packages such as \fBmecab\-dic\fP and \fBmecab\-jumandic\fP packages require to install \fBgroonga\-release\fP package which provides the Groonga yum repository beforehand: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/fedora/groonga\-release\-1.1.0\-1.noarch.rpm % sudo yum update .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgroonga\fP package is the minimum set of fulltext search engine. If you want to use Groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 groonga\-server\-http (simple HTTP protocol based server package) .IP \(bu 2 groonga\-httpd (nginx and HTTP protocol based server package) .IP \(bu 2 groonga\-server\-gqtp (GQTP protocol based server package) .UNINDENT .sp See \fB/server\fP section about details. .UNINDENT .UNINDENT .sp If you want to use \fI\%MeCab\fP as a tokenizer, install groonga\-tokenizer\-mecab package. .sp Install groonga\-tokenizer\-mecab package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-tokenizer\-mecab .ft P .fi .UNINDENT .UNINDENT .sp Then install MeCab dictionary. (mecab\-ipadic or mecab\-jumandic) .sp Install IPA dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y mecab\-ipadic .ft P .fi .UNINDENT .UNINDENT .sp Or install Juman dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y mecab\-jumandic .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor Groonga status by Munin, install groonga\-munin\-plugins package. .sp Install groonga\-munin\-plugins package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .sp There is a package that provides MySQL compatible normalizer as Groonga plugins. If you want to use that one, install groonga\-normalizer\-mysql package. .sp Install groonga\-normalizer\-mysql package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y install groonga\-normalizer\-mysql .ft P .fi .UNINDENT .UNINDENT .SS Build from source .sp Install required packages to build Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y wget tar gcc\-c++ make mecab\-devel libedit\-devel .ft P .fi .UNINDENT .UNINDENT .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j$(grep \(aq^processor\(aq /proc/cpuinfo | wc \-l) .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS Oracle Solaris .sp This section describes how to install Groonga from source on Oracle Solaris. .SS Oracle Solaris 11 .sp Install required packages to build Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo pkg install gnu\-tar gcc\-45 system/header .ft P .fi .UNINDENT .UNINDENT .sp Download source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % gtar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 .ft P .fi .UNINDENT .UNINDENT .sp Configure with \fBCFLAGS="\-m64" CXXFLAGS="\-m64"\fP variables. They are needed for building 64\-bit version. To build 32\-bit version, just remove those variables. (see \fIsource\-configure\fP about \fBconfigure\fP options): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure CFLAGS="\-m64" CXXFLAGS="\-m64" .ft P .fi .UNINDENT .UNINDENT .sp Build: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make .ft P .fi .UNINDENT .UNINDENT .sp Install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .SS Others .sp This section describes how to install Groonga from source on UNIX like environment. .sp To get more detail about installing Groonga from source on the specific environment, find the document for the specific environment from \fB/install\fP\&. .SS Dependencies .sp Groonga doesn\(aqt require any special libraries but requires some tools for build. .SS Tools .sp Here are required tools: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBwget\fP, \fBcurl\fP or Web browser for downloading source archive .IP \(bu 2 \fBtar\fP and \fBgzip\fP for extracting source archive .IP \(bu 2 shell (many shells such as \fBdash\fP, \fBbash\fP and \fBzsh\fP will work) .IP \(bu 2 C compiler and C++ compiler (\fBgcc\fP and \fBg++\fP are supported but other compilers may work) .IP \(bu 2 \fBmake\fP (GNU make is supported but other make like BSD make will work) .UNINDENT .UNINDENT .UNINDENT .sp You must get them ready. .sp You can use \fI\%CMake\fP instead of shell but this document doesn\(aqt describe about building with CMake. .sp Here are optional tools: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%pkg\-config\fP for detecting libraries .IP \(bu 2 \fI\%sudo\fP for installing built groonga .UNINDENT .UNINDENT .UNINDENT .sp You must get them ready if you want to use optional libraries. .SS Libraries .sp All libraries are optional. Here are optional libraries: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%MeCab\fP for tokenizing full\-text search target document by morphological analysis .IP \(bu 2 \fI\%KyTea\fP for tokenizing full\-text search target document by morphological analysis .IP \(bu 2 \fI\%ZeroMQ\fP for \fB/suggest\fP .IP \(bu 2 \fI\%libevent\fP for \fB/suggest\fP .IP \(bu 2 \fI\%MessagePack\fP for supporting MessagePack output and \fB/suggest\fP .IP \(bu 2 \fI\%libedit\fP for command line editing in \fB/reference/executables/groonga\fP .IP \(bu 2 \fI\%zlib\fP for compressing column value .IP \(bu 2 \fI\%LZO\fP for compressing column value .UNINDENT .UNINDENT .UNINDENT .sp If you want to use those all or some libraries, you need to install them before installing Groonga. .SS Build from source .sp Groonga uses GNU build system. So the following is the simplest build steps: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % wget http://packages.groonga.org/source/groonga/groonga\-4.0.6.tar.gz % tar xvzf groonga\-4.0.6.tar.gz % cd groonga\-4.0.6 % ./configure % make % sudo make install .ft P .fi .UNINDENT .UNINDENT .sp After the above steps, \fB/reference/executables/groonga\fP is found in \fB/usr/local/bin/groonga\fP\&. .sp The default build will work well but you can customize groonga at \fBconfigure\fP step. .sp The following describes details about each step. .SS \fBconfigure\fP .sp First, you need to run \fBconfigure\fP\&. Here are important \fBconfigure\fP options: .SS \fB\-\-prefix=PATH\fP .sp Specifies the install base directory. Groonga related files are installed under \fB${PATH}/\fP directory. .sp The default is \fB/usr/local\fP\&. In this case, \fB/reference/executables/groonga\fP is installed into \fB/usr/local/bin/groonga\fP\&. .sp Here is an example that installs Groonga into \fB~/local\fP for an user use instead of system wide use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-prefix=$HOME/local .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-localstatedir=PATH\fP .sp Specifies the base directory to place modifiable file such as log file, PID file and database files. For example, log file is placed at \fB${PATH}/log/groonga.log\fP\&. .sp The default is \fB/usr/local/var\fP\&. .sp Here is an example that system wide \fB/var\fP is used for modifiable files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-localstatedir=/var .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-log\-path=PATH\fP .sp Specifies the default log file path. You can override the default log path is \fB/reference/executables/groonga\fP command\(aqs \fB\-\-log\-path\fP command line option. So this option is not critical build option. It\(aqs just for convenient. .sp The default is \fB/usr/local/var/log/groonga.log\fP\&. The \fB/usr/local/var\fP part is changed by \fB\-\-localstatedir\fP option. .sp Here is an example that log file is placed into shared NFS directory \fB/nfs/log/groonga.log\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-log\-path=/nfs/log/groonga.log .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-default\-encoding=ENCODING\fP .sp Specifies the default encoding. Available encodings are \fBeuc_jp\fP, \fBsjis\fP, \fButf8\fP, \fBlatin1\fP, \fBkoi8r\fP and \fBnone\fP\&. .sp The default is \fButf\-8\fP\&. .sp Here is an example that Shift_JIS is used as the default encoding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-default\-encoding=sjis .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-match\-escalation\-threshold=NUMBER\fP .sp Specifies the default match escalation threshold. See \fImatch\-escalation\-threshold\fP about match escalation threshold. \-1 means that match operation never escalate. .sp The default is 0. .sp Here is an example that match escalation isn\(aqt used by default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-match\-escalation\-threshold=\-1 .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-zlib\fP .sp Enables column value compression by zlib. .sp The default is disabled. .sp Here is an example that enables column value compression by zlib: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-zlib .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The disabled reason is that memory leak occurs when it refers column value. This is already known issue as \fI\%GitHub#6\fP\&. This issue is not nothing to do with updating column value. .UNINDENT .UNINDENT .SS \fB\-\-with\-lzo\fP .sp Enables column value compression by LZO. .sp The default is disabled. .sp Here is an example that enables column value compression by LZO: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-lzo .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The disabled reason is that memory leak occurs when it refers column value. This is already known issue as \fI\%GitHub#6\fP\&. This issue is not nothing to do with updating column value. .UNINDENT .UNINDENT .SS \fB\-\-with\-message\-pack=MESSAGE_PACK_INSTALL_PREFIX\fP .sp Specifies where MessagePack is installed. If MessagePack isn\(aqt installed with \fB\-\-prefix=/usr\fP, you need to specify this option with path that you use for building MessagePack. .sp If you installed MessagePack with \fB\-\-prefix=$HOME/local\fP option, you sholud specify \fB\-\-with\-message\-pack=$HOME/local\fP to groonga\(aqs \fBconfigure\fP\&. .sp The default is \fB/usr\fP\&. .sp Here is an example that uses MessagePack built with \fB\-\-prefix=$HOME/local\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-message\-pack=$HOME/local .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-munin\-plugins\fP .sp Installs Munin plugins for Groonga. They are installed into \fB${PREFIX}/share/groonga/munin/plugins/\fP\&. .sp Those plugins are not installed by default. .sp Here is an example that installs Munin plugins for Groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-munin\-plugins .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-with\-package\-platform=PLATFORM\fP .sp Installs platform specific system management files such as init script. Available platforms are \fBredhat\fP and \fBfedora\fP\&. \fBredhat\fP is for Red Hat and Red Hat clone distributions such as CentOS. \fBfedora\fP is for Fedora. .sp Those system management files are not installed by default. .sp Here is an example that installs CentOS specific system management files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-package\-platform=redhat .ft P .fi .UNINDENT .UNINDENT .SS \fB\-\-help\fP .sp Shows all \fBconfigure\fP options. .SS \fBmake\fP .sp \fBconfigure\fP is succeeded, you can build groonga by \fBmake\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make .ft P .fi .UNINDENT .UNINDENT .sp If you have multi cores CPU, you can make faster by using \fB\-j\fP option. If you have 4 cores CPU, it\(aqs good for using \fB\-j4\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-j4 .ft P .fi .UNINDENT .UNINDENT .sp If you get some errors by \fBmake\fP, please report them to us: \fB/contribution/report\fP .SS \fBmake install\fP .sp Now, you can install built Groonga!: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo make install .ft P .fi .UNINDENT .UNINDENT .sp If you have write permission for \fB${PREFIX}\fP, you don\(aqt need to use \fBsudo\fP\&. e.g. \fB\-\-prefix=$HOME/local\fP case. In this case, use \fBmake install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make install .ft P .fi .UNINDENT .UNINDENT .SH COMMUNITY .sp There are some places for sharing Groonga information. We welcome you to join our community. .SS Mailing List .sp There are mailing lists for discussion about Groonga. .INDENT 0.0 .TP .B For English speakers \fI\%groonga\-talk@lists.sourceforge.net\fP .TP .B For Japanese speakers \fI\%groonga\-dev@lists.sourceforge.jp\fP .UNINDENT .SS Twitter .sp \fI\%@groonga\fP tweets Groonga related information. .sp Please follow the account to get the latest Groonga related information! .SS Facebook .sp \fI\%Groonga page on Facebook\fP shares Groonga related information. .sp Please like the page to get the latest Groonga related information! .SH TUTORIAL .SS Basic operations .sp A Groonga package provides a C library (libgroonga) and a command line tool (groonga). This tutorial explains how to use the command line tool, with which you can create/operate databases, start a server, establish a connection with a server, etc. .SS Create a database .sp The first step to using Groonga is to create a new database. The following shows how to do it. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga \-n DB_PATH .ft P .fi .UNINDENT .UNINDENT .sp The \fI\-n\fP option specifies to create a new database and DB_PATH specifies the path of the new database. Actually, a database consists of a series of files and DB_PATH specifies the file which will be the entrance to the new database. DB_PATH also specifies the path prefix for other files. Note that database creation fails if DB_PATH points to an existing file. .sp This command creates a new database and then enters into interactive mode in which Groonga prompts you to enter commands for operating that database. You can terminate this mode with Ctrl\-d. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-n /tmp/groonga\-databases/introduction.db .ft P .fi .UNINDENT .UNINDENT .sp After this database creation, you can find a series of files in /tmp/groonga\-databases. .SS Operate a database .sp The following shows how to operate an existing database. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga DB_PATH [COMMAND] .ft P .fi .UNINDENT .UNINDENT .sp DB_PATH specifies the path of a target database. This command fails if the specified database does not exist. .sp If COMMAND is specified, Groonga executes COMMAND and returns the result. Otherwise, Groonga starts in interactive mode that reads commands from the standard input and executes them one by one. This tutorial focuses on the interactive mode. .sp Let\(aqs see the status of a Groonga process by using a \fB/reference/commands/status\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga /tmp/groonga\-databases/introduction.db status # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "uptime": 0, # "max_command_version": 2, # "n_queries": 0, # "cache_hit_rate": 0.0, # "version": "4.0.1", # "alloc_count": 161, # "command_version": 1, # "starttime": 1395806057, # "default_command_version": 1 # } # ] .ft P .fi .UNINDENT .UNINDENT .sp As shown in the above example, a command returns a JSON array. The first element contains an error code, execution time, etc. The second element is the result of an operation. .SS Command format .sp Commands for operating a database accept arguments as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Form_1: COMMAND VALUE_1 VALUE_2 .. Form_2: COMMAND \-\-NAME_1 VALUE_1 \-\-NAME_2 VALUE_2 .. .ft P .fi .UNINDENT .UNINDENT .sp In the first form, arguments must be passed in order. This kind of arguments are called positional arguments because the position of each argument determines its meaning. .sp In the second form, you can specify a parameter name with its value. So, the order of arguments is not defined. This kind of arguments are known as named parameters or keyword arguments. .sp If you want to specify a value which contains white\-spaces or special characters, such as quotes and parentheses, please enclose the value with single\-quotes or double\-quotes. .sp For details, see also the paragraph of "command" in \fB/reference/executables/groonga\fP\&. .SS Basic commands .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB/reference/commands/status\fP shows status of a Groonga process. .TP .B \fB/reference/commands/table_list\fP shows a list of tables in a database. .TP .B \fB/reference/commands/column_list\fP shows a list of columns in a table. .TP .B \fB/reference/commands/table_create\fP adds a table to a database. .TP .B \fB/reference/commands/column_create\fP adds a column to a table. .TP .B \fB/reference/commands/select\fP searches records from a table and shows the result. .TP .B \fB/reference/commands/load\fP inserts records to a table. .UNINDENT .UNINDENT .UNINDENT .SS Create a table .sp A \fB/reference/commands/table_create\fP command creates a new table. .sp In most cases, a table has a primary key which must be specified with its data type and index type. .sp There are various data types such as integers, strings, etc. See also \fB/reference/types\fP for more details. The index type determines the search performance and the availability of prefix searches. The details will be described later. .sp Let\(aqs create a table. The following example creates a table with a primary key. The \fIname\fP parameter specifies the name of the table. The \fIflags\fP parameter specifies the index type for the primary key. The \fIkey_type\fP parameter specifies the data type of the primary key. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Site \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The second element of the result indicates that the operation succeeded. .SS View a table .sp A \fB/reference/commands/select\fP command can enumerate records in a table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 0 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp When only a table name is specified with a \fItable\fP parameter, a \fB/reference/commands/select\fP command returns the first (at most) 10 records in the table. [0] in the result shows the number of records in the table. The next array is a list of columns. ["_id","Uint32"] is a column of UInt32, named _id. ["_key","ShortText"] is a column of ShortText, named _key. .sp The above two columns, _id and _key, are the necessary columns. The _id column stores IDs those are automatically allocated by Groonga. The _key column is associated with the primary key. You are not allowed to rename these columns. .SS Create a column .sp A \fB/reference/commands/column_create\fP command creates a new column. .sp Let\(aqs add a column. The following example adds a column to the Site table. The \fItable\fP parameter specifies the target table. The \fIname\fP parameter specifies the name of the column. The \fItype\fP parameter specifies the data type of the column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table Site \-\-name title \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] select \-\-table Site # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 0 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Load records .sp A \fB/reference/commands/load\fP command loads JSON\-formatted records into a table. .sp The following example loads nine records into the Site table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Site [ {"_key":"http://example.org/","title":"This is test record 1!"}, {"_key":"http://example.net/","title":"test record 2."}, {"_key":"http://example.com/","title":"test test record three."}, {"_key":"http://example.net/afr","title":"test record four."}, {"_key":"http://example.org/aba","title":"test test test record five."}, {"_key":"http://example.com/rab","title":"test test test test record six."}, {"_key":"http://example.net/atv","title":"test test test record seven."}, {"_key":"http://example.org/gat","title":"test test record eight."}, {"_key":"http://example.com/vdw","title":"test test record nine."}, ] # [[0, 1337566253.89858, 0.000355720520019531], 9] .ft P .fi .UNINDENT .UNINDENT .sp The second element of the result indicates how many records were successfully loaded. In this case, all the records are successfully loaded. .sp Let\(aqs make sure that these records are correctly stored. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ], # [ # 2, # "http://example.net/", # "test record 2." # ], # [ # 3, # "http://example.com/", # "test test record three." # ], # [ # 4, # "http://example.net/afr", # "test record four." # ], # [ # 5, # "http://example.org/aba", # "test test test record five." # ], # [ # 6, # "http://example.com/rab", # "test test test test record six." # ], # [ # 7, # "http://example.net/atv", # "test test test record seven." # ], # [ # 8, # "http://example.org/gat", # "test test record eight." # ], # [ # 9, # "http://example.com/vdw", # "test test record nine." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Get a record .sp A \fB/reference/commands/select\fP command can search records in a table. .sp If a search condition is specified with a \fIquery\fP parameter, a \fB/reference/commands/select\fP command searches records matching the search condition and returns the matched records. .sp Let\(aqs get a record having a specified record ID. The following example gets the first record in the Site table. More precisely, the \fIquery\fP parameter specifies a record whose _id column stores 1. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query _id:1 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Next, let\(aqs get a record having a specified key. The following example gets the record whose primary key is "\fI\%http://example.org/\fP". More precisely, the \fIquery\fP parameter specifies a record whose _key column stores "\fI\%http://example.org/\fP". .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query \(aq_key:"http://example.org/"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Create a lexicon table for full text search .sp Let\(aqs go on to how to make full text search. .sp Groonga uses an inverted index to provide fast full text search. So, the first step is to create a lexicon table which stores an inverted index, also known as postings lists. The primary key of this table is associated with a vocabulary made up of index terms and each record stores postings lists for one index term. .sp The following shows a command which creates a lexicon table named Terms. The data type of its primary key is ShortText. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Terms \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fB/reference/commands/table_create\fP command takes many parameters but you don\(aqt need to understand all of them. Please skip the next paragraph if you are not interested in how it works. .sp The TABLE_PAT_KEY flag specifies to store index terms in a patricia trie. The KEY_NORMALIZE flag specifies to normalize index terms. In this example, both flags are validated by using a \(aq|\(aq. The \fIdefault_tokenizer\fP parameter specifies the method for tokenizing text. This example uses TokenBigram that is generally called N\-gram. .SS Create an index column for full text search .sp The second step is to create an index column, which allows you to search records from its associated column. That is to say this step specifies which column needs an index. .sp Let\(aqs create an index column. The following example creates an index column for a column in the Site table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table Terms \-\-name blog_title \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Site \-\-source title # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fItable\fP parameter specifies the index table and the \fIname\fP parameter specifies the index column. The \fItype\fP parameter specifies the target table and the \fIsource\fP parameter specifies the target column. The COLUMN_INDEX flag specifies to create an index column and the WITH_POSITION flag specifies to create a full inverted index, which contains the positions of each index term. This combination, COLUMN_INDEX|WITH_POSITION, is recommended for the general purpose. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can create a lexicon table and index columns before/during/after loading records. If a target column already has records, Groonga creates an inverted index in a static manner. In contrast, if you load records into an already indexed column, Groonga updates the inverted index in a dynamic manner. .UNINDENT .UNINDENT .SS Full text search .sp It\(aqs time. You can make full text search with a \fB/reference/commands/select\fP command. .sp A query for full text search is specified with a \fIquery\fP parameter. The following example searches records whose "title" column contains "this". The \(aq@\(aq specifies to make full text search. Note that a lower case query matches upper case and capitalized terms in a record if KEY_NORMALIZE was specified when creating a lexcon table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query title:@this # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp In this example, the first record matches the query because its title contains "This", that is the capitalized form of the query. .sp A \fB/reference/commands/select\fP command accepts an optional parameter, named \fImatch_columns\fP, that specifies the default target columns. This parameter is used if target columns are not specified in a query. [1] .sp The combination of "\fI\-\-match_columns\fP title" and "\fI\-\-query\fP this" brings you the same result that "\fI\-\-query\fP title:@this" does. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-match_columns title \-\-query this # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Specify output columns .sp An \fIoutput_columns\fP parameter of a \fB/reference/commands/select\fP command specifies columns to appear in the search result. If you want to specify more than one columns, please separate column names by commas (\(aq,\(aq). .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-output_columns _key,title,_score \-\-query title:@test # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "http://example.org/", # "This is test record 1!", # 1 # ], # [ # "http://example.net/", # "test record 2.", # 1 # ], # [ # "http://example.com/", # "test test record three.", # 2 # ], # [ # "http://example.net/afr", # "test record four.", # 1 # ], # [ # "http://example.org/aba", # "test test test record five.", # 3 # ], # [ # "http://example.com/rab", # "test test test test record six.", # 4 # ], # [ # "http://example.net/atv", # "test test test record seven.", # 3 # ], # [ # "http://example.org/gat", # "test test record eight.", # 2 # ], # [ # "http://example.com/vdw", # "test test record nine.", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This example specifies three output columns including the _score column, which stores the relevance score of each record. .SS Specify output ranges .sp A \fB/reference/commands/select\fP command returns a part of its search result if \fIoffset\fP and/or \fIlimit\fP parameters are specified. These parameters are useful to paginate a search result, a widely\-used interface which shows a search result on a page by page basis. .sp An \fIoffset\fP parameter specifies the starting point and a \fIlimit\fP parameter specifies the maximum number of records to be returned. If you need the first record in a search result, the offset parameter must be 0 or omitted. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-offset 0 \-\-limit 3 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ], # [ # 2, # "http://example.net/", # "test record 2." # ], # [ # 3, # "http://example.com/", # "test test record three." # ] # ] # ] # ] select \-\-table Site \-\-offset 3 \-\-limit 3 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 4, # "http://example.net/afr", # "test record four." # ], # [ # 5, # "http://example.org/aba", # "test test test record five." # ], # [ # 6, # "http://example.com/rab", # "test test test test record six." # ] # ] # ] # ] select \-\-table Site \-\-offset 7 \-\-limit 3 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 8, # "http://example.org/gat", # "test test record eight." # ], # [ # 9, # "http://example.com/vdw", # "test test record nine." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Sort a search result .sp A \fB/reference/commands/select\fP command sorts its result when used with a \fIsortby\fP parameter. .sp A \fIsortby\fP parameter specifies a column as a sorting creteria. A search result is arranged in ascending order of the column values. If you want to sort a search result in reverse order, please add a leading hyphen (\(aq\-\(aq) to the column name in a parameter. .sp The following example shows records in the Site table in reverse order. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-sortby \-_id # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 9, # "http://example.com/vdw", # "test test record nine." # ], # [ # 8, # "http://example.org/gat", # "test test record eight." # ], # [ # 7, # "http://example.net/atv", # "test test test record seven." # ], # [ # 6, # "http://example.com/rab", # "test test test test record six." # ], # [ # 5, # "http://example.org/aba", # "test test test record five." # ], # [ # 4, # "http://example.net/afr", # "test record four." # ], # [ # 3, # "http://example.com/", # "test test record three." # ], # [ # 2, # "http://example.net/", # "test record 2." # ], # [ # 1, # "http://example.org/", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The next example uses the _score column as the sorting criteria for ranking the search result. The result is sorted in relevance order. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query title:@test \-\-output_columns _id,_score,title \-\-sortby \-_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_score", # "Int32" # ], # [ # "title", # "ShortText" # ] # ], # [ # 6, # 4, # "test test test test record six." # ], # [ # 5, # 3, # "test test test record five." # ], # [ # 7, # 3, # "test test test record seven." # ], # [ # 8, # 2, # "test test record eight." # ], # [ # 3, # 2, # "test test record three." # ], # [ # 9, # 2, # "test test record nine." # ], # [ # 1, # 1, # "This is test record 1!" # ], # [ # 4, # 1, # "test record four." # ], # [ # 2, # 1, # "test record 2." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp If you want to specify more than one columns, please separate column names by commas (\(aq,\(aq). In such a case, a search result is sorted in order of the values in the first column, and then records having the same values in the first column are sorted in order of the second column values. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query title:@test \-\-output_columns _id,_score,title \-\-sortby \-_score,_id # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_score", # "Int32" # ], # [ # "title", # "ShortText" # ] # ], # [ # 6, # 4, # "test test test test record six." # ], # [ # 5, # 3, # "test test test record five." # ], # [ # 7, # 3, # "test test test record seven." # ], # [ # 3, # 2, # "test test record three." # ], # [ # 8, # 2, # "test test record eight." # ], # [ # 9, # 2, # "test test record nine." # ], # [ # 1, # 1, # "This is test record 1!" # ], # [ # 2, # 1, # "test record 2." # ], # [ # 4, # 1, # "test record four." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT footnote .IP [1] 5 Currently, a \fImatch_columns\fP parameter is available iff there exists an inverted index for full text search. A \fImatch_columns\fP parameter for a regular column is not supported. .SS Remote access .sp You can use Groonga as a server which allows remote access. Groonga supports the original protocol (GQTP), the memcached binary protocol and HTTP. .SS Groonga Query Transfer Protocol (GQTP) .SS How to run a GQTP server .sp Groonga has a special protocol, named Groonga Query Transfer Protocol (GQTP), for remote access to a database. The following form shows how to run Groonga as a GQTP server. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [\-p PORT_NUMBER] \-s DB_PATH .ft P .fi .UNINDENT .UNINDENT .sp The \fI\-s\fP option specifies to run Groonga as a server. DB_PATH specifies the path of the existing database to be hosted. The \fI\-p\fP option and its argument, PORT_NUMBER, specify the port number of the server. The default port number is 10043, which is used when you don\(aqt specify PORT_NUMBER. .sp The following command runs a server that listens on the default port number. The server accepts operations to the specified database. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-s /tmp/groonga\-databases/introduction.db Ctrl\-c % .ft P .fi .UNINDENT .UNINDENT .SS How to run a GQTP daemon .sp You can also run a GQTP server as a daemon by using the \fI\-d\fP option, instead of the \fI\-s\fP option. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [\-p PORT_NUMBER] \-d DB_PATH .ft P .fi .UNINDENT .UNINDENT .sp A Groonga daemon prints its process ID as follows. In this example, the process ID is 12345. Then, the daemon opens a specified database and accepts operations to that database. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-d /tmp/groonga\-databases/introduction.db 12345 % .ft P .fi .UNINDENT .UNINDENT .SS How to run a GQTP client .sp You can run Groonga as a GQTP client as follows: .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [\-p PORT_NUMBER] \-c [HOST_NAME_OR_IP_ADDRESS] .ft P .fi .UNINDENT .UNINDENT .sp This command establishes a connection with a GQTP server and then enters into interactive mode. HOST_NAME_OR_IP_ADDRESS specifies the hostname or the IP address of the server. If not specified, Groonga uses the default hostname "localhost". The \fI\-p\fP option and its argument, PORT_NUMBER, specify the port number of the server. If not specified, Groonga uses the default port number 10043. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-c status # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "uptime": 0, # "max_command_version": 2, # "n_queries": 0, # "cache_hit_rate": 0.0, # "version": "4.0.1", # "alloc_count": 140, # "command_version": 1, # "starttime": 1395806078, # "default_command_version": 1 # } # ] > ctrl\-d % .ft P .fi .UNINDENT .UNINDENT .sp In interactive mode, Groonga reads commands from the standard input and executes them one by one. .SS How to terminate a GQTP server .sp You can terminate a GQTP server with a \fB/reference/commands/shutdown\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-c > shutdown % .ft P .fi .UNINDENT .UNINDENT .SS Memcached binary protocol .sp Groonga supports the memcached binary protocol. The following form shows how to run Groonga as a memcached binary protocol server daemon. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [\-p PORT_NUMBER] \-d \-\-protocol memcached DB_PATH .ft P .fi .UNINDENT .UNINDENT .sp The \fI\-\-protocol\fP option and its argument specify the protocol of the server. "memcached" specifies to use the memcached binary protocol. .SS Hypertext transfer protocol (HTTP) .SS How to run an HTTP server .sp Groonga supports the hypertext transfer protocol (HTTP). The following form shows how to run Groonga as an HTTP server daemon. .sp Form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [\-p PORT_NUMBER] \-d \-\-protocol http DB_PATH .ft P .fi .UNINDENT .UNINDENT .sp The \fI\-\-protocol\fP option and its argument specify the protocol of the server. "http" specifies to use HTTP. If the \fI\-p\fP option is not specified, Groonga uses the default port number 10041. .sp The following command runs an HTTP server that listens on the port number 80. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo groonga \-p 80 \-d \-\-protocol http /tmp/groonga\-databases/introduction.db % .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You must have root privileges if you listen on the port number 80 (well known port). There is no such a limitation about the port number 1024 or over. .UNINDENT .UNINDENT .SS How to send a command to an HTTP server .sp You can send a command to an HTTP server by sending a GET request to /d/COMMAND_NAME. Command parameters can be passed as parameters of the GET request. The format is "?NAME_1=VALUE_1&NAME_2=VALUE_2&...". .sp The following example shows how to send commands to an HTTP server. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/d/status Executed command: status # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "uptime": 1, # "max_command_version": 2, # "n_queries": 0, # "cache_hit_rate": 0.0, # "version": "4.0.1", # "alloc_count": 141, # "command_version": 1, # "starttime": 1395806078, # "default_command_version": 1 # } # ] http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/d/select?table=Site&query=title:@this Executed command: select \-\-table Site \-\-query title:@this # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "http://example.org/", # "japan", # ".org", # "http://example.net/", # [ # "http://example.net/", # "http://example.org/", # "http://example.com/" # ], # "128452975x503157902", # "This is test record 1!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Administration tool (HTTP) .sp An HTTP server of Groonga provides a browser based administration tool that makes database management easy. After starting an HTTP server, you can use the administration tool by accessing \fI\%http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/\fP\&. Note that Javascript must be enabled for the tool to work properly. .SS Security issues .sp Groonga servers don\(aqt support user authentication. Everyone can view and modify databases hosted by Groonga servers. You are recommended to restrict IP addresses that can access Groonga servers. You can use iptables or similar for this purpose. .SS Various data types .sp Groonga is a full text search engine but also serves as a column\-oriented data store. Groonga supports various data types, such as numeric types, string types, date and time type, longitude and latitude types, etc. This tutorial shows a list of data types and explains how to use them. .SS Overview .sp The basic data types of Groonga are roughly divided into 5 groups \-\-\- boolean type, numeric types, string types, date/time type and longitude/latitude types. The numeric types are further divided according to whether integer or floating point number, signed or unsigned and the number of bits allocated to each integer. The string types are further divided according to the maximum length. The longitude/latitude types are further divided according to the geographic coordinate system. For more details, see \fB/reference/types\fP\&. .sp In addition, Groonga supports reference types and vector types. Reference types are designed for accessing other tables. Vector types are designed for storing a variable number of values in one element. .sp First, let\(aqs create a table for this tutorial. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name ToyBox \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .SS Boolean type .sp The boolean type is used to store true or false. To create a boolean type column, specify Bool to the \fItype\fP parameter of \fB/reference/commands/column_create\fP command. The default value of the boolean type is false. .sp The following example creates a boolean type column and adds three records. Note that the third record has the default value because no value is specified. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table ToyBox \-\-name is_animal \-\-type Bool # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table ToyBox [ {"_key":"Monkey","is_animal":true} {"_key":"Flower","is_animal":false} {"_key":"Block"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] select \-\-table ToyBox \-\-output_columns _key,is_animal # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "is_animal", # "Bool" # ] # ], # [ # "Monkey", # true # ], # [ # "Flower", # false # ], # [ # "Block", # false # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Numeric types .sp The numeric types are divided into integer types and a floating point number type. The integer types are further divided into the signed integer types and unsigned integer types. In addition, you can choose the number of bits allocated to each integer. For more details, see \fB/reference/types\fP\&. The default value of the numeric types is 0. .sp The following example creates an Int8 column and a Float column, and then updates existing records. The \fB/reference/commands/load\fP command updates the weight column as expected. On the other hand, the price column values are different from the specified values because 15.9 is not an integer and 200 is too large. 15.9 is converted to 15 by removing the fractional part. 200 causes an overflow and the result becomes \-56. Note that the result of an overflow/underflow is undefined. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table ToyBox \-\-name price \-\-type Int8 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table ToyBox \-\-name weight \-\-type Float # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table ToyBox [ {"_key":"Monkey","price":15.9} {"_key":"Flower","price":200,"weight":0.13} {"_key":"Block","weight":25.7} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] select \-\-table ToyBox \-\-output_columns _key,price,weight # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "price", # "Int8" # ], # [ # "weight", # "Float" # ] # ], # [ # "Monkey", # 15, # 0.0 # ], # [ # "Flower", # \-56, # 0.13 # ], # [ # "Block", # 0, # 25.7 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS String types .sp The string types are divided according to the maximum length. For more details, see \fB/reference/types\fP\&. The default value is the zero\-length string. .sp The following example creates a ShortText column and updates existing records. The third record has the default value because not updated. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table ToyBox \-\-name name \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table ToyBox [ {"_key":"Monkey","name":"Grease"} {"_key":"Flower","name":"Rose"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] select \-\-table ToyBox \-\-output_columns _key,name # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "name", # "ShortText" # ] # ], # [ # "Monkey", # "Grease" # ], # [ # "Flower", # "Rose" # ], # [ # "Block", # "" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Date and time type .sp The date and time type of Groonga is Time. Actually, a Time column stores a date and time as the number of microseconds since the Epoch, 1970\-01\-01 00:00:00. A Time value can represent a date and time before the Epoch because the actual data type is a signed integer. Note that \fB/reference/commands/load\fP and \fB/reference/commands/select\fP commands use a decimal number to represent a data and time in seconds. The default value is 0.0, which means the Epoch. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga internally holds the value of Epoch as pair of integer. The first integer represents the value of seconds, on the other hand, the second integer represents the value of micro seconds. So, Groonga shows the value of Epoch as floating point. Integral part means the value of seconds, fraction part means the value of micro seconds. .UNINDENT .UNINDENT .sp The following example creates a Time column and updates existing records. The first record has the default value because not updated. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table ToyBox \-\-name time \-\-type Time # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table ToyBox [ {"_key":"Flower","time":1234567890.1234569999} {"_key":"Block","time":\-1234567890} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] select \-\-table ToyBox \-\-output_columns _key,time # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "time", # "Time" # ] # ], # [ # "Monkey", # 0.0 # ], # [ # "Flower", # 1234567890.12346 # ], # [ # "Block", # \-1234567890.0 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Longitude and latitude types .sp The longitude and latitude types are divided according to the geographic coordinate system. For more details, see \fB/reference/types\fP\&. To represent a longitude and latitude, Groonga uses a string formatted as follows: .INDENT 0.0 .IP \(bu 2 "longitude x latitude" in milliseconds (e.g.: "128452975x503157902") .IP \(bu 2 "longitude x latitude" in degrees (e.g.: "35.6813819x139.7660839") .UNINDENT .sp A number with/without a decimal point represents a longitude or latitude in milliseconds/degrees respectively. Note that a combination of a number with a decimal point and a number without a decimal point (e.g. 35.1x139) must not be used. A comma (\(aq,\(aq) is also available as a delimiter. The default value is "0x0". .sp The following example creates a WGS84GeoPoint column and updates existing records. The second record has the default value because not updated. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table ToyBox \-\-name location \-\-type WGS84GeoPoint # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table ToyBox [ {"_key":"Monkey","location":"128452975x503157902"} {"_key":"Block","location":"35.6813819x139.7660839"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] select \-\-table ToyBox \-\-output_columns _key,location # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ] # ], # [ # "Monkey", # "128452975x503157902" # ], # [ # "Flower", # "0x0" # ], # [ # "Block", # "128452975x503157902" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Reference types .sp Groonga supports a reference column, which stores references to records in its associated table. In practice, a reference column stores the IDs of the referred records in the associated table and enables access to those records. .sp You can specify a column in the associated table to the \fIoutput_columns\fP parameter of a \fB/reference/commands/select\fP command. The format is "Src.Dest" where Src is the name of the reference column and Dest is the name of the target column. If only the reference column is specified, it is handled as "Src._key". Note that if a reference does not point to a valid record, a \fB/reference/commands/select\fP command outputs the default value of the target column. .sp The following example adds a reference column to the Site table that was created in the previous tutorial. The new column, named link, is designed for storing links among records in the Site table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table Site \-\-name link \-\-type Site # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Site [{"_key":"http://example.org/","link":"http://example.net/"}] select \-\-table Site \-\-output_columns _key,title,link._key,link.title \-\-query title:@this # [[0, 1337566253.89858, 0.000355720520019531], 1] # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ], # [ # "link._key", # "ShortText" # ], # [ # "link.title", # "ShortText" # ] # ], # [ # "http://example.org/", # "This is test record 1!", # "http://example.net/", # "test record 2." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fItype\fP parameter of the \fB/reference/commands/column_create\fP command specifies the table to be associated with the reference column. In this example, the reference column is associated with the own table. Then, the \fB/reference/commands/load\fP command registers a link from "\fI\%http://example.org\fP" to "\fI\%http://example.net\fP". Note that a reference column requires the primary key, not the ID, of the record to be referred to. After that, the link is confirmed by the \fB/reference/commands/select\fP command. In this case, the primary key and the title of the referred record are output because link._key and link.title are specified to the \fIoutput_columns\fP parameter. .SS Vector types .sp Groonga supports a vector column, in which each element can store a variable number of values. To create a vector column, specify the COLUMN_VECTOR flag to the \fIflags\fP parameter of a \fB/reference/commands/column_create\fP command. A vector column is useful to represent a many\-to\-many relationship. .sp The previous example used a regular column, so each record could have at most one link. Obviously, the specification is insufficient because a site usually has more than one links. To solve this problem, the following example uses a vector column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table Site \-\-name links \-\-flags COLUMN_VECTOR \-\-type Site # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Site [{"_key":"http://example.org/","links":["http://example.net/","http://example.org/","http://example.com/"]}] select \-\-table Site \-\-output_columns _key,title,links._key,links.title \-\-query title:@this # [[0, 1337566253.89858, 0.000355720520019531], 1] # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "title", # "ShortText" # ], # [ # "links._key", # "ShortText" # ], # [ # "links.title", # "ShortText" # ] # ], # [ # "http://example.org/", # "This is test record 1!", # [ # "http://example.net/", # "http://example.org/", # "http://example.com/" # ], # [ # "test record 2.", # "This is test record 1!", # "test test record three." # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The only difference at the first step is the \fIflags\fP parameter that specifies to create a vector column. The \fItype\fP parameter of the \fB/reference/commands/column_create\fP command is the same as in the previous example. Then, the \fB/reference/commands/load\fP command registers three links from "\fI\%http://example.org/\fP" to "\fI\%http://example.net/\fP", "\fI\%http://example.org/\fP" and "\fI\%http://example.com/\fP". After that, the links are confirmed by the \fB/reference/commands/select\fP command. In this case, the primary keys and the titles are output as arrays because links._key and links.title are specified to the \fIoutput_columns\fP parameter. .SS Various search conditions .sp Groonga supports to narrow down by using syntax like JavaScript, sort by the calculated value. Additionally, Groonga also supports to narrow down & sort search results by using location information (latitude & longitude). .SS Narrow down & Full\-text search by using syntax like JavaScript .sp The \fBfilter\fP parameter of \fBselect\fP command accepts the search condition. There is one difference between \fBfilter\fP parameter and \fBquery\fP parameter, you need to specify the condition by syntax like JavaScript for \fBfilter\fP parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-filter "_id <= 1" \-\-output_columns _id,_key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 1, # "http://example.org/" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp See the detail of above query. Here is the condition which is specified as \fBfilter\fP parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C _id <= 1 .ft P .fi .UNINDENT .UNINDENT .sp In this case, this query returns the records which meets the condition that the value of \fB_id\fP is equal to 1. .sp Moreover, you can use \fB&&\fP for AND search, \fB||\fP for OR search. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-filter "_id >= 4 && _id <= 6" \-\-output_columns _id,_key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 4, # "http://example.net/afr" # ], # [ # 5, # "http://example.org/aba" # ], # [ # 6, # "http://example.com/rab" # ] # ] # ] # ] select \-\-table Site \-\-filter "_id <= 2 || _id >= 7" \-\-output_columns _id,_key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 1, # "http://example.org/" # ], # [ # 2, # "http://example.net/" # ], # [ # 7, # "http://example.net/atv" # ], # [ # 8, # "http://example.org/gat" # ], # [ # 9, # "http://example.com/vdw" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp If you specify \fBquery\fP parameter and \fBfilter\fP parameter at the same time, you can get the records which meets both of the condition as a result. .SS Sort by using \fBscorer\fP .sp \fBselect\fP command accepts \fBscorer\fP parameter which is used to process each record of full\-text search results. .sp This parameter accepts the conditions which is specified by syntax like JavaScript as same as \fBfilter\fP parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-filter "true" \-\-scorer "_score = rand()" \-\-output_columns _id,_key,_score \-\-sortby _score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # 6, # "http://example.com/rab", # 424238335 # ], # [ # 9, # "http://example.com/vdw", # 596516649 # ], # [ # 7, # "http://example.net/atv", # 719885386 # ], # [ # 2, # "http://example.net/", # 846930886 # ], # [ # 8, # "http://example.org/gat", # 1649760492 # ], # [ # 3, # "http://example.com/", # 1681692777 # ], # [ # 4, # "http://example.net/afr", # 1714636915 # ], # [ # 1, # "http://example.org/", # 1804289383 # ], # [ # 5, # "http://example.org/aba", # 1957747793 # ] # ] # ] # ] select \-\-table Site \-\-filter "true" \-\-scorer "_score = rand()" \-\-output_columns _id,_key,_score \-\-sortby _score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # 4, # "http://example.net/afr", # 783368690 # ], # [ # 2, # "http://example.net/", # 1025202362 # ], # [ # 5, # "http://example.org/aba", # 1102520059 # ], # [ # 1, # "http://example.org/", # 1189641421 # ], # [ # 3, # "http://example.com/", # 1350490027 # ], # [ # 8, # "http://example.org/gat", # 1365180540 # ], # [ # 9, # "http://example.com/vdw", # 1540383426 # ], # [ # 7, # "http://example.net/atv", # 1967513926 # ], # [ # 6, # "http://example.com/rab", # 2044897763 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \(aq_score\(aq is one of a pseudo column. The score of full\-text search is assigned to it. See \fB/reference/columns/pseudo\fP about \(aq_score\(aq column. .sp In the above query, the condition of \fBscorer\fP parameter is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C _score = rand() .ft P .fi .UNINDENT .UNINDENT .sp In this case, the score of full\-text search is overwritten by the value of rand() function. .sp The condition of \fBsortby\fP parameter is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C _score .ft P .fi .UNINDENT .UNINDENT .sp This means that sorting the search result by ascending order. .sp As a result, the order of search result is randomized. .SS Narrow down & sort by using location information .sp Groonga supports to store location information (Longitude & Latitude) and not only narrow down but also sort by using it. .sp Groonga supports two kind of column types to store location information. One is \fBTokyoGeoPoint\fP, the other is \fBWGS84GeoPoint\fP\&. \fBTokyoGeoPoint\fP is used for Japan geodetic system. \fBWGS84GeoPoint\fP is used for world geodetic system. .sp Specify longitude and latitude as follows: .INDENT 0.0 .IP \(bu 2 "[latitude in milliseconds]x[longitude in milliseconds]"（e.g.: "128452975x503157902"） .IP \(bu 2 "[latitude in milliseconds],[longitude in milliseconds]"（e.g.: "128452975,503157902"） .IP \(bu 2 "[latitude in degrees]x[longitude in degrees]"（e.g.: "35.6813819x139.7660839"） .IP \(bu 2 "[latitude in degrees],[longitude in degrees]"（e.g.: "35.6813819,139.7660839"） .UNINDENT .sp Let\(aqs store two location information about station in Japan by WGS. One is Tokyo station, the other is Shinjyuku station. Both of them are station in Japan. The latitude of Tokyo station is 35 degrees 40 minutes 52.975 seconds, the longitude of Tokyo station is 139 degrees 45 minutes 57.902 seconds. The latitude of Shinjyuku station is 35 degrees 41 minutes 27.316 seconds, the longitude of Shinjyuku station is 139 degrees 42 minutes 0.929 seconds. Thus, location information in milliseconds are "128452975x503157902" and "128487316x502920929" respectively. location information in degrees are "35.6813819x139.7660839" and "35.6909211x139.7002581" respectively. .sp Let\(aqs register location information in milliseconds. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create \-\-table Site \-\-name location \-\-type WGS84GeoPoint # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Site [ {"_key":"http://example.org/","location":"128452975x503157902"} {"_key":"http://example.net/","location":"128487316x502920929"}, ] # [[0, 1337566253.89858, 0.000355720520019531], 2] select \-\-table Site \-\-query "_id:1 OR _id:2" \-\-output_columns _key,location # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ] # ], # [ # "http://example.org/", # "128452975x503157902" # ], # [ # "http://example.net/", # "128487316x502920929" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Then assign the value of geo distance which is calculated by \fB/reference/functions/geo_distance\fP function to \fBscorer\fP parameter. .sp Let\(aqs show geo distance from Akihabara station in Japan. In world geodetic system, the latitude of Akihabara station is 35 degrees 41 minutes 55.259 seconds, the longitude of Akihabara station is 139 degrees 46 minutes 27.188 seconds. Specify "128515259x503187188" for geo_distance function. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query "_id:1 OR _id:2" \-\-output_columns _key,location,_score \-\-scorer \(aq_score = geo_distance(location, "128515259x503187188")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "_score", # "Int32" # ] # ], # [ # "http://example.org/", # "128452975x503157902", # 2054 # ], # [ # "http://example.net/", # "128487316x502920929", # 6720 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp As you can see, the geo distance between Tokyo station and Akihabara station is 2054 meters, the geo distance between Akihabara station and Shinjyuku station is 6720 meters. .sp The return value of geo_distance function is also used for sorting by specifying pseudo \fB_score\fP column to \fBsortby\fP parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-query "_id:1 OR _id:2" \-\-output_columns _key,location,_score \-\-scorer \(aq_score = geo_distance(location, "128515259x503187188")\(aq \-\-sortby \-_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "_score", # "Int32" # ] # ], # [ # "http://example.net/", # "128487316x502920929", # 6720 # ], # [ # "http://example.org/", # "128452975x503157902", # 2054 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Groonga also supports to narrow down by "a certain point within specified meters". .sp In such a case, use \fB/reference/functions/geo_in_circle\fP function in \fBfilter\fP parameter. .sp For example, search the records which exists within 5000 meters from Akihabara station. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-output_columns _key,location \-\-filter \(aqgeo_in_circle(location, "128515259x503187188", 5000)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ] # ], # [ # "http://example.org/", # "128452975x503157902" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp There is \fB/reference/functions/geo_in_rectangle\fP function which is used to search a certain point within specified region. .SS Drilldown .sp You learned how to search and sort searched results in the previous sections. Now that you can search as you likes, but how do you summarize the number of records which has specific value in the column? .sp As you know, there is a naive solution to execute query by every the value of column, then you can get the number of records as a result. It is a simple way, but it is not reasonable to many records. .sp If you are familiar with SQL, you will doubt with "Is there a similar SQL functionality to \fBGROUP BY\fP in Groonga?". .sp Of course, Groonga provides such a functionality. It\(aqs called as \fBdrilldown\fP\&. .sp \fBdrilldown\fP enables you to get the number of records which belongs to specific the value of column at once. .sp To illustrate this feature, imagine the case that classification by domain and grouping by country that domain belongs to. .sp Here is the concrete examples how to use this feature. .sp In this example, we add two columns to \fBSite\fP table. \fBdomain\fP column is used for TLD (top level domain). \fBcountry\fP column is used for country name. The type of these columns are \fBSiteDomain\fP table which uses domain name as a primary key and \fBSiteCountry\fP table which uses country name as a primary key. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name SiteDomain \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create \-\-name SiteCountry \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Site \-\-name domain \-\-flags COLUMN_SCALAR \-\-type SiteDomain # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Site \-\-name country \-\-flags COLUMN_SCALAR \-\-type SiteCountry # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Site [ {"_key":"http://example.org/","domain":".org","country":"japan"}, {"_key":"http://example.net/","domain":".net","country":"brazil"}, {"_key":"http://example.com/","domain":".com","country":"japan"}, {"_key":"http://example.net/afr","domain":".net","country":"usa"}, {"_key":"http://example.org/aba","domain":".org","country":"korea"}, {"_key":"http://example.com/rab","domain":".com","country":"china"}, {"_key":"http://example.net/atv","domain":".net","country":"china"}, {"_key":"http://example.org/gat","domain":".org","country":"usa"}, {"_key":"http://example.com/vdw","domain":".com","country":"japan"} ] # [[0, 1337566253.89858, 0.000355720520019531], 9] .ft P .fi .UNINDENT .UNINDENT .sp Here is a example of drilldown with \fBdomain\fP column. Three kind of values are used in \fBdomain\fP column \- ".org", ".net" and ".com". .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-drilldown domain # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # ".org", # 3 # ], # [ # ".net", # 3 # ], # [ # ".com", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is a summary of above query. .SS Drilldown by \fBdomain\fP column .TS center; |l|l|l|. _ T{ Group by T} T{ The number of group records T} T{ Group records means following records T} _ T{ \&.org T} T{ 3 T} T{ .INDENT 0.0 .IP \(bu 2 \fI\%http://example.org/\fP .IP \(bu 2 \fI\%http://example.org/aba\fP .IP \(bu 2 \fI\%http://example.org/gat\fP .UNINDENT T} _ T{ \&.net T} T{ 3 T} T{ .INDENT 0.0 .IP \(bu 2 \fI\%http://example.net/\fP .IP \(bu 2 \fI\%http://example.net/afr\fP .IP \(bu 2 \fI\%http://example.net/atv\fP .UNINDENT T} _ T{ \&.com T} T{ 3 T} T{ .INDENT 0.0 .IP \(bu 2 \fI\%http://example.com/\fP .IP \(bu 2 \fI\%http://example.com/rab\fP .IP \(bu 2 \fI\%http://example.com/vdw\fP .UNINDENT T} _ .TE .sp The value of drilldown are returned as the value of \fB_nsubrecs\fP column. In this case, \fBSite\fP table is grouped by ".org", ".net", ".com" domain. \fB_nsubrecs\fP shows that each three domain has three records. .sp If you execute drildown to the column which has table as a type, you can get the value of column which is stored in referenced table. \fB_nsubrecs\fP pseudo column is added to the table which is used for drilldown. this pseudo column stores the number of records which is grouped by. .sp Then, investigate referenced table in detail. As \fBSite\fP table use \fBSiteDomain\fP table as column type of \fBdomain\fP, you can use \fB\-\-drilldown_output_columns\fP to know detail of referenced column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-drilldown domain \-\-drilldown_output_columns _id,_key,_nsubrecs # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # 1, # ".org", # 3 # ], # [ # 2, # ".net", # 3 # ], # [ # 3, # ".com", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Now, you can see detail of each grouped domain, drilldown by \fBcountry\fP column which has ".org" as column value. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-filter "domain._id == 1" \-\-drilldown country # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "japan", # 1 # ], # [ # "korea", # 1 # ], # [ # "usa", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Drilldown with multiple column .sp Drilldown feature supports multiple column. Use comma separated multiple column names as \fBdrildown\fP parameter. You can get the each result of drilldown at once. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-drilldown domain,country # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # ".org", # 3 # ], # [ # ".net", # 3 # ], # [ # ".com", # 3 # ] # ], # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "japan", # 3 # ], # [ # "brazil", # 1 # ], # [ # "usa", # 2 # ], # [ # "korea", # 1 # ], # [ # "china", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Sorting drildown results .sp Use \fB\-\-drilldown_sortby\fP if you want to sort the result of drilldown. For example, specify \fB_nsubrecs\fP as ascending order. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-drilldown country \-\-drilldown_sortby _nsubrecs # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "brazil", # 1 # ], # [ # "korea", # 1 # ], # [ # "usa", # 2 # ], # [ # "china", # 2 # ], # [ # "japan", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS limits drildown results .sp The number of drilldown results is limited to 10 as a default. Use \fBdrilldown_limit\fP and \fBdrilldown_offset\fP parameter to customize orilldown results. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-limit 0 \-\-drilldown country \-\-drilldown_sortby _nsubrecs \-\-drilldown_limit 2 \-\-drilldown_offset 2 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 9 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "country", # "SiteCountry" # ], # [ # "domain", # "SiteDomain" # ], # [ # "link", # "Site" # ], # [ # "links", # "Site" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "title", # "ShortText" # ] # ] # ], # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "usa", # 2 # ], # [ # "china", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Note that drilldown to the column which stores string is slower than the columns which stores the other types. If you drilldown to string type of column, create the table that type of primary key is string, then create the column which refers that table. .SS Tag search and reverse resolution of reference relationships .sp As you know, Groonga supports to store array in column which refers other table. In fact, you can do tag search by using array data which refers other table. .sp Tag search is very fast because Groonga use inverted index as data structure. .SS Tag search .sp Let\(aqs consider to create a search engine for an web site to share movies. Each movie may be associated with multiple keywords which represents the content of movie. .sp Let\(aqs create tables for movie information, then search the movies. .sp First, create the \fBVideo\fP table which stores movie information. the \fBVideo\fP table has two columns. the \fBtitle\fP column stores title of the movie. the \fBtags\fP column stores multiple tag information in reference Tag table. .sp Next, create the \fBTag\fP table which stores tag information. the \fBTag\fP table has one column. The tag string is stored as primary key, then \fBindex_tags\fP stores indexes for tags column of Video table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Video \-\-flags TABLE_HASH_KEY \-\-key_type UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create \-\-name Tag \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Video \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Video \-\-name tags \-\-flags COLUMN_VECTOR \-\-type Tag # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Tag \-\-name index_tags \-\-flags COLUMN_INDEX \-\-type Video \-\-source tags # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Video [ {"_key":1,"title":"Soccer 2010","tags":["Sports","Soccer"]}, {"_key":2,"title":"Zenigata Kinjirou","tags":["Variety","Money"]}, {"_key":3,"title":"groonga Demo","tags":["IT","Server","groonga"]}, {"_key":4,"title":"Moero!! Ultra Baseball","tags":["Sports","Baseball"]}, {"_key":5,"title":"Hex Gone!","tags":["Variety","Quiz"]}, {"_key":6,"title":"Pikonyan 1","tags":["Animation","Pikonyan"]}, {"_key":7,"title":"Draw 8 Month","tags":["Animation","Raccoon"]}, {"_key":8,"title":"K.O.","tags":["Animation","Music"]} ] # [[0, 1337566253.89858, 0.000355720520019531], 8] .ft P .fi .UNINDENT .UNINDENT .sp After creating indexed column, you can do full\-text search very fast. The indexed column is also automatically updated when stored data is refreshed. .sp List up the movies that specific keywords are given. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Video \-\-query tags:@Variety \-\-output_columns _key,title # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "UInt32" # ], # [ # "title", # "ShortText" # ] # ], # [ # 2, # "Zenigata Kinjirou" # ], # [ # 5, # "Hex Gone!" # ] # ] # ] # ] select \-\-table Video \-\-query tags:@Sports \-\-output_columns _key,title # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "UInt32" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "Soccer 2010" # ], # [ # 4, # "Moero!! Ultra Baseball" # ] # ] # ] # ] select \-\-table Video \-\-query tags:@Animation \-\-output_columns _key,title # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "UInt32" # ], # [ # "title", # "ShortText" # ] # ], # [ # 6, # "Pikonyan 1" # ], # [ # 7, # "Draw 8 Month" # ], # [ # 8, # "K.O." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp You can search by tags such as "Variety", "Sports" and "Animation". .SS Reverse resolution of reference relationships .sp Groonga supports indexes for reverse resolution among tables. Tag search is one of concrete examples. .sp For example, you can search friendships by reverse resolution in social networking site. .sp Following example shows how to create \fBUser\fP table which stores user information, \fBusername\fP column which stores user name, \fBfriends\fP column which stores list of user\(aqs friends in array, \fBindex_friends\fP column as indexed column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name User \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table User \-\-name username \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table User \-\-name friends \-\-flags COLUMN_VECTOR \-\-type User # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table User \-\-name index_friends \-\-flags COLUMN_INDEX \-\-type User \-\-source friends # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table User [ {"_key":"ken","username":"健作","friends":["taro","jiro","tomo","moritapo"]} {"_key":"moritapo","username":"森田","friends":["ken","tomo"]} {"_key":"taro","username":"ぐるんが太郎","friends":["jiro","tomo"]} {"_key":"jiro","username":"ぐるんが次郎","friends":["taro","tomo"]} {"_key":"tomo","username":"トモちゃん","friends":["ken","hana"]} {"_key":"hana","username":"花子","friends":["ken","taro","jiro","moritapo","tomo"]} ] # [[0, 1337566253.89858, 0.000355720520019531], 6] .ft P .fi .UNINDENT .UNINDENT .sp Let\(aqs show list of users who contains specified user in friend list. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table User \-\-query friends:@tomo \-\-output_columns _key,username # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "username", # "ShortText" # ] # ], # [ # "ken", # "健作" # ], # [ # "taro", # "ぐるんが太郎" # ], # [ # "jiro", # "ぐるんが次郎" # ], # [ # "moritapo", # "森田" # ], # [ # "hana", # "花子" # ] # ] # ] # ] select \-\-table User \-\-query friends:@jiro \-\-output_columns _key,username # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "username", # "ShortText" # ] # ], # [ # "ken", # "健作" # ], # [ # "taro", # "ぐるんが太郎" # ], # [ # "hana", # "花子" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Then drilldown the count which shows user is listed as friend. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table User \-\-limit 0 \-\-drilldown friends # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 6 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "friends", # "User" # ], # [ # "index_friends", # "User" # ], # [ # "username", # "ShortText" # ] # ] # ], # [ # [ # 6 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "taro", # 3 # ], # [ # "jiro", # 3 # ], # [ # "tomo", # 5 # ], # [ # "moritapo", # 2 # ], # [ # "ken", # 3 # ], # [ # "hana", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp As you can see, it shows the results which follows reverse resolution of reference relationship. .SS Geo location search with index .sp Groonga supports to add indexes to the column which stores geo location information. Groonga is very fast because it use such indexes against the column which contains geo location information to search enormous number of records. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name GeoIndex \-\-flags TABLE_PAT_KEY \-\-key_type WGS84GeoPoint # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table GeoIndex \-\-name index_point \-\-type Site \-\-flags COLUMN_INDEX \-\-source location # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Site [ {"_key":"http://example.org/","location":"128452975x503157902"}, {"_key":"http://example.net/","location":"128487316x502920929"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] select \-\-table Site \-\-filter \(aqgeo_in_circle(location, "128515259x503187188", 5000)\(aq \-\-output_columns _key,location # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ] # ], # [ # "http://example.org/", # "128452975x503157902" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp These indexes are also used when sorting the records with geo location search. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Site \-\-filter \(aqgeo_in_circle(location, "128515259x503187188", 50000)\(aq \-\-output_columns _key,location,_score \-\-sortby \(aq\-geo_distance(location, "128515259x503187188")\(aq \-\-scorer \(aq_score = geo_distance(location, "128515259x503187188")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "location", # "WGS84GeoPoint" # ], # [ # "_score", # "Int32" # ] # ], # [ # "http://example.org/", # "128452975x503157902", # 2054 # ], # [ # "http://example.net/", # "128487316x502920929", # 6720 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS match_columns parameter .SS Full\-text search against multiple columns .sp Groonga supports full\-text search against multiple columns. Let\(aqs consider blog site. Usually, blog site has a table which contains title column and content column. How do you search the blog entry which contains specified keywords in title or content? .sp In such a case, there are two ways to create indexes. One way is creating column index against each column. The other way is creating one column index against multiple columns. Either way, Groonga supports similar full\-text search syntax. .SS Creating column index against each column .sp Here is the example which create column index against each column. .sp First, create \fBBlog1\fP table, add \fBtitle\fP column which stores title string, \fBmessage\fP column which stores content of blog entry. .sp Then create \fBIndexBlog1\fP table for column indexes, add \fBindex_title\fP column for \fBtitle\fP column, \fBindex_message\fP column for \fBmessage\fP column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Blog1 \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Blog1 \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Blog1 \-\-name message \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create \-\-name IndexBlog1 \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table IndexBlog1 \-\-name index_title \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Blog1 \-\-source title # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table IndexBlog1 \-\-name index_message \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Blog1 \-\-source message # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Blog1 [ {"_key":"grn1","title":"groonga test","message":"groonga message"}, {"_key":"grn2","title":"baseball result","message":"rakutan eggs 4 \- 4 groonga moritars"}, {"_key":"grn3","title":"groonga message","message":"none"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .sp \fBmatch_columns\fP option of \fBselect\fP command accepts multiple columns as search target. Specify query string to \fBquery\fP option. Then you can do full\-text search title and content of blog entries. .sp Let\(aqs try to search blog entries. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Blog1 \-\-match_columns title||message \-\-query groonga # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "grn1", # "groonga message", # "groonga test" # ], # [ # 3, # "grn3", # "none", # "groonga message" # ], # [ # 2, # "grn2", # "rakutan eggs 4 \- 4 groonga moritars", # "baseball result" # ] # ] # ] # ] select \-\-table Blog1 \-\-match_columns title||message \-\-query message # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 3, # "grn3", # "none", # "groonga message" # ], # [ # 1, # "grn1", # "groonga message", # "groonga test" # ] # ] # ] # ] select \-\-table Blog1 \-\-match_columns title \-\-query message # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 3, # "grn3", # "none", # "groonga message" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Creating one column index against multiple columns .sp Groonga also supports one column index against multiple columns. .sp The difference for previous example is only one column index exists. Thus, There is one common column index against title and message column. .sp Even though same column index is used, Groonga supports to search against title column only, message column only and title or message column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Blog2 \-\-flags TABLE_HASH_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Blog2 \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table Blog2 \-\-name message \-\-flags COLUMN_SCALAR \-\-type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create \-\-name IndexBlog2 \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table IndexBlog2 \-\-name index_blog \-\-flags COLUMN_INDEX|WITH_POSITION|WITH_SECTION \-\-type Blog2 \-\-source title,message # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Blog2 [ {"_key":"grn1","title":"groonga test","message":"groonga message"}, {"_key":"grn2","title":"baseball result","message":"rakutan eggs 4 \- 4 groonga moritars"}, {"_key":"grn3","title":"groonga message","message":"none"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .sp Let\(aqs search same query in previous section. You can get same search results. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Blog2 \-\-match_columns title||message \-\-query groonga # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "grn1", # "groonga message", # "groonga test" # ], # [ # 2, # "grn2", # "rakutan eggs 4 \- 4 groonga moritars", # "baseball result" # ], # [ # 3, # "grn3", # "none", # "groonga message" # ] # ] # ] # ] select \-\-table Blog2 \-\-match_columns title||message \-\-query message # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 1, # "grn1", # "groonga message", # "groonga test" # ], # [ # 3, # "grn3", # "none", # "groonga message" # ] # ] # ] # ] select \-\-table Blog2 \-\-match_columns title \-\-query message # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "message", # "ShortText" # ], # [ # "title", # "ShortText" # ] # ], # [ # 3, # "grn3", # "none", # "groonga message" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There may be a question that "which is the better solution for indexing." It depends on the case. .INDENT 0.0 .IP \(bu 2 Indexes for each column \- The update performance tends to be better than multiple colum index because there is enough buffer for updating. On the other hand, the efficiency of disk usage is not so good. .IP \(bu 2 Indexes for multiple column \- It saves disk usage because it shares common buffer. On the other hand, the update performance is not so good. .UNINDENT .UNINDENT .UNINDENT .SS Full text search with specific index name .sp TODO .SS Nested index search among related table by column index .sp If there are relationships among multiple table with column index, you can search multiple table by specifying reference column name. .sp Here is the concrete example. .sp There are tables which store blog articles, comments for articles. The table which stores articles has columns for article and comment. And the comment column refers Comments table. The table which stores comments has columns for comment and column index to article table. .sp if you want to search the articles which contain specified keyword in comment, you need to execute fulltext search for table of comment, then search the records which contains fulltext search results. .sp But, you can search the records by specifying the reference column index at once. .sp Here is the sample schema. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Comments TABLE_HASH_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comments content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Articles TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Articles content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Articles comment COLUMN_SCALAR Comments # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Lexicon TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon articles_content COLUMN_INDEX|WITH_POSITION Articles content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon comments_content COLUMN_INDEX|WITH_POSITION Comments content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comments article COLUMN_INDEX Articles comment # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Here is the sample data. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Comments [ {"_key": 1, "content": "I\(aqm using groonga too!"}, {"_key": 2, "content": "I\(aqm using groonga and mroonga!"}, {"_key": 3, "content": "I\(aqm using mroonga too!"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] load \-\-table Articles [ {"content": "Groonga is fast!", "comment": 1}, {"content": "Groonga is useful!"}, {"content": "Mroonga is fast!", "comment": 3} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .sp You can write the query that search the records which contains specified keyword as a comment, then fetch the articles which refers to it. .sp Query for searching the records described above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Articles \-\-match_columns comment.content \-\-query groonga \-\-output_columns "_id, _score, *" .ft P .fi .UNINDENT .UNINDENT .sp You need to concatenate comment column of Articles table and content column of Comments table with period(.) as \-\-match_columns arguments. .sp At first, this query execute fulltext search from content of Comments table, then fetch the records of Articles table which refers to already searched records of Comments table. (Because of this, if you comment out the query which create column index \(aqarticle\(aq of Comments table, you can\(aqt get intended search results.) .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Articles \-\-match_columns comment.content \-\-query groonga \-\-output_columns "_id, _score, *" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_score", # "Int32" # ], # [ # "comment", # "Comments" # ], # [ # "content", # "Text" # ] # ], # [ # 1, # 1, # 1, # "Groonga is fast!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Now, you can search articles which contains specific keywords as a comment. .sp The feature of nested index search is not limited to the relationship between two table only. .sp Here is the sample schema similar to previous one. The difference is added table which express \(aqReply\(aq and relationship is extended to three tables. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Replies2 TABLE_HASH_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Replies2 content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Comments2 TABLE_HASH_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comments2 content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comments2 comment COLUMN_SCALAR Replies2 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Articles2 TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Articles2 content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Articles2 comment COLUMN_SCALAR Comments2 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Lexicon2 TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon2 articles_content COLUMN_INDEX|WITH_POSITION Articles2 content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon2 comments_content COLUMN_INDEX|WITH_POSITION Comments2 content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon2 replies_content COLUMN_INDEX|WITH_POSITION Replies2 content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comments2 article COLUMN_INDEX Articles2 comment # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Replies2 reply_to COLUMN_INDEX Comments2 comment # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Here is the sample data. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Replies2 [ {"_key": 1, "content": "I\(aqm using rroonga too!"}, {"_key": 2, "content": "I\(aqm using groonga and mroonga and rroonga!"}, {"_key": 3, "content": "I\(aqm using nroonga too!"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] load \-\-table Comments2 [ {"_key": 1, "content": "I\(aqm using groonga too!", "comment": 1}, {"_key": 2, "content": "I\(aqm using groonga and mroonga!", "comment": 2}, {"_key": 3, "content": "I\(aqm using mroonga too!"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] load \-\-table Articles2 [ {"content": "Groonga is fast!", "comment": 1}, {"content": "Groonga is useful!", "comment": 2}, {"content": "Mroonga is fast!", "comment": 3} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .sp Query for searching the records described above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Articles2 \-\-match_columns comment.content \-\-query mroonga \-\-output_columns "_id, _score, *" select Articles2 \-\-match_columns comment.comment.content \-\-query mroonga \-\-output_columns "_id, _score, *" .ft P .fi .UNINDENT .UNINDENT .sp The first query searches \(aqmroonga\(aq from Comments2 table, the second one searches \(aqmroonga\(aq from Replies2 and Comment2 table by using reference column index. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Articles2 \-\-match_columns comment.content \-\-query mroonga \-\-output_columns "_id, _score, *" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_score", # "Int32" # ], # [ # "comment", # "Comments2" # ], # [ # "content", # "Text" # ] # ], # [ # 2, # 1, # 2, # "Groonga is useful!" # ], # [ # 3, # 1, # 3, # "Mroonga is fast!" # ] # ] # ] # ] select Articles2 \-\-match_columns comment.comment.content \-\-query mroonga \-\-output_columns "_id, _score, *" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_score", # "Int32" # ], # [ # "comment", # "Comments2" # ], # [ # "content", # "Text" # ] # ], # [ # 2, # 1, # 2, # "Groonga is useful!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp As a result, the first query matches two article because of Comments2 table has two records which contains \(aqmroonga\(aq as keyword. .sp On the other hand, the second one matches one article only because of Replies2 table has only one record which contains \(aqmroonga\(aq as keyword, and there is one record which contains same keyword and refers to the record in Comments2 table. .SS Indexes with Weight .sp TODO .SS Prefix search with patricia trie .sp Groonga supports to create a table with patricia trie option. By specifying it, You can do prefix search. .sp And more, you can do suffix search against primary key by specifying additional option. .SS Prefix search by primary key .sp table_create command which uses TABLE_PAT_KEY for flags option supports prefix search by primary key. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name PatPrefix \-\-flags TABLE_PAT_KEY \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table PatPrefix [ {"_key":"James"} {"_key":"Jason"} {"_key":"Jennifer"}, {"_key":"Jeff"}, {"_key":"John"}, {"_key":"Joseph"}, ] # [[0, 1337566253.89858, 0.000355720520019531], 6] select \-\-table PatPrefix \-\-query _key:^Je # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 3, # "Jennifer" # ], # [ # 4, # "Jeff" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS 主キーによる後方一致検索 .sp table_createコマンドのflagsオプションにTABLE_PAT_KEYとKEY_WITH_SISを指定することで、主キーによる前方一致検索・後方一致検索の両方が可能となります。 .sp KEY_WITH_SISフラグを付与すると、データを追加する際に後方一致用のレコードも追加されてしまいます。そのため、単純に検索すると、元のレコードに加えて自動的に追加されたレコードまでヒットしてしまいます。元のレコードのみ検索するために、一工夫必要になります。 .sp 例えば、元のレコードと自動的に追加されたレコードとの区別をつけるために、元のレコードであることを示すoriginalカラムを追加して、検索時にはoriginalカラムが \fBtrue\fP も検索条件に加えます。 \fB\-\-query\fP オプションでは \fBBool\fP 型の値を直感的に指定することができないので \fB\-\-filter\fP オプションを使っていることに注意してください。 .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name PatSuffix \-\-flags TABLE_PAT_KEY|KEY_WITH_SIS \-\-key_type ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create \-\-table PatSuffix \-\-name original \-\-type Bool # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table PatSuffix [ {"_key":"ひろゆき","original":true}, {"_key":"まろゆき","original":true}, {"_key":"ひろあき","original":true}, {"_key":"ゆきひろ","original":true} ] # [[0, 1337566253.89858, 0.000355720520019531], 4] select \-\-table PatSuffix \-\-query _key:$ゆき # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "original", # "Bool" # ] # ], # [ # 3, # "ゆき", # false # ], # [ # 2, # "ろゆき", # false # ], # [ # 5, # "まろゆき", # true # ], # [ # 1, # "ひろゆき", # true # ] # ] # ] # ] select \-\-table PatSuffix \-\-filter \(aq_key @$ "ゆき" && original == true\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "original", # "Bool" # ] # ], # [ # 5, # "まろゆき", # true # ], # [ # 1, # "ひろゆき", # true # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Additional information about lexicon for full text search .sp Groonga uses lexicon for full text search as a table. Thus, Groonga can hold multiple information each lexicon. For example, Groonga holds frequency of word, flags for stop word, importance of word and so on. .sp TODO: Write document. .SS Let\(aqs create micro\-blog .sp Let\(aqs create micro\-blog with full text search by Groonga. Micro\-blog is one of the broadcast medium in the forms of blog. It is mainly used to post small messages like a Twitter. .SS Create a table .sp Let\(aqs create table. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Users \-\-flags TABLE_HASH_KEY \-\-key_type ShortText table_create \-\-name Comments \-\-flags TABLE_HASH_KEY \-\-key_type ShortText table_create \-\-name HashTags \-\-flags TABLE_HASH_KEY \-\-key_type ShortText table_create \-\-name Bigram \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram table_create \-\-name GeoIndex \-\-flags TABLE_PAT_KEY \-\-key_type WGS84GeoPoint column_create \-\-table Users \-\-name name \-\-flags COLUMN_SCALAR \-\-type ShortText column_create \-\-table Users \-\-name follower \-\-flags COLUMN_VECTOR \-\-type Users column_create \-\-table Users \-\-name favorites \-\-flags COLUMN_VECTOR \-\-type Comments column_create \-\-table Users \-\-name location \-\-flags COLUMN_SCALAR \-\-type WGS84GeoPoint column_create \-\-table Users \-\-name location_str \-\-flags COLUMN_SCALAR \-\-type ShortText column_create \-\-table Users \-\-name description \-\-flags COLUMN_SCALAR \-\-type ShortText column_create \-\-table Users \-\-name followee \-\-flags COLUMN_INDEX \-\-type Users \-\-source follower column_create \-\-table Comments \-\-name comment \-\-flags COLUMN_SCALAR \-\-type ShortText column_create \-\-table Comments \-\-name last_modified \-\-flags COLUMN_SCALAR \-\-type Time column_create \-\-table Comments \-\-name replied_to \-\-flags COLUMN_SCALAR \-\-type Comments column_create \-\-table Comments \-\-name replied_users \-\-flags COLUMN_VECTOR \-\-type Users column_create \-\-table Comments \-\-name hash_tags \-\-flags COLUMN_VECTOR \-\-type HashTags column_create \-\-table Comments \-\-name location \-\-flags COLUMN_SCALAR \-\-type WGS84GeoPoint column_create \-\-table Comments \-\-name posted_by \-\-flags COLUMN_SCALAR \-\-type Users column_create \-\-table Comments \-\-name favorited_by \-\-flags COLUMN_INDEX \-\-type Users \-\-source favorites column_create \-\-table HashTags \-\-name hash_index \-\-flags COLUMN_INDEX \-\-type Comments \-\-source hash_tags column_create \-\-table Bigram \-\-name users_index \-\-flags COLUMN_INDEX|WITH_POSITION|WITH_SECTION \-\-type Users \-\-source name,location_str,description column_create \-\-table Bigram \-\-name comment_index \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Comments \-\-source comment column_create \-\-table GeoIndex \-\-name users_location \-\-type Users \-\-flags COLUMN_INDEX \-\-source location column_create \-\-table GeoIndex \-\-name comments_location \-\-type Comments \-\-flags COLUMN_INDEX \-\-source location .ft P .fi .UNINDENT .UNINDENT .SS Users table .sp This is the table which stores user information. It stores name of user, profile, list of follower and so on. .INDENT 0.0 .TP .B \fB_key\fP User ID .TP .B \fBname\fP User name .TP .B \fBfollower\fP List of following users .TP .B \fBfavorites\fP List of favorite comments .TP .B \fBlocation\fP Current location of user (geolocation) .TP .B \fBlocation_str\fP Current location of user (string) .TP .B \fBdescription\fP User profile .TP .B \fBfollowee\fP Indexes for \fBfollower\fP column in \fBUsers\fP table. With this indexes, you can search users who follows the person. .UNINDENT .SS Comments table .sp This is the table which stores comments and its metadata. It stores content of comment, posted date, comment which reply to, and so on. .INDENT 0.0 .TP .B \fB_key\fP Comment ID .TP .B \fBcomment\fP Content of comment .TP .B \fBlast_modified\fP Posted date .TP .B \fBreplied_to\fP Comment which you reply to someone .TP .B \fBreplied_users\fP List of users who you reply to .TP .B \fBhash_tags\fP List of hash tags about comment .TP .B \fBlocation\fP Posted place (for geolocation) .TP .B \fBposted_by\fP Person who write comment .TP .B \fBfavorited_by\fP Indexes for \fBfavorites\fP column in \fBUsers\fP table. With this indexes, you can search the person who mark comment as favorite one. .UNINDENT .SS HashTags table .sp This is the table which stores hash tags for comments. .INDENT 0.0 .TP .B \fB_key\fP Hash tag .TP .B \fBhash_index\fP Indexes for \fBComments.hash_tags\fP\&. With this indexes, you can search list of comments with specified hash tags. .UNINDENT .SS Bigram table .sp This is the table which stores indexes for full text search by user information or comments. .INDENT 0.0 .TP .B \fB_key\fP Word .TP .B \fBusers_index\fP Indexes of user information. This column contains indexes of user name (\fBUsers.name\fP), current location (\fBUsers.location_str\fP), profile (\fBUsers.description\fP). .TP .B \fBcomment_index\fP Indexes about content of comments (\fBComments.comment\fP). .UNINDENT .SS GeoIndex table .sp This is the table which stores indexes of location column to search geo location effectively. .INDENT 0.0 .TP .B \fBusers_location\fP Indexes of location column for Users table .TP .B \fBcomments_location\fP Indexes of location column for Comments table .UNINDENT .SS Loading data .sp Then, load example data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Users [ { "_key": "alice", "name": "Alice", "follower": ["bob"], "favorites": [], "location": "152489000x\-255829000", "location_str": "Boston, Massachusetts", "description": "Groonga developer" }, { "_key": "bob", "name": "Bob", "follower": ["alice","charlie"], "favorites": ["alice:1","charlie:1"], "location": "146249000x\-266228000", "location_str": "Brooklyn, New York City", "description": "" }, { "_key": "charlie", "name": "Charlie", "follower": ["alice","bob"], "favorites": ["alice:1","bob:1"], "location": "146607190x\-267021260", "location_str": "Newark, New Jersey", "description": "Hmm,Hmm" } ] load \-\-table Comments [ { "_key": "alice:1", "comment": "I\(aqve created micro\-blog!", "last_modified": "2010/03/17 12:05:00", "posted_by": "alice", }, { "_key": "bob:1", "comment": "First post. test,test...", "last_modified": "2010/03/17 12:00:00", "posted_by": "bob", }, { "_key": "alice:2", "comment": "@bob Welcome!!!", "last_modified": "2010/03/17 12:05:00", "replied_to": "bob:1", "replied_users": ["bob"], "posted_by": "alice", }, { "_key": "bob:2", "comment": "@alice Thanks!", "last_modified": "2010/03/17 13:00:00", "replied_to": "alice:2", "replied_users": ["alice"], "posted_by": "bob", }, { "_key": "bob:3", "comment": "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga", "last_modified": "2010/03/17 14:00:00", "hash_tags": ["groonga"], "location": "146566000x\-266422000", "posted_by": "bob", }, { "_key": "bob:4", "comment": "I\(aqm come at city of New York for development camp! #groonga #travel", "last_modified": "2010/03/17 14:05:00", "hash_tags": ["groonga", "travel"], "location": "146566000x\-266422000", "posted_by": "bob", }, { "_key": "charlie:1", "comment": "@alice @bob I\(aqve tried to register!", "last_modified": "2010/03/17 15:00:00", "replied_users": ["alice", "bob"], "location": "146607190x\-267021260", "posted_by": "charlie", } { "_key": "charlie:2", "comment": "I\(aqm at the Museum of Modern Art in NY now!", "last_modified": "2010/03/17 15:05:00", "location": "146741340x\-266319590", "posted_by": "charlie", } ] .ft P .fi .UNINDENT .UNINDENT .sp \fBfollower\fP column and \fBfavorites\fP column in \fBUsers\fP table and \fBreplied_users\fP column in \fBComments\fP table are vector column, so specify the value as an array. .sp \fBlocation\fP column in \fBUsers\fP table, \fBlocation\fP column in \fBComments\fP table use GeoPoint type. This type accepts "[latitude]x[longitude]". .sp \fBlast_modified\fP column in \fBComments\fP table use Time type. .sp There are two way to specify the value. First, specify epoch (seconds since Jan, 1, 1970 AM 00:00:00) directly. In this case, you can specify micro seconds as fractional part. The value is converted from factional part to the time which is micro seconds based one when data is loaded. The second, specify the timestamp as string in following format: "(YEAR)/(MONTH)/(DAY) (HOUR):(MINUTE):(SECOND)". In this way, the string is casted to proper micro seconds when data is loaded. .SS Search .sp Let\(aqs search micro\-blog. .SS Search users by keyword .sp In this section, we search micro\-blog against multiple column by keyword. See \fBmatch_columns\fP to search multiple column at once. .sp Let\(aqs search user from micro\-blog\(aqs user name, location, description entries. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Users \-\-match_columns name,location_str,description \-\-query "New York" \-\-output_columns _key,name # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], 3] # [[0, 1337566253.89858, 0.000355720520019531], 8] # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "name", # "ShortText" # ] # ], # [ # "bob", # "Bob" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp By using "New York" as searching keyword for user, "Bob" who lives in "New York" is listed in search result. .SS Search users by geolocation data (GeoPoint) .sp In this section, we search users by column data which use type of GeoPoint. See \fBsearch\fP about GeoPoint column. .sp Following example searches users who live in within 20km from specified location. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Users \-\-filter \(aqgeo_in_circle(location,"146710080x\-266315480",20000)\(aq \-\-output_columns _key,name # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "name", # "ShortText" # ] # ], # [ # "charlie", # "Charlie" # ], # [ # "bob", # "Bob" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It shows that "Bob" and "Charlie" lives in within 20 km from station of "Grand Central Terminal". .SS Search users who follows specific user .sp In this section, we do reverse resolution of reference relationships which is described at \fBindex\fP\&. .sp Following examples shows reverse resolution about \fBfollower\fP column of \fBUsers\fP table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Users \-\-query follower:@bob \-\-output_columns _key,name # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "name", # "ShortText" # ] # ], # [ # "alice", # "Alice" # ], # [ # "charlie", # "Charlie" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It shows that "Alice" and "Charlie" follows "Bob". .SS Search comments by using the value of GeoPoint type .sp In this section, we search comments which are written within specific location. .sp Then, we also use drill down which is described at \fBdrilldown\fP\&. Following example shows how to drill down against search results. As a result, we get the value of count which is grouped by user, and hash tags respectively. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Comments \-\-filter \(aqgeo_in_circle(location,"146867000x\-266280000",20000)\(aq \-\-output_columns posted_by.name,comment \-\-drilldown hash_tags,posted_by # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "posted_by.name", # "ShortText" # ], # [ # "comment", # "ShortText" # ] # ], # [ # "Charlie", # "I\(aqm at the Museum of Modern Art in NY now!" # ], # [ # "Bob", # "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga" # ], # [ # "Bob", # "I\(aqm come at city of New York for development camp! #groonga #travel" # ], # [ # "Charlie", # "@alice @bob I\(aqve tried to register!" # ] # ], # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "groonga", # 2 # ], # [ # "travel", # 1 # ] # ], # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "charlie", # 2 # ], # [ # "bob", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query searches comments which are posted within 20 km from Central Park in city of New York. .sp As specified range is 20 km, all comments with location are collected. You know that search results contain 2 #groonga hash tags and one #travel hash tag, and bob and charlie posted 2 comments. .SS Search comments by keyword .sp In this section, we search comments which contains specific keyword. And more, Let\(aqs calculate the value of \fI_score\fP which is described at \fBsearch\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Comments \-\-query comment:@Now \-\-output_columns comment,_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "comment", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga", # 1 # ], # [ # "I\(aqm at the Museum of Modern Art in NY now!", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp By using \(aqNow\(aq as a keyword, above query returns 2 comments. It also contains count of \(aqNow\(aq as the value of \fI_score\fP\&. .SS Search comments by keyword and geolocation .sp In this section, we search comments by specific keyword and geolocation. By using \fI\-\-query\fP and \fI\-\-filter\fP option, following query returns records which are matched to both conditions. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Comments \-\-query comment:@New \-\-filter \(aqgeo_in_circle(location,"146867000x\-266280000",20000)\(aq \-\-output_columns posted_by.name,comment \-\-drilldown hash_tags,posted_by # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "posted_by.name", # "ShortText" # ], # [ # "comment", # "ShortText" # ] # ], # [ # "Bob", # "I\(aqm come at city of New York for development camp! #groonga #travel" # ] # ], # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "groonga", # 1 # ], # [ # "travel", # 1 # ] # ], # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "bob", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It returns 1 comment which meets both condition. It also returns result of drilldown. There is 1 comment which is commented by Bob. .SS Search comments by hash tags .sp In this section, we search comments which contains specific hash tags. Let\(aqs use reverse resolution of reference relationships. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Comments \-\-query hash_tags:@groonga \-\-output_columns posted_by.name,comment \-\-drilldown posted_by # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "posted_by.name", # "ShortText" # ], # [ # "comment", # "ShortText" # ] # ], # [ # "Bob", # "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga" # ], # [ # "Bob", # "I\(aqm come at city of New York for development camp! #groonga #travel" # ] # ], # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "bob", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query returns 2 comments which contains #groonga hash tag. It also returns result of drilldown grouped by person who posted it. It shows that there are 2 comments. Bob commented it. .SS Search comments by user id .sp In this section, we search comments which are posted by specific user. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Comments \-\-query posted_by:bob \-\-output_columns comment \-\-drilldown hash_tags # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "comment", # "ShortText" # ] # ], # [ # "First post. test,test..." # ], # [ # "@alice Thanks!" # ], # [ # "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga" # ], # [ # "I\(aqm come at city of New York for development camp! #groonga #travel" # ] # ], # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "groonga", # 2 # ], # [ # "travel", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query returns 4 comments which are posted by Bob. It also returns result of drilldown by hash tags. There are 2 comments which contains #groonga, and 1 comment which contains #travel as hash tag. .SS Search user\(aqs favorite comments .sp In this section, we search user\(aqs favorite comments. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-table Users \-\-query _key:bob \-\-output_columns favorites.posted_by,favorites.comment # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "favorites.posted_by", # "Users" # ], # [ # "favorites.comment", # "ShortText" # ] # ], # [ # [ # "alice", # "charlie" # ], # [ # "I\(aqve created micro\-blog!", # "@alice @bob I\(aqve tried to register!" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query returns Bob\(aqs favorite comments. .SS Search comments by posted time .sp In this section, we search comments by posted time. See type of \fITime\fP in \fBdata\fP\&. .sp Let\(aqs search comments that posted time are older than specified time. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Comments \-\-filter \(aqlast_modified<=1268802000\(aq \-\-output_columns posted_by.name,comment,last_modified \-\-drilldown hash_tags,posted_by # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "posted_by.name", # "ShortText" # ], # [ # "comment", # "ShortText" # ], # [ # "last_modified", # "Time" # ] # ], # [ # "Alice", # "I\(aqve created micro\-blog!", # 1268795100.0 # ], # [ # "Bob", # "First post. test,test...", # 1268794800.0 # ], # [ # "Alice", # "@bob Welcome!!!", # 1268795100.0 # ], # [ # "Bob", # "@alice Thanks!", # 1268798400.0 # ], # [ # "Bob", # "I\(aqve just used \(aqTry\-Groonga\(aq now! #groonga", # 1268802000.0 # ] # ], # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "groonga", # 1 # ] # ], # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_nsubrecs", # "Int32" # ] # ], # [ # "alice", # 2 # ], # [ # "bob", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query returns 5 comments which are older than 2010/03/17 14:00:00. It also returns result of drilldown by posted person. There are 2 comments by Alice, 3 comments by Bob. .SS Query expansion .sp Groonga accepts \fBquery_expander\fP parameter for \fB/reference/commands/select\fP command. It enables you to extend your query string. .sp For example, if user searches "theatre" instead of "theater", query expansion enables to return search results of "theatre OR theater". This kind of way reduces search leakages. This is what really user wants. .SS Preparation .sp To use query expansion, you need to create table which stores documents, synonym table which stores query string and replacement string. In synonym table, primary key represents original string, the column of ShortText represents modified string. .sp Let\(aqs create document table and synonym table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Doc TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Doc body COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Term TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Term Doc_body COLUMN_INDEX|WITH_POSITION Doc body # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Synonym TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Synonym body COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Doc [ {"_key": "001", "body": "Play all night in this theater."}, {"_key": "002", "body": "theatre is British spelling."}, ] # [[0, 1337566253.89858, 0.000355720520019531], 2] load \-\-table Synonym [ {"_key": "theater", "body": "(theater OR theatre)"}, {"_key": "theatre", "body": "(theater OR theatre)"}, ] # [[0, 1337566253.89858, 0.000355720520019531], 2] .ft P .fi .UNINDENT .UNINDENT .sp In this case, it doesn\(aqt occur search leakage because it creates synonym table which accepts "theatre" and "theater" as query string. .SS Search .sp Then, let\(aqs use prepared synonym table. First, use select command without \fBquery_expander\fP parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Doc \-\-match_columns body \-\-query "theater" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "body", # "ShortText" # ] # ], # [ # 1, # "001", # "Play all night in this theater." # ] # ] # ] # ] select Doc \-\-match_columns body \-\-query "theatre" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "body", # "ShortText" # ] # ], # [ # 2, # "002", # "theatre is British spelling." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Above query returns the record which completely equal to query string. .sp Then, use \fBquery_expander\fP parameter against \fBbody\fP column of \fBSynonym\fP table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Doc \-\-match_columns body \-\-query "theater" \-\-query_expander Synonym.body # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "body", # "ShortText" # ] # ], # [ # 1, # "001", # "Play all night in this theater." # ], # [ # 2, # "002", # "theatre is British spelling." # ] # ] # ] # ] select Doc \-\-match_columns body \-\-query "theatre" \-\-query_expander Synonym.body # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "body", # "ShortText" # ] # ], # [ # 1, # "001", # "Play all night in this theater." # ], # [ # 2, # "002", # "theatre is British spelling." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp In which cases, query string is replaced to "(theater OR theatre)", thus synonym is considered for full text search. .SH SUGGEST .sp Groonga has the suggest feature. This section describes how to use it and how it works. .SS Introduction .sp The suggest feature in Groonga provides the following features: .INDENT 0.0 .IP \(bu 2 Completion .IP \(bu 2 Correction .IP \(bu 2 Suggestion .UNINDENT .SS Completion .sp Completion helps user input. If user inputs a partial word, Groonga can return complete words from registered words. .sp For example, there are registered words: .INDENT 0.0 .IP \(bu 2 "groonga" .IP \(bu 2 "complete" .IP \(bu 2 "correction" .IP \(bu 2 "suggest" .UNINDENT .sp An user inputs "co" and groonga returns "complete" and "correction" because they starts with "co". .sp An user inputs "sug" and groonga returns "suggest" because "suggest" starts with "sug". .sp An user inputs "ab" and groonga returns nothing because no word starts with "ab". .SS Correction .sp Correction also helps user input. If user inputs a wrong word, groonga can return correct words from registered correction pairs. .sp For example, there are registered correction pairs: .TS center; |l|l|. _ T{ wrong word T} T{ correct word T} _ T{ grroonga T} T{ groonga T} _ T{ gronga T} T{ groonga T} _ T{ gronnga T} T{ groonga T} _ .TE .sp An user inputs "gronga" and groonga returns "groonga" because "gronga" is in wrong word and corresponding correct word is "groonga". .sp An user inputs "roonga" and groonga returns nothing because "roonga" isn\(aqt in wrong word. .SS Suggestion .sp Suggestion helps that user filters many found documents. If user inputs a query, groonga can return new queries that has more additional keywords from registered related query pairs. .sp For example, there are registered related query pairs: .TS center; |l|l|. _ T{ keyword T} T{ related query T} _ T{ groonga T} T{ groonga search engine T} _ T{ search T} T{ Google search T} _ T{ speed T} T{ groonga speed T} _ .TE .sp An user inputs "groonga" and groonga returns "groonga search engine" because "groonga" is in keyword column and related query column is "groonga search engine". .sp An user inputs "MySQL" and groonga returns nothing because "MySQL" isn\(aqt in keyword column values. .SS Learning .sp The suggest feature requires registered data before using the feature. Those data can be registered from user inputs. Gronnga\-suggest\-httpd and groonga\-suggest\-learner commands are provided for the propose. .SS Tutorial .sp TODO... .SS Completion .sp This section describes about the following completion features: .INDENT 0.0 .IP \(bu 2 How it works .IP \(bu 2 How to use .IP \(bu 2 How to learn .UNINDENT .SS How it works .sp The completion feature uses three searches to compute completed words: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Prefix RK search against registered words. .IP 2. 3 Cooccurrence search against learned data. .IP 3. 3 Prefix search against registered words. (optional) .UNINDENT .UNINDENT .UNINDENT .SS Prefix RK search .sp RK means Romaji and Katakana. Prefix RK search can find registered words that start with user\(aqs input by romaji, katakana or hiragana. It\(aqs useful for searching in Japanese. .sp For example, there is a registered word "日本". And "ニホン" (it must be katakana) is registered as its reading. An user can find "日本" by "ni", "二" or "に". .sp If you create dataset which is named as example by \fB/reference/executables/groonga\-suggest\-create\-dataset\fP command, you can update pairs of registered word and its reading by loading data to \(aq_key\(aq and \(aqkana\(aq column of item_example table explicitly for prefix RK search. .SS Cooccurrence search .sp Cooccurrence search can find registered words from user\(aqs partial input. It uses user input sequences that will be learned from query logs, access logs and so on. .sp For example, there is the following user input sequence: .TS center; |l|l|. _ T{ input T} T{ submit T} _ T{ s T} T{ no T} _ T{ se T} T{ no T} _ T{ sea T} T{ no T} _ T{ sear T} T{ no T} _ T{ searc T} T{ no T} _ T{ search T} T{ yes T} _ T{ e T} T{ no T} _ T{ en T} T{ no T} _ T{ eng T} T{ no T} _ T{ engi T} T{ no T} _ T{ engin T} T{ no T} _ T{ engine T} T{ no T} _ T{ enginen T} T{ no (typo!) T} _ T{ engine T} T{ yes T} _ .TE .sp Groonga creates the following completion pairs: .TS center; |l|l|. _ T{ input T} T{ completed word T} _ T{ s T} T{ search T} _ T{ se T} T{ search T} _ T{ sea T} T{ search T} _ T{ sear T} T{ search T} _ T{ searc T} T{ search T} _ T{ e T} T{ engine T} _ T{ en T} T{ engine T} _ T{ eng T} T{ engine T} _ T{ engi T} T{ engine T} _ T{ engin T} T{ engine T} _ T{ engine T} T{ engine T} _ T{ enginen T} T{ engine T} _ .TE .sp All user not\-submitted inputs (e.g. "s", "se" and so on) before each an user submission maps to the submitted input (e.g. "search"). .sp To be precise, this description isn\(aqt correct because it omits about time stamp. Groonga doesn\(aqt case about "all user not\-submitted inputs before each an user submission". Groonga just case about "all user not\-submitted inputs within a minute from an user submission before each an user submission". Groonga doesn\(aqt treat user inputs before a minute ago. .sp If an user inputs "sea" and cooccurrence search returns "search" because "sea" is in input column and corresponding completed word column value is "search". .SS Prefix search .sp Prefix search can find registered word that start with user\(aqs input. This search doesn\(aqt care about romaji, katakana and hiragana not like Prefix RK search. .sp This search isn\(aqt always ran. It\(aqs just ran when it\(aqs requested explicitly or both prefix RK search and cooccurrence search return nothing. .sp For example, there is a registered word "search". An user can find "search" by "s", "se", "sea", "sear", "searc" and "search". .SS How to use .sp Groonga provides \fB/reference/commands/suggest\fP command to use completion. \fI\-\-type complete\fP option requests completion. .sp For example, here is an command to get completion results by "en": .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query en # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "engine", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS How it learns .sp Cooccurrence search uses learned data. They are based on query logs, access logs and so on. To create learned data, groonga needs user input sequence with time stamp and user submit input with time stamp. .sp For example, an user wants to search by "engine". The user inputs the query with the following sequence: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 2011\-08\-10T13:33:23+09:00: e .IP 2. 3 2011\-08\-10T13:33:23+09:00: en .IP 3. 3 2011\-08\-10T13:33:24+09:00: eng .IP 4. 3 2011\-08\-10T13:33:24+09:00: engi .IP 5. 3 2011\-08\-10T13:33:24+09:00: engin .IP 6. 3 2011\-08\-10T13:33:25+09:00: engine (submit!) .UNINDENT .UNINDENT .UNINDENT .sp Groonga can be learned from the input sequence by the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950803.86057, "item": "e"}, {"sequence": "1", "time": 1312950803.96857, "item": "en"}, {"sequence": "1", "time": 1312950804.26057, "item": "eng"}, {"sequence": "1", "time": 1312950804.56057, "item": "engi"}, {"sequence": "1", "time": 1312950804.76057, "item": "engin"}, {"sequence": "1", "time": 1312950805.86057, "item": "engine", "type": "submit"} ] .ft P .fi .UNINDENT .UNINDENT .SS How to update RK reading data .sp Groonga requires registered word and its reading for RK search, so load such data in the advance. .sp Here is the example to register "日本" which means Japanese in english. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950805.86058, "item": "日本", "type": "submit"} ] # [[0, 1337566253.89858, 0.000355720520019531], 1] .ft P .fi .UNINDENT .UNINDENT .sp Here is the example to update RK data to complete "日本". .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table item_query [ {"_key":"日本", "kana":["ニホン", "ニッポン"]} ] # [[0, 1337566253.89858, 0.000355720520019531], 1] .ft P .fi .UNINDENT .UNINDENT .sp Then you can complete registered word "日本" by RK input \- "nihon". .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query nihon # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "日本", # 2 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .sp Without loading above RK data, you can\(aqt complete registered word "日本" by query \- "nihon". .sp As the column type of item_query table is VECTOR_COLUMN, you can register multiple readings for registered word. .sp This is the reason that you can also complete the registered word "日本" by query \- "nippon". .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query nippon # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "日本", # 2 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .sp This feature is very convenient because you can search registered word even though Japanese IM is disabled. .sp If there are multiple candidates as completed result, you can customize priority to set the value of "boost" column in item_query table. .sp Here is the example to customize priority for RK search. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950805.86059, "item": "日本語", "type": "submit"} {"sequence": "1", "time": 1312950805.86060, "item": "日本人", "type": "submit"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] load \-\-table item_query [ {"_key":"日本語", "kana":"ニホンゴ"} {"_key":"日本人", "kana":"ニホンジン"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query nihon # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "日本", # 2 # ], # [ # "日本人", # 2 # ], # [ # "日本語", # 2 # ] # ] # } # ] load \-\-table item_query [ {"_key":"日本人", "boost": 100}, ] # [[0, 1337566253.89858, 0.000355720520019531], 1] suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query nihon # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 3 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "日本人", # 102 # ], # [ # "日本", # 2 # ], # [ # "日本語", # 2 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS Correction .sp This section describes about the following correction features: .INDENT 0.0 .IP \(bu 2 How it works .IP \(bu 2 How to use .IP \(bu 2 How to learn .UNINDENT .SS How it works .sp The correction feature uses three searches to compute corrected words: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Cooccurrence search against learned data. .IP 2. 3 Similar search against registered words. (optional) .UNINDENT .UNINDENT .UNINDENT .SS Cooccurrence search .sp Cooccurrence search can find registered words from user\(aqs wrong input. It uses user submit sequences that will be learned from query logs, access logs and so on. .sp For example, there are the following user submissions: .TS center; |l|l|. _ T{ query T} T{ time T} _ T{ serach (typo!) T} T{ 2011\-08\-10T22:20:50+09:00 T} _ T{ search (fixed!) T} T{ 2011\-08\-10T22:20:52+09:00 T} _ .TE .sp Groonga creates the following correction pair from the above submissions: .TS center; |l|l|. _ T{ input T} T{ corrected word T} _ T{ serach T} T{ search T} _ .TE .sp Groonga treats continuous submissions within a minute as input correction by user. Not submitted user input sequence between two submissions isn\(aqt used as learned data for correction. .sp If an user inputs "serach" and cooccurrence search returns "search" because "serach" is in input column and corresponding corrected word column value is "search". .SS Similar search .sp Similar search can find registered words that has one or more the same tokens as user input. TokenBigram tokenizer is used for tokenization because suggest dataset schema created by \fB/reference/executables/groonga\-suggest\-create\-dataset\fP uses TokenBigram tokenizer as the default tokenizer. .sp For example, there is a registered query "search engine". An user can find "search engine" by "web search service", "sound engine" and so on. Because "search engine" and "web search engine" have the same token "search" and "search engine" and "sound engine" have the same token "engine". .sp "search engine" is tokenized to "search" and "engine" tokens. (Groonga\(aqs TokenBigram tokenizer doesn\(aqt tokenize two characters for continuous alphabets and continuous digits for reducing search noise. TokenBigramSplitSymbolAlphaDigit tokenizer should be used to ensure tokenizing to two characters.) "web search service" is tokenized to "web", "search" and "service". "sound engine" is tokenized to "sound" and "engine". .SS How to use .sp Groonga provides \fB/reference/commands/suggest\fP command to use correction. \fI\-\-type correct\fP option requests corrections. .sp For example, here is an command to get correction results by "saerch": .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types correction \-\-frequency_threshold 1 \-\-query saerch # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "correct": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS How it learns .sp Cooccurrence search uses learned data. They are based on query logs, access logs and so on. To create learned data, groonga needs user submit inputs with time stamp. .sp For example, an user wants to search by "search" but the user has typo "saerch" before inputs the correct query. The user inputs the query with the following sequence: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 2011\-08\-10T13:33:23+09:00: s .IP 2. 3 2011\-08\-10T13:33:23+09:00: sa .IP 3. 3 2011\-08\-10T13:33:24+09:00: sae .IP 4. 3 2011\-08\-10T13:33:24+09:00: saer .IP 5. 3 2011\-08\-10T13:33:24+09:00: saerc .IP 6. 3 2011\-08\-10T13:33:25+09:00: saerch (submit!) .IP 7. 3 2011\-08\-10T13:33:29+09:00: serch (correcting...) .IP 8. 3 2011\-08\-10T13:33:30+09:00: search (submit!) .UNINDENT .UNINDENT .UNINDENT .sp Groonga can be learned from the input sequence by the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950803.86057, "item": "s"}, {"sequence": "1", "time": 1312950803.96857, "item": "sa"}, {"sequence": "1", "time": 1312950804.26057, "item": "sae"}, {"sequence": "1", "time": 1312950804.56057, "item": "saer"}, {"sequence": "1", "time": 1312950804.76057, "item": "saerc"}, {"sequence": "1", "time": 1312950805.76057, "item": "saerch", "type": "submit"}, {"sequence": "1", "time": 1312950809.76057, "item": "serch"}, {"sequence": "1", "time": 1312950810.86057, "item": "search", "type": "submit"} ] .ft P .fi .UNINDENT .UNINDENT .SS Suggestion .sp This section describes about the following completion features: .INDENT 0.0 .IP \(bu 2 How it works .IP \(bu 2 How to use .IP \(bu 2 How to learn .UNINDENT .SS How it works .sp The suggestion feature uses a search to compute suggested words: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Cooccurrence search against learned data. .UNINDENT .UNINDENT .UNINDENT .SS Cooccurrence search .sp Cooccurrence search can find related words from user\(aqs input. It uses user submissions that will be learned from query logs, access logs and so on. .sp For example, there are the following user submissions: .TS center; |l|. _ T{ query T} _ T{ search engine T} _ T{ web search realtime T} _ .TE .sp Groonga creates the following suggestion pairs: .TS center; |l|l|. _ T{ input T} T{ suggested words T} _ T{ search T} T{ search engine T} _ T{ engine T} T{ search engine T} _ T{ web T} T{ web search realtime T} _ T{ search T} T{ web search realtime T} _ T{ realtime T} T{ web search realtime T} _ .TE .sp Those pairs are created by the following steps: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Tokenizes user input query by TokenDelimit tokenizer that uses a space as token delimiter. (e.g. "search engine" is tokenized to two tokens "search" and "engine".) .IP 2. 3 Creates a pair that is consists of a token and original query for each token. .UNINDENT .UNINDENT .UNINDENT .sp If an user inputs "search" and cooccurrence search returns "search engine" and "web search realtime" because "search" is in two input columns and corresponding suggested word columns have "search engine" and "web search realtime". .SS How to use .sp Groonga provides \fB/reference/commands/suggest\fP command to use suggestion. \fI\-\-type suggest\fP option requests suggestion .sp For example, here is an command to get suggestion results by "search": .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types suggest \-\-frequency_threshold 1 \-\-query search # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "suggest": [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search engine", # 1 # ], # [ # "web search realtime", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS How it learns .sp Cooccurrence search uses learned data. They are based on query logs, access logs and so on. To create learned data, groonga needs user input sequence with time stamp and user submit input with time stamp. .sp For example, an user wants to search by "engine". The user inputs the query with the following sequence: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 2011\-08\-10T13:33:23+09:00: search engine (submit) .IP 2. 3 2011\-08\-10T13:33:28+09:00: web search realtime (submit) .UNINDENT .UNINDENT .UNINDENT .sp Groonga can be learned from the submissions by the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950803.86057, "item": "search engine", "type": "submit"}, {"sequence": "1", "time": 1312950808.86057, "item": "web search realtime", "type": "submit"} ] .ft P .fi .UNINDENT .UNINDENT .SS How to extract learning data .sp The learning data is stored into item_DATASET and pair_DATASET tables. By using select command for such tables, you can all extract learing data. .sp Here is the query to extract all learning data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select item_DATASET \-\-limit \-1 select pair_DATASET \-\-filter \(aqfreq0 > 0 || freq1 > 0 || freq2 > 0\(aq \-\-limit \-1 .ft P .fi .UNINDENT .UNINDENT .sp Without \(aq\-\-limit \-1\(aq, you can\(aqt get all data. In pair table, the valid value of freq0, freq1 and freq2 column must be larger than 0. .sp Don\(aqt execute above query via HTTP request because enourmous number of records are fetched. .SH GEOLOCATION SEARCH .sp Groonga supports geolocation search. It uses index for search. It means that you can search by geolocation fast like fulltext search. .SS Supported features .sp Groonga supports only point as data type. Line, surface and so on aren\(aqt supported yet. Here is a feature list: .INDENT 0.0 .IP 1. 3 Groonga can store a point to a column. .IP 2. 3 Groonga can search records that have a point in the specified rectangle. .IP 3. 3 Groonga can search records that have a point in the specified circle. .IP 4. 3 Groonga can calculate distance between two points. .IP 5. 3 Groonga can sort records by distance from the specified point in ascending order. .UNINDENT .sp Here are use cases for Groonga\(aqs geolocation search: .INDENT 0.0 .IP \(bu 2 You list McDonald\(aqs around a station. .IP \(bu 2 You list KFS around the current location sort by distance from the current location in ascending order with distance. .UNINDENT .sp Here are not use cases: .INDENT 0.0 .IP \(bu 2 You search McDonald\(aqs in a city. (Groonga doesn\(aqt support geolocation search by a shape except a rectangle and a circle.) .IP \(bu 2 You store a region instead of a point as a lake record. (A column can\(aqt has geolocation data except a point.) .UNINDENT .sp The following figures show about Groonga\(aqs geolocation search features. .sp Here is a figure that only has records. A black point describes a record. The following figures shows how records are treated. [image: only records] [image] .sp Coming soon... .SH SERVER .SS Server packages .sp The package \fBgroonga\fP is the mininum set of fulltext search engine. If you want to use groonga for server use, you can install additional preconfigured packages. .sp There are three packages for server use. .INDENT 0.0 .IP \(bu 2 \fBgroonga\-httpd\fP (nginx and HTTP protocol based server package) .IP \(bu 2 \fBgroonga\-server\-http\fP (simple HTTP protocol based server package) .IP \(bu 2 \fBgroonga\-server\-gqtp\fP (\fB/spec/gqtp\fP protocol based server package) .UNINDENT .sp There is the reason why groonga supports not only GQTP but also two HTTP server packages. \fB/spec/gqtp\fP \- Groonga Query Transfer Protocol is desined to reduce overheads and improve performance. But, GQTP is less support of client library than HTTP protocol does. As HTTP is matured protocol, you can take advantage of existing tool and there are many client library (See \fI\%related projects\fP for details). If you use \fBgroonga\-httpd\fP package, you can also take benefits of nginx functionality. .sp We recommend to use \fBgroonga\-server\-http\fP at first, then if you want to use more fullfilling functionality, use \fBgroonga\-httpd\fP package. If you have performance issues which is derived from protocol overheads, consider to use \fBgroonga\-server\-gqtp\fP\&. .INDENT 0.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is a conflict between \fBgroonga\-httpd\fP and \fBgroonga\-server\-http\fP package because of port number. See \fB/server/http/comparison\fP if you want to know which package meets your demands. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS groonga\-httpd .sp \fBgroonga\-httpd\fP is a nginx and HTTP protocol based server package. .sp Preconfigured setting: .TS center; |l|l|. _ T{ Item T} T{ Default value T} _ T{ Port number T} T{ 10041 T} _ T{ Access log path T} T{ /var/log/groonga/httpd/acccess.log T} _ T{ Error log path T} T{ /var/log/groonga/http\-query.log T} _ T{ Database T} T{ /var/lib/groonga/db/* T} _ T{ Configuration file T} T{ /etc/groonga/httpd/groonga\-httpd.conf T} _ .TE .SS Start HTTP server .sp Starting groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-httpd start .ft P .fi .UNINDENT .UNINDENT .sp Starting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl start groonga\-httpd .ft P .fi .UNINDENT .UNINDENT .SS Stop HTTP server .sp Stopping groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-httpd stop .ft P .fi .UNINDENT .UNINDENT .sp Starting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl stop groonga\-httpd .ft P .fi .UNINDENT .UNINDENT .SS Restart HTTP server .sp Restarting groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-httpd restart .ft P .fi .UNINDENT .UNINDENT .sp Restarting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl restart groonga\-httpd .ft P .fi .UNINDENT .UNINDENT .SS groonga\-server\-http .sp \fBgroonga\-server\-http\fP is a simple HTTP protocol based server package. .sp Preconfigured setting: .TS center; |l|l|. _ T{ Item T} T{ Default value T} _ T{ Port number T} T{ 10041 T} _ T{ \fIprocess\-log\fP T} T{ /var/log/groonga/groonga\-http.log T} _ T{ \fIquery\-log\fP T} T{ /var/log/groonga/http\-query.log T} _ T{ Database T} T{ /var/lib/groonga/db/* T} _ .TE .sp Configuration file for server setting (Debian/Ubuntu): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/default/groonga/groonga\-server\-http .ft P .fi .UNINDENT .UNINDENT .sp Configuration file for server setting (CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/sysconfig/groonga\-server\-http .ft P .fi .UNINDENT .UNINDENT .SS Start HTTP server .sp Starting groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-http start .ft P .fi .UNINDENT .UNINDENT .sp Starting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl start groonga\-server\-http .ft P .fi .UNINDENT .UNINDENT .SS Stop HTTP server .sp Stopping groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-http stop .ft P .fi .UNINDENT .UNINDENT .sp Stopping groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl stop groonga\-server\-http .ft P .fi .UNINDENT .UNINDENT .SS Restart HTTP server .sp Restarting groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-http restart .ft P .fi .UNINDENT .UNINDENT .sp Restarting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl restart groonga\-server\-http .ft P .fi .UNINDENT .UNINDENT .SS groonga\-server\-gqtp .sp \fBgroonga\-server\-gqtp\fP is a \fB/spec/gqtp\fP protocol based server package. .TS center; |l|l|. _ T{ Item T} T{ Default value T} _ T{ Port number T} T{ 10043 T} _ T{ \fIprocess\-log\fP T} T{ /var/log/groonga/groonga\-gqtp.log T} _ T{ \fIquery\-log\fP T} T{ /var/log/groonga/gqtp\-query.log T} _ T{ Database T} T{ /var/lib/groonga/db/* T} _ .TE .sp Configuration file for server setting (Debian/Ubuntu): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/default/groonga/groonga\-server\-gqtp .ft P .fi .UNINDENT .UNINDENT .sp Configuration file for server setting (CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/sysconfig/groonga\-server\-gqtp .ft P .fi .UNINDENT .UNINDENT .SS Start GQTP server .sp Starting groonga GQTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-gqtp start .ft P .fi .UNINDENT .UNINDENT .sp Starting groonga GQTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl start groonga\-server\-gqtp .ft P .fi .UNINDENT .UNINDENT .SS Stop GQTP server .sp Stopping groonga GQTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-http stop .ft P .fi .UNINDENT .UNINDENT .sp Stopping groonga GQTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl stop groonga\-server\-gqtp .ft P .fi .UNINDENT .UNINDENT .SS Restart GQTP server .sp Restarting groonga HTTP server(Debian/Ubuntu/CentOS): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo service groonga\-server\-gqtp restart .ft P .fi .UNINDENT .UNINDENT .sp Restarting groonga HTTP server(Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo systemctl restart groonga\-server\-gqtp .ft P .fi .UNINDENT .UNINDENT .SS GQTP .sp TODO .sp See \fB/reference/executables/groonga\fP\&. .SS HTTP .sp Groonga provides two HTTP server implementations. .INDENT 0.0 .IP \(bu 2 \fBhttp/groonga\fP .IP \(bu 2 \fBhttp/groonga\-httpd\fP .UNINDENT .sp \fBhttp/groonga\fP is a simple implemntation. It is fast but doesn\(aqt have many HTTP features. It is convenient to try groonga because it requires just a few command line options to run. .sp \fBhttp/groonga\-httpd\fP is a \fI\%nginx\fP based implementation. It is also fast and has many HTTP features. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBhttp/groonga\-httpd\fP is still experimental. .UNINDENT .UNINDENT .SS Comparison .sp There are many differences between \fBgroonga\fP and \fBgroonga\-httpd\fP\&. Here is a comparison table. .TS center; |l|l|l|. _ T{ T} T{ groonga T} T{ groonga\-httpd T} _ T{ Performance T} T{ o T} T{ o T} _ T{ Using multi CPU cores T} T{ o (by multi threading) T} T{ o (by multi process) T} _ T{ Configuration file T} T{ optional T} T{ required T} _ T{ Custom prefix path T} T{ x T} T{ o T} _ T{ Custom command version T} T{ o T} T{ x (comming soon) T} _ T{ Multi databases T} T{ x T} T{ o T} _ T{ Authentication T} T{ x T} T{ o T} _ T{ Gzip compression T} T{ x T} T{ o T} _ T{ POST T} T{ o T} T{ o T} _ T{ HTTPS T} T{ x T} T{ o T} _ T{ Access log T} T{ x T} T{ o T} _ T{ Upgrading without downtime T} T{ x T} T{ o T} _ .TE .SS Performance .sp Both \fBgroonga\fP and \fBgroonga\-httpd\fP are very fast. They can work with the same throughput. .SS Using multi CPU cores .sp Groonga scales on multi CPU cores. \fBgroonga\fP scales by multi threading. \fBgroonga\-httpd\fP scales by multi processes. .sp \fBgroonga\fP uses the same number of threads as CPU cores by default. If you have 8 CPU cores, 8 threads are used by default. .sp \fBgroonga\-httpd\fP uses 1 process by default. You need to set \fI\%worker_processes\fP directive to use CPU cores. If you have 8 CPU cores, specify \fBworker_processes 8\fP in configuration file like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C worker_processes 8; http { # ... } .ft P .fi .UNINDENT .UNINDENT .SS Configuration file .sp \fBgroonga\fP can work without configuration file. All configuration items such as port number and the max number of threads can be specified by command line. Configuration file is also used to specify configuration items. .sp It\(aqs very easy to run groonga HTTP server because \fBgroonga\fP requires just a few options to run. Here is the most simple command line to start HTTP server by \fBgroonga\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-\-protocol http \-d /PATH/TO/DATABASE .ft P .fi .UNINDENT .UNINDENT .sp \fBgroonga\-httpd\fP requires configuration file to run. Here is the most simple configuration file to start HTTP server by \fBgroonga\-httpd\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; location /d/ { groonga on; groonga_database /PATH/TO/DATABASE; } } } .ft P .fi .UNINDENT .UNINDENT .SS Custom prefix path .sp \fBgroonga\fP accepts a path that starts with \fB/d/\fP as command URL such as \fBhttp://localhost:10041/d/status\fP\&. You cannot change the prefix path \fB/d/\fP\&. .sp \fBgroonga\-httpd\fP can custom prefix path. For example, you can use \fBhttp://localhost:10041/api/status\fP as command URL. Here is a sample configuration to use \fB/api/\fP as prefix path: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; location /api/ { # <\- change this groonga on; groonga_database /PATH/TO/DATABASE; } } } .ft P .fi .UNINDENT .UNINDENT .SS Custom command version .sp Groonga has \fB/reference/command/command_version\fP mechanism. It is for upgrading groonga commands with backward compatibility. .sp \fBgroonga\fP can change the default command veresion by \fB\-\-default\-command\-version\fP option. Here is a sample command line to use command version 2 as the default command version: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-\-protocol http \-\-default\-command\-version 2 \-d /PATH/TO/DATABASE .ft P .fi .UNINDENT .UNINDENT .sp \fBgroonga\-httpd\fP cannot custom the default command version yet. But it will be supported soon. If it is supported, you can provides different command version groonga commands in the same \fBgroonga\-httpd\fP process. Here is a sample configuration to provide command version 1 commands under \fB/api/1/\fP and command version 2 comamnds under \fB/api/2/\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; groonga_database /PATH/TO/DATABASE; location /api/1/ { groonga on; groogna_default_command_version 1; } location /api/2/ { groonga on; groogna_default_command_version 2; } } } .ft P .fi .UNINDENT .UNINDENT .SS Multi databases .sp \fBgroonga\fP can use only one database in a process. .sp \fBgroonga\-httpd\fP can use one or more databases in a process. Here is a sample configuration to provide \fB/tmp/db1\fP database under \fB/db1/\fP path and \fB/tmp/db2\fP database under \fB/db2/\fP path: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; location /db1/ { groonga on; groonga_database /tmp/db1; } location /db2/ { groonga on; groonga_database /tmp/db2; } } } .ft P .fi .UNINDENT .UNINDENT .SS Authentication .sp HTTP supports authentications such as basic authentication and digest authentication. It can be used for restricting use of danger command such as \fB/reference/commands/shutdown\fP\&. .sp \fBgroonga\fP doesn\(aqt support any authentications. To restrict use of danger command, other tools such as iptables and reverse proxy are needed. .sp \fBgroonga\-httpd\fP supports basic authentication. Here is a sample configuration to restrict use of \fB/reference/commands/shutdown\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; groonga_database /PATH/TO/DATABASE; location /d/shutdown { groonga on; auth_basic "manager is required!"; auth_basic_user_file "/etc/managers.htpasswd"; } location /d/ { groonga on; } } } .ft P .fi .UNINDENT .UNINDENT .SS Gzip compression .sp HTTP supports response compression by gzip with \fBContent\-Encoding: gzip\fP response header. It can reduce network flow. It is useful for large search response. .sp \fBgroonga\fP doesn\(aqt support compression. To support compression, reverse proxy is needed. .sp \fBgroonga\-httpd\fP supports gzip compression. Here is a sample configuration to compress response by gzip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C events { } http { server { listen 10041; groonga_database /PATH/TO/DATABASE; location /d/ { groonga on; gzip on; gzip_types *; } } } .ft P .fi .UNINDENT .UNINDENT .sp Note that \fIgzip_types *\fP is specified. It\(aqs one of the important configuration. \fIgzip_types\fP specifies gzip target data formats by MIME types. \fBgroonga\-httpd\fP returns one of JSON, XML or MessagePack format data. But those formats aren\(aqt included in the default value of \fIgzip_types\fP\&. The default value of \fIgzip_types\fP is \fItext/html\fP\&. .sp To compress response data from \fBgroonga\-httpd\fP by gzip, you need to specify \fIgzip_types *\fP or \fIgzip_types application/json text/xml application/x\-msgpack\fP explicitly. \fIgzip_types *\fP is recommended. There are two reasons for it. The first, groonga may support more formats in the future. The second, all requests for the \fIlocation\fP are processed by groonga. You don\(aqt need to consider about other modules. .SS POST .sp You can load your data by POST JSON data. You need follow the following rules to use loading by POST. .INDENT 0.0 .IP \(bu 2 \fIContent\-Type\fP header value must be \fIapplication/json\fP\&. .IP \(bu 2 JSON data is sent as body. .IP \(bu 2 Table name is specified by query parameter such as \fBtable=NAME\fP\&. .UNINDENT .sp Here is an example curl command line that loads two users \fIalice\fP and \fIbob\fP to \fIUsers\fP table: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-\-data\-binary \(aq[{"_key": "alice"}, {"_key": "bob"}]\(aq \-H "Content\-Type: application/json" "http://localhost:10041/d/load?table=Users" .ft P .fi .UNINDENT .UNINDENT .SS HTTPS .sp TODO .SS Access log .sp TODO .SS Upgrading without downtime .sp TODO .SS groonga .sp TODO .SS groonga\-httpd .sp TODO .SH REFERENCE MANUAL .SS Executables .sp This section describes executable files provided by groonga package. .SS grnslap .SS 名前 .sp grnslap \- groongaプロセスの通信層のパフォーマンスをチェックするツール .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grnslap [options] [dest] .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp grnslapは、groongaプロセスに対してリクエストを多重に行い、パフォーマンスをチェックするためのツールです。 .sp Groonga独自プロトコルであるGQTPと、httpの両プロトコルでリクエストを行うことができます。また、リクエストの多重度を指定することができます。 .sp クエリの内容を標準入力から与えることができます。実稼動環境でのクエリパタンに近いクエリを標準入力に与えることによって、実稼動環境に近い状態での検証を行うことができます。 .sp 現在は、make installしてもインストールは行われない。 .SS オプション .INDENT 0.0 .TP .B \-P リクエストのプロトコルを指定します。 .sp \fIhttp\fP .INDENT 7.0 .INDENT 3.5 httpでリクエストします。対象のhttpのパス群(GETパラメータを含む)をLF区切り形式で標準入力に与えると、それらのパスに順次アクセスします。 .UNINDENT .UNINDENT .sp \fIgqtp\fP .INDENT 7.0 .INDENT 3.5 gqtpでリクエストします。gqtpのリクエストをLF区切り形式で標準入力に与えると、それらのリクエストを順次行います。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-m リクエストの多重度を指定します。初期値は10です。 .UNINDENT .SS 引数 .INDENT 0.0 .TP .B dest 接続先のホスト名とポート番号をを指定します(デフォルト値は\(aqlocalhost:10041\(aq)。ポート番号を指定しない場合には、10041が指定されたものとします。 .UNINDENT .SS サンプル .sp \fI\%http://localhost:10041/d/status\fP に、多重度100でリクエストを行う。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > yes /d/status | head \-n 100 | grnslap \-P http \-m 100 localhost:10041 2009\-11\-12 19:34:09.998696|begin: max_concurrency=100 max_tp=10000 2009\-11\-12 19:34:10.011208|end : n=100 min=46 max=382 avg=0 qps=7992.966190 etime=0.012511 .ft P .fi .UNINDENT .UNINDENT .SS groonga command .SS 名前 .sp groonga \- 列指向データベース機能を持つ全文検索エンジンソフトウェア .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga [options] [dest] [command [args]] .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groongaは列指向のデータベース機能を持つ高速でスケーラブルな全文検索エンジンです。 Groongaのデータベースは、groongaコマンドかCライブラリインタフェースを通して操作することができます。このマニュアルページでは、groongaコマンドの使い方について説明します。 .SS オプション .INDENT 0.0 .TP .B \-n 新たなデータベースを作成します。 .UNINDENT .INDENT 0.0 .TP .B \-c クライアントモードで実行します。 .UNINDENT .INDENT 0.0 .TP .B \-s サーバモードで実行します。 .UNINDENT .INDENT 0.0 .TP .B \-d デーモンモードで実行します。(forkする点がサーバモードと異なる) .UNINDENT .INDENT 0.0 .TP .B \-e, \-\-encoding データベースで使用する文字エンコーディング方式を指定します。新たなデータベースを作成する時のみ有効です。none, euc, utf8, sjis, latin, koi8rのいずれかが指定できます。 .UNINDENT .INDENT 0.0 .TP .B \-l, \-\-log\-level ログレベルを指定します。0〜8までの数値が指定可能で、数が大きいほど多くのログが出力されます。 .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-address Deprecated since version 1.2.2: Use \fI\-\-bind\-address\fP instead. .UNINDENT .INDENT 0.0 .TP .B \-\-bind\-address New in version 1.2.2. .sp サーバモードかデーモンモードで実行するとき、listenするアドレスを指定します。(デフォルトは \fIhostname\fP の返すホスト名) .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-port クライアント、サーバ、またはデーモンモードで使用するTCPポート番号。 (クライアントモードのデフォルトは10043番、サーバ、またはデーモンモードのデフォルトは、HTTPの場合、10041番、GQTPの場合、10043番) .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-server\-id サーバモードかデーモンモードで実行するとき、サーバのIDとなるアドレスを指定します。(デフォルトは\(gahostname\(gaの返すホスト名) .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help ヘルプメッセージを出力します。 .UNINDENT .INDENT 0.0 .TP .B \-\-document\-root httpサーバとしてgroongaを使用する場合に静的ページを格納するディレクトリを指定します。 .sp デフォルトでは、データベースを管理するための汎用的なページに対応するファイルが/usr/share/groonga/admin_html以下にインストールされます。このディレクトリをdocument\-rootオプションの値に指定して起動した場合、ウェブブラウザでhttp://hostname:port/index.htmlにアクセスすると、ウェブベースのデータベース管理ツールを使用できます。 .UNINDENT .INDENT 0.0 .TP .B \-\-protocol http,gqtpのいずれかを指定します。(デフォルトはgqtp) .UNINDENT .INDENT 0.0 .TP .B \-\-log\-path ログを出力するファイルのパスを指定します。(デフォルトは/var/log/groonga/groonga.logです) .UNINDENT .INDENT 0.0 .TP .B \-\-query\-log\-path クエリーログを出力するファイルのパスを指定します。(デフォルトでは出力されません) .UNINDENT .INDENT 0.0 .TP .B \-t, \-\-max\-threads 最大で利用するスレッド数を指定します。(デフォルトはマシンのCPUコア数と同じ数です) .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-path PIDを保存するパスを指定します。(デフォルトでは保存しません) .UNINDENT .INDENT 0.0 .TP .B \-\-config\-path 設定ファイルのパスを指定します。設定ファイルは以下のようなフォーマットになります。: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # \(aq#\(aq以降はコメント。 ; \(aq;\(aq以降もコメント。 # \(aqキー = 値\(aqでオプションを指定。 pid\-file = /var/run/groonga.pid # \(aq=\(aqの前後の空白はは無視される。↓は↑と同じ意味。 pid\-file=/var/run/groonga.pid # \(aqキー\(aqは\(aq\-\-XXX\(aqスタイルのオプション名と同じものが使える。 # 例えば、\(aq\-\-pid\-path\(aqに対応するキーは\(aqpid\-path\(aq。 # ただし、キーが\(aqconfig\-path\(aqのオプションは無視される。 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-cache\-limit キャッシュ数の最大値を指定します。(デフォルトは100です) .UNINDENT .INDENT 0.0 .TP .B \-\-default\-match\-escalation\-threshold 検索の挙動をエスカレーションする閾値を指定します。(デフォルトは0です) .UNINDENT .SS 引数 .INDENT 0.0 .TP .B dest 使用するデータベースのパス名を指定します。 .sp クライアントモードの場合は接続先のホスト名とポート番号を指定します(デフォルト値は\(aqlocalhost:10043\(aq)。ポート番号を指定しない場合には、10043が指定されたものとします。 .UNINDENT .INDENT 0.0 .TP .B command [args] スタンドアロンおよびクライアントモードの場合は、実行するコマンドとその引数をコマンドライン引数に指定できます。コマンドライン引数にcommandを与えなかった場合は、標準入力から一行ずつEOFに達するまでコマンド文字列を読み取り、順次実行します。 .UNINDENT .SS コマンド .sp groongaコマンドを通してデータベースを操作する命令をコマンドと呼びます。コマンドは主にC言語で記述され、groongaプロセスにロードすることによって使用できるようになります。 それぞれのコマンドは一意な名前と、0個以上の引数を持ちます。 .sp 引数は以下の2種類の方法のいずれかで指定することができます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 形式1: コマンド名 値1 値2,.. 形式2: コマンド名 \-\-引数名1 値1 \-\-引数名2 値2,.. .ft P .fi .UNINDENT .UNINDENT .sp 形式1でコマンドを実行する場合は、定義された順番で値を指定しなければならず、途中の引数の値を省略することはできません。形式2でコマンドを実行する場合は、「\-\-引数名」のように引数の名前を明示しなければならない代わりに、任意の順番で引数を指定することが可能で、途中の引数の指定を省略することもできます。 .sp 標準入力からコマンド文字列を与える場合は、コマンド名と引数名と値は、空白( )で区切ります。空白や、記号「"\(aq()」のうちいずれかを含む値を指定したい場合は、シングルクォート(\(aq)かダブルクォート(")で値を囲みます。値として指定する文字列の中では、改行文字は\(aqn\(aqに置き換えて指定します。また、引用符に使用した文字を値の中で指定する場合には、その文字の前にバックスラッシュ(\(aq\(aq) を指定します。バックスラッシュ文字自身を値として指定する場合には、その前にバックスラッシュを指定します。 .sp You can write command list with continuous line which is represented by \(aq\e\(aq character.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create \-\-name Terms \e \-\-flags TABLE_PAT_KEY \e \-\-key_type ShortText \e \-\-default_tokenizer TokenBigram .ft P .fi .UNINDENT .UNINDENT .SS 組み込みコマンド .sp 以下のコマンドは組み込みコマンドとして予め定義されています。 .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBstatus\fP groongaプロセスの状態を表示します。 .TP .B \fBtable_list\fP DBに定義されているテーブルのリストを表示します。 .TP .B \fBcolumn_list\fP テーブルに定義されているカラムのリストを表示します。 .TP .B \fBtable_create\fP DBにテーブルを追加します。 .TP .B \fBcolumn_create\fP テーブルにカラムを追加します。 .TP .B \fBtable_remove\fP DBに定義されているテーブルを削除します。 .TP .B \fBcolumn_remove\fP テーブルに定義されているカラムを削除します。 .TP .B \fBload\fP テーブルにレコードを挿入します。 .TP .B \fBselect\fP テーブルに含まれるレコードを検索して表示します。 .TP .B \fBdefine_selector\fP 検索条件をカスタマイズした新たな検索コマンドを定義します。 .TP .B \fBquit\fP データベースとのセッションを終了します。 .TP .B \fBshutdown\fP サーバ(デーモン)プロセスを停止します。 .TP .B \fBlog_level\fP ログ出力レベルを設定します。 .TP .B \fBlog_put\fP ログ出力を行います。 .TP .B \fBclearlock\fP ロックを解除します。 .UNINDENT .UNINDENT .UNINDENT .SS 例 .sp 新しいデータベースを作成します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-n /tmp/hoge.db quit % .ft P .fi .UNINDENT .UNINDENT .sp 作成済みのデータベースにテーブルを定義します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga /tmp/hoge.db table_create Table 0 ShortText [[0]] % .ft P .fi .UNINDENT .UNINDENT .sp サーバを起動します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-d /tmp/hoge.db % .ft P .fi .UNINDENT .UNINDENT .sp httpサーバとして起動します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-d \-p 80 \-\-protocol http \-\-document\-root /usr/share/groonga/admin_html /tmp/hoge.db % .ft P .fi .UNINDENT .UNINDENT .sp サーバに接続し、テーブル一覧を表示します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga \-c localhost table_list [[0],[["id","name","path","flags","domain"],[256,"Table","/tmp/hoge.db.0000100",49152,14]]] % .ft P .fi .UNINDENT .UNINDENT .SS groonga\-benchmark .SS 名前 .sp groonga\-benchmark \- groongaテストプログラム .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-benchmark [options...] [script] [db] .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp groonga\-benchmarkは、groonga汎用ベンチマークツールです。 .sp groongaを単独のプロセスとして利用する場合はもちろん、サーバプログラムとして利用する場合の動作確認や実行速度測定が可能です。 .sp groonga\-benchmark用のデータファイルは自分で作成することも既存のものを利用することもできます。既存のデータファイルは、ftp.groonga.orgから必要に応じダウンロードします。そのため、groonga及びgroonga\-benchmarkが動作し、インターネットに接続できる環境であればgroongaコマンドの知識がなくてもgroongaの動作を確認できます。 .sp 現在は、Linux 及びWindows上で動作します。make installしてもインストールは行われません。 .SS オプション .INDENT 0.0 .TP .B \-i, \-\-host 接続するgroongaサーバを、ipアドレスまたはホスト名で指定します。指定先にgroongaサーバが立ち上がっていない場合、接続不能となることに注意してください。このオプションを指定しない場合、groonga\-benchmarkは自動的にlocalhostのgroongaサーバを起動して接続します。 .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-port 自動的に起動するgroongaサーバ、または明示的に指定した接続先のgroonga サーバが利用するポート番号を指定します。接続先のgroongaサーバが利用しているポートと、このオプションで指定したポート番号が異なる場合、接続不能となることに注意してください。 .UNINDENT .INDENT 0.0 .TP .B \-\-dir ftp.groonga.org に用意されているスクリプトファイルを表示します。 .UNINDENT .INDENT 0.0 .TP .B \-\-ftp ftp.groonga.orgとFTP通信を行い、scriptファイルの同期やログファイルの送信を行います。 .UNINDENT .INDENT 0.0 .TP .B \-\-log\-output\-dir デフォルトでは、groonga\-benchmark終了後のログファイルの出力先ははカレントディレクトリです。このオプションを利用すると、任意のディレクトリに出力先を変更することができます。 .UNINDENT .INDENT 0.0 .TP .B \-\-groonga groongaコマンドのパスを指定します。デフォルトでは、PATHの中からgroongaコマンドを探します。 .UNINDENT .INDENT 0.0 .TP .B \-\-protocol groongaコマンドが使うプロトコルとして \fIgqtp\fP または \fIhttp\fP を指定します。 .UNINDENT .SS 引数 .INDENT 0.0 .TP .B script groonga\-benchmarkの動作方法(以下、groonga\-benchmark命令と呼びます)を記述したテキストファイルです。拡張子は.scrです。 .UNINDENT .INDENT 0.0 .TP .B db groonga\-benchmarkが利用するgroonga データベースです。指定されたデータベースが存在しない場合、groonga\-benchmarkが新規に作成します。またgroonga サーバを自動的に起動する場合もこの引数で指定したデータベースが利用されます。接続するgroonga サーバを明示的に指定した場合に利用するデータベースは、接続先サーバが使用中のデータベースになることに注意してください。 .UNINDENT .SS 使い方 .sp まず、シェル上(Windowsならコマンドプロンプト上)で: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-benchmark test.scr 任意のDB名 .ft P .fi .UNINDENT .UNINDENT .sp とタイプしてください。もしgroonga\-benchmarkが正常に動作すれば、: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test\-ユーザ名\-数字.log .ft P .fi .UNINDENT .UNINDENT .sp というファイルが作成されるはずです。作成されない場合、このドキュメントの「トラブルシューティング」の章を参照してください。 .SS スクリプトファイル .sp スクリプトファイルは、groonga\-benchmark命令を記述したテキストファイルです。 ";"セミコロンを利用して、一行に複数のgroonga\-benchmark命令を記述することができます。一行に複数のgroonga\-benchmark命令がある場合、各命令は並列に実行されます。 "#"で始まる行はコメントとして扱われます。 .SS groonga\-benchmark命令 .sp 現在サポートされているgroonga\-benchmark命令は以下の11種類です。 .INDENT 0.0 .INDENT 3.5 do_local コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroonga\-benchmark単体で実行します。スレッド数が指定されている場合、複数のスレッドで同じコマンドファイルを同時に実行します。繰り返し数が指定されてい場合、コマンドファイルの内容を繰り返し実行します。スレッド数、繰り返し数とも省略時は1です。1スレッドで複数回動作させたい場合は、do_local コマンドファイル 1 [繰り返し数]と明示的に指定してください。 .UNINDENT .UNINDENT .sp do_gqpt コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでGQTP経由で実行します。スレッド数や繰り返し数の意味はdo_localの場合と同じです。 .UNINDENT .UNINDENT .sp do_http コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでHTTP経由で実行します。スレッド数や繰り返し数の意味はdo_localの場合と同じです。 .UNINDENT .UNINDENT .sp rep_local コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroonga\-benchmark単体で実行し、より詳細な報告を行います。 .UNINDENT .UNINDENT .sp rep_gqpt コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでGQTP経由で実行し、より詳細な報告を行います。 スレッド数や繰り返し数の意味はdo_localと 同じです。 .UNINDENT .UNINDENT .sp rep_http コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでHTTP経由で実行し、より詳細な報告を行います。 スレッド数や繰り返し数の意味はdo_localと 同じです。 .UNINDENT .UNINDENT .sp out_local コマンドファイル 入力ファイル名 .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroonga\-benchmark単体で実行し、各コマンドの実行結果をすべて”出力ファイル"に書きだします。この結果は、test_local,　test_gqtp命令で利用します。なおこの命令の「出力ファイル」とは、groonga\-benchmark実行時に自動的に作成されるログとは別のものです。groonga\-benchmarkではコメントが利用できる以外、: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga < コマンドファイル > 出力ファイル .ft P .fi .UNINDENT .UNINDENT .sp とした場合と同じです。 .UNINDENT .UNINDENT .sp out_gqtp コマンドファイル 出力ファイル名 .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでGQTP経由で実行します。その他はout_local命令と同等です。 .UNINDENT .UNINDENT .sp out_http コマンドファイル 出力ファイル名 .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバでHTTP経由で実行します。その他はout_local命令と同等です。 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B test_local コマンドファイル 入力ファイル名 コマンドファイルをgroonga\-benchmark単体で実行し、各コマンドの実行結果を入力ファイルと比較します。処理時間など本質的要素以外に差分があった場合、差分を、入力ファイル.diffというファイルに書きだします。 .UNINDENT .UNINDENT .UNINDENT .SS コマンドファイル .sp コマンドファイルは、groonga組み込みコマンドを1行に1つずつ記述したテキストファイルです。拡張子に制限はありません。groonga組み込みコマンドに関しては \fB/reference/command\fP を参照してください。 .SS サンプル .sp スクリプトファイルのサンプルです。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # sample script rep_local test.ddl do_local test.load; do_gqtp test.select 10 10; do_local test.status 10 .ft P .fi .UNINDENT .UNINDENT .sp 上記の意味は以下のとおりです。 .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B 1行目 コメント行。 .TP .B 2行目 test.ddl というコマンドファイルをgroonga単体で実行し、詳細に報告する。 .TP .B 3行目 test.load というコマンドファイルをgroonga単体で実行する。(最後の";"セミコロンは複数のgroonga\-benchmark命令を記述する場合に必要ですが、この例のように1つのgroonga\-benchmark命令を実行する場合に付与しても問題ありません。) .TP .B 4行目 test.select というコマンドファイルをgroongaサーバで10個のスレッドで同時に実行する。各スレッドはtest.selectの中身を10回繰り返す。また同時に、groonga単体でtest.statusというコマンドファイルを10個のスレッドで実行する。 .UNINDENT .UNINDENT .UNINDENT .SS 特殊命令 .sp スクリプトファイルのコメント行には特殊コマンドを埋め込むことが可能です。現在サポートされている特殊命令は以下の二つです。 .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B #SET_HOST \-i, \-\-hostオプションと同等の機能です。コマンドラインオプションに指定したIPアドレス/ホスト名と、SET_HOSTで指定したIPアドレス/ホスト名が異なる場合、またコマンドラインオプションを指定しなかった場合にもSET_HOSTが優先されます。SET_HOSTを利用した場合、サーバが自動的には起動されないのもコマンドラインオプションで指定した場合と同様です。 .TP .B #SET_PORT \-p, \-\-port オプションと同等の機能です。コマンドラインオプションに指定したポート番号とSET_PORTで指定したポート番号が異なる場合、またコマンドラインオプションを指定しなかった場合にもSET_PORTが優先されます。 .UNINDENT .UNINDENT .UNINDENT .sp 特殊命令はスクリプトファイルの任意の場所に書き込むことができます。同一ファイル内に複数回特殊命令を記述した場合、「最後の」特殊命令が有効となります。 .sp 例えば、 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ ./groonga\-benchmark \-\-port 20010 test.scr testdb .ft P .fi .UNINDENT .UNINDENT .sp とコマンド上でポートを指定した場合でも、もしtest.scrの中身が .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #SET_PORT 10900 rep_local test.ddl do_local test.load; rep_gqtp test.select 10 10; rep_local test.status 10 #SET_PORT 10400 .ft P .fi .UNINDENT .UNINDENT .sp であれば、自動的に起動されるgroongaサーバはポート番号10400を利用します。 .SS groonga\-benchmark実行結果 .sp groonga\-benchmarkが正常に終了すると、(拡張子を除いた)スクリプト名\-ユーザ名\-実行開始時刻.logという形式のログファイルがカレントディレクトリに作られます。ログファイルは自動的にftp.groonga.org に送信されます。ログファイルは以下のようなjson形式のテキストです。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{"script": "test.scr", "user": "homepage", "date": "2010\-04\-14 22:47:04", "CPU": Intel(R) Pentium(R) 4 CPU 2.80GHz", "BIT": 32, "CORE": 1, "RAM": "975MBytes", "HDD": "257662232KBytes", "OS": "Linux 2.4.20\-24.7\-i686", "HOST": "localhost", "PORT": "10041", "VERSION": "0.1.8\-100\-ga54c5f8" }, {"jobs": "rep_local test.ddl", "detail": [ [0, "table_create res_table \-\-key_type ShortText", 1490, 3086, [0,1271252824.25846,0.00144 7]], [0, "column_create res_table res_column \-\-type Text", 3137, 5956, [0,1271252824.2601,0.002 741]], [0, "column_create res_table user_column \-\-type Text", 6020, 8935, [0,1271252824.26298,0.0 02841]], [0, "column_create res_table mail_column \-\-type Text", 8990, 11925, [0,1271252824.26595,0. 002861]], [0, "column_create res_table time_column \-\-type Time", 12008, 13192, [0,1271252824.26897,0 \&.001147]], [0, "status", 13214, 13277, [0,1271252824.27018,3.0e\-05]], [0, "table_create thread_table \-\-key_type ShortText", 13289, 14541, [0,1271252824.27025,0. 001213]], [0, "column_create thread_table thread_title_column \-\-type ShortText", 14570, 17380, [0,12 71252824.27153,0.002741]], [0, "status", 17435, 17480, [0,1271252824.2744,2.7e\-05]], [0, "table_create lexicon_table \-\-flags 129 \-\-key_type ShortText \-\-default_tokenizer Token Bigram", 17491, 18970, [0,1271252824.27446,0.001431]], [0, "column_create lexicon_table inv_res_column 514 res_table res_column ", 18998, 33248, [0,1271252824.27596,0.01418]], [0, "column_create lexicon_table inv_thread_column 514 thread_table thread_title_column ", 33285, 48472, [0,1271252824.29025,0.015119]], [0, "status", 48509, 48554, [0,1271252824.30547,2.7e\-05]]], "summary" :[{"job": "rep_local test.ddl", "latency": 48607, "self": 47719, "qps": 272.4281 73, "min": 45, "max": 15187, "queries": 13}]}, {"jobs": "do_local test.load; ", "summary" :[{"job": "do_local test.load", "latency": 68693, "self": 19801, "qps": 1010.049 997, "min": 202, "max": 5453, "queries": 20}]}, {"jobs": "do_gqtp test.select 10 10; do_local test.status 10", "summary" :[{"job": " do_local test.status 10", "latency": 805990, "self": 737014, "qps": 54.273053, "min": 24, "max": 218, "queries": 40},{"job": "do_gqtp test.select 10 10", "lat ency": 831495, "self": 762519, "qps": 1967.164097, "min": 73, "max": 135631, "queries": 15 00}]}, {"total": 915408, "qps": 1718.359464, "queries": 1573}] .ft P .fi .UNINDENT .UNINDENT .SS 制限事項 .INDENT 0.0 .IP \(bu 2 スクリプトファイルの一行には複数のgroonga\-benchmark命令を記述できますが、すべてのスレッド数の合計は最大64までに制限されます。 .IP \(bu 2 コマンドファイル中のgroongaコマンドの長さは最長5000000byteです。 .UNINDENT .SS トラブルシューティング .sp もし、groonga\-benchmarkが正常に動作しない場合、まず以下を確認してください。 .INDENT 0.0 .IP \(bu 2 インターネットに接続しているか？ \fI\-\-ftp\fP オプションを指定すると、groonga\-benchmarkは動作のたびにftp.groonga.orgと通信します。ftp.groonga.orgと通信可能でない場合、groonga\-benchmarkは正常に動作しません。 .IP \(bu 2 groonga サーバが動作していないか？　groonga\-benchmarkは、\-i, \-\-host オプションで明示的にサーバを指定しないかぎり、自動的にlocalhostのgroongaサーバを立ち上げます。すでにgroongaサーバが動作している場合、groonga\-benchmarkは正常に動作しない可能性があります。 .IP \(bu 2 指定したDBが適切か？ groonga\-benchmarkは、引数で指定したDBの中身はチェックしません。もし指定されたDBが存在しなければ自動的にDBを作成しますが、もしファイルとして存在する場合は中身に関わらず動作を続けてしまい、結果が異常になる可能性があります。 .UNINDENT .sp 以上の原因でなければ、問題はgroonga\-benchmarkかgroongaにあります。ご報告をお願いします。 .SS groonga\-httpd .SS Summary .sp groonga\-httpd is a program to communicate with a Groonga server using the HTTP protocol. It functions as same as \fBgroonga\-server\-http\fP\&. Although \fBgroonga\-server\-http\fP has limited support for HTTP with a minimal built\-in HTTP server, groonga\-httpd has full support for HTTP with an embedded \fI\%nginx\fP\&. All standards\-compliance and features provided by nginx is also available in groonga\-httpd. .sp groonga\-httpd has an Web\-based administration tool implemented with HTML and JavaScript. You can access to it from \fI\%http://hostname:port/\fP\&. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-httpd [nginx options] .ft P .fi .UNINDENT .UNINDENT .SS Usage .SS Set up .sp First, you\(aqll need to edit the groonga\-httpd configuration file to specify a database. Edit /etc/groonga/httpd/groonga\-httpd.conf to enable the \fBgroonga_database\fP directive like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Match this to the file owner of groonga database files if groonga\-httpd is # run as root. #user groonga; \&... http { ... # Don\(aqt change the location; currently only /d/ is supported. location /d/ { groonga on; # <= This means to turn on groonga\-httpd. # Specify an actual database and enable this. groonga_database /var/lib/groonga/db/db; } ... } .ft P .fi .UNINDENT .UNINDENT .sp Then, run groonga\-httpd. Note that the control immediately returns back to the console because groonga\-httpd runs as a daemon process by default.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga\-httpd .ft P .fi .UNINDENT .UNINDENT .SS Request queries .sp To check, request a simple query (\fB/reference/commands/status\fP). .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status [ [ 0, 1337566253.89858, 0.000355720520019531 ], { "uptime": 0, "max_command_version": 2, "n_queries": 0, "cache_hit_rate": 0.0, "version": "4.0.1", "alloc_count": 161, "command_version": 1, "starttime": 1395806036, "default_command_version": 1 } ] .ft P .fi .UNINDENT .UNINDENT .SS Loading data by POST .sp The feature of groonga\-httpd in contrast to groonga is supporting POST method. .sp You can load data by POST JSON data. .sp Here is an example curl command line that loads two users alice and bob to Users table: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-\-data\-binary \(aq[{"_key": "alice"}, {"_key": "bob"}]\(aq \-H "Content\-Type: application/json" "http://localhost:10041/d/load?table=Users" .ft P .fi .UNINDENT .UNINDENT .sp If you loads users from JSON file, prepare JSON file like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ {"_key": "alice"}, {"_key": "bob"} ] .ft P .fi .UNINDENT .UNINDENT .sp Then specify JSON file in curl command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-X POST \(aqhttp://localhost:10041/d/load?table=Users\(aq \-H \(aqContent\-Type: application/json\(aq \-d @users.json .ft P .fi .UNINDENT .UNINDENT .SS Browse the administration tool .sp Also, you can browse Web\-based administration tool at \fI\%http://localhost:10041/\fP\&. .SS Shut down .sp Finally, to terminate the running groonga\-httpd daemon, run this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga\-httpd \-s stop .ft P .fi .UNINDENT .UNINDENT .SS Configuration directives .sp This section decribes only important directives. They are groonga\-httpd specific directives and performance related directives. .sp The following directives can be used in the groonga\-httpd configuration file. By default, it\(aqs located at /etc/groonga/httpd/groonga\-httpd.conf. .SS Groonga\-httpd specific directives .sp The following directives aren\(aqt provided by nginx. They are provided by groonga\-httpd to configure groonga\-httpd specific configurations. .SS \fBgroonga\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga on | off; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fBgroonga off;\fP .TP .B Context \fBlocation\fP .UNINDENT .sp Specifies whether Groonga is enabled in the \fBlocation\fP block. The default is \fBoff\fP\&. You need to specify \fBon\fP to enable groonga. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location /d/ { groonga on; # Enables groonga under /d/... path } location /d/ { groonga off; # Disables groonga under /d/... path } .ft P .fi .UNINDENT .UNINDENT .SS \fBgroonga_database\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_database /path/to/groonga/database; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fBgroonga_database /usr/local/var/lib/groonga/db/db;\fP .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies the path to a Groonga database. This is the required directive. .SS \fBgroonga_database_auto_create\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_database_auto_create on | off; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fBgroonga_database_auto_create on;\fP .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies whether Groonga database is created automatically or not. If the value is \fBon\fP and the Groonga database specified by \fIgroonga\-database\fP doesn\(aqt exist, the Groonga database is created automatically. If the Groonga database exists, groonga\-httpd does nothing. .sp If parent directory doesn\(aqt exist, parent directory is also created recursively. .sp The default value is \fBon\fP\&. Normally, the value doesn\(aqt need to be changed. .SS \fBgroonga_base_path\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_base_path /d/; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default The same value as \fBlocation\fP name. .TP .B Context \fBlocation\fP .UNINDENT .sp Specifies the base path in URI. Groonga uses \fB/d/command?parameter1=value1&...\fP path to run \fBcommand\fP\&. The form of path in used in groonga\-httpd but groonga\-httpd also supports \fB/other\-prefix/command?parameter1=value1&...\fP form. To support the form, groonga\-httpd removes the base path from the head of request URI and prepend \fB/d/\fP to the processed request URI. By the path conversion, users can use custom path prefix and Groonga can always uses \fB/d/command?parameter1=value1&...\fP form. .sp Nomally, this directive isn\(aqt needed. It is needed for per command configuration. .sp Here is an example configuration to add authorization to \fB/reference/commands/shutdown\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_database /var/lib/groonga/db/db; location /d/shutdown { groonga on; # groonga_base_path is needed. # Because /d/shutdown is handled as the base path. # Without this configuration, /d/shutdown/shutdown path is required # to run shutdown command. groonga_base_path /d/; auth_basic "manager is required!"; auth_basic_user_file "/etc/managers.htpasswd"; } location /d/ { groonga on; # groonga_base_path doesn\(aqt needed. # Because location name is the base path. } .ft P .fi .UNINDENT .UNINDENT .SS \fBgroonga_log_path\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_log_path path | off; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fB/var/log/groonga/httpd/groonga.log\fP .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies Groonga log path in the \fBhttp\fP, \fBserver\fP or \fBlocation\fP block. The default is \fB/var/log/groonga/httpd/groonga.log\fP\&. You can disable logging to specify \fBoff\fP\&. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location /d/ { groonga on; # You can disable log for groonga. groonga_log_path off; } .ft P .fi .UNINDENT .UNINDENT .SS \fBgroonga_log_level\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_log_level none | emergency | alert | ciritical | error | warning | notice | info | debug | dump; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fBnotice\fP .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies Groonga log level in the \fBhttp\fP, \fBserver\fP or \fBlocation\fP block. The default is \fBnotice\fP\&. You can disable logging by specifying \fBnone\fP as log level. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location /d/ { groonga on; # You can customize log level for groonga. groonga_log_level notice; } .ft P .fi .UNINDENT .UNINDENT .SS \fBgroonga_query_log_path\fP .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_query_log_path path | off; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default \fB/var/log/groonga/httpd/groonga\-query.log\fP .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies Groonga\(aqs query log path in the \fBhttp\fP, \fBserver\fP or \fBlocation\fP block. The default is \fB/var/log/groonga/httpd/groonga\-query.log\fP\&. You can disable logging to specify \fBoff\fP\&. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location /d/ { groonga on; # You can disable query log for groonga. groonga_query_log_path off; } .ft P .fi .UNINDENT .UNINDENT .sp Query log is useful for the following cases: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Detecting slow query. .IP \(bu 2 Debugging. .UNINDENT .UNINDENT .UNINDENT .sp You can analyze your query log by \fI\%groonga\-query\-log package\fP\&. The package provides useful tools. .sp For example, there is a tool that analyzing your query log. It can detect slow queries from your query log. There is a tool that replaying same queries in your query log. It can test the new Groonga before updating production environment. .SS Performance related directives .sp The following directives are related to the performance of groonga\-httpd. .SS \fBworker_processes\fP .sp For optimum performance, set this to be equal to the number of CPUs or cores. In many cases, Groonga queries may be CPU\-intensive work, so to fully utilize multi\-CPU/core systems, it\(aqs essential to set this accordingly. .sp This isn\(aqt a groonga\-httpd specific directive, but an nginx\(aqs one. For details, see \fI\%http://wiki.nginx.org/CoreModule#worker_processes\fP\&. .sp By default, this is set to 1. It is nginx\(aqs default. .SS \fBgroonga_cache_limit\fP .sp This directive is introduced to customize cache limit for each worker process. .sp Synopsis: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga_cache_limit CACHE_LIMIT; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Default 100 .TP .B Context \fBhttp\fP, \fBserver\fP, \fBlocation\fP .UNINDENT .sp Specifies Groonga\(aqs limit of query cache in the \fBhttp\fP, \fBserver\fP or \fBlocation\fP block. The default value is 100. You can disable query cache to specify 0 to \fBgroonga_cache_limit\fP explicitly. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location /d/ { groonga on; # You can customize query cache limit for groonga. groonga_cache_limit 100; } .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_cache\fP .sp In short, you can use nginx\(aqs reverse proxy and cache mechanism instead of Groonga\(aqs built\-in query cache feature. .SS Query cache .sp Groonga has query cache feature for \fB/reference/commands/select\fP command. The feature improves performance in many cases. .sp Query cache feature works well on groonga\-httpd except you use \fB/reference/commands/cache_limit\fP command on 2 or more workers. Normally, \fB/reference/commands/cache_limit\fP command isn\(aqt used. So there is no problem on many cases. .sp Here is a description about a problem of using \fB/reference/commands/cache_limit\fP command on 2 or more workers. .sp Groonga\(aqs query cache is available in the same process. It means that workers can\(aqt share the cache. If you don\(aqt change cache size, it isn\(aqt a big problem. If you want to change cache size by \fB/reference/commands/cache_limit\fP command, there is a problem. .sp There is no portable ways to change cache size for all workers. .sp For example, there are 3 workers: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\- worker 1 client \-\- groonga\-httpd (master) \-\-+\-\- worker 2 +\-\- worker 3 .ft P .fi .UNINDENT .UNINDENT .sp The client requests \fB/reference/commands/cache_limit\fP command and the worker 1 receives it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-> worker 1 (changed!) client \-> groonga\-httpd (master) \-\-+\-\- worker 2 +\-\- worker 3 .ft P .fi .UNINDENT .UNINDENT .sp The client requests \fB/reference/commands/cache_limit\fP command again and the worker 1 receives it again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-> worker 1 (changed again!!!) client \-> groonga\-httpd (master) \-\-+\-\- worker 2 +\-\- worker 3 .ft P .fi .UNINDENT .UNINDENT .sp In this case, the worker 2 and the worker 3 aren\(aqt received any requests. So they don\(aqt change cache size. .sp You can\(aqt choose a worker. So you can\(aqt change cache sizes of all workers by \fB/reference/commands/cache_limit\fP command. .SS Reverse proxy and cache .sp You can use nginx\(aqs reverse proxy and cache feature for query cache: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\- worker 1 client \-\- groonga\-httpd (master) \-\- reverse proxy + cache \-\-+\-\- worker 2 +\-\- worker 3 .ft P .fi .UNINDENT .UNINDENT .sp You can use the same cache configuration for all workers but you can\(aqt change cache configuration dynamically by HTTP. .sp Here is a sample configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&... http { proxy_cache_path /var/cache/groonga\-httpd levels=1:2 keys_zone=groonga:10m; proxy_cache_valid 10m; ... # Reverse proxy and cache server { listen 10041; ... # Only select command location /d/select { # Pass through groonga with cache proxy_cache groonga; proxy_pass http://localhost:20041; } location / { # Pass through groonga proxy_pass http://localhost:20041; } } # groonga server { location 20041; location /d/ { groonga on; groonga_database /var/lib/groonga/db/db; } } ... } .ft P .fi .UNINDENT .UNINDENT .sp See the following nginx documentations for parameter details: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path\fP .IP \(bu 2 \fI\%http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid\fP .IP \(bu 2 \fI\%http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache\fP .IP \(bu 2 \fI\%http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass\fP .UNINDENT .UNINDENT .UNINDENT .sp Note that you need to remove cache files created by nginx by hand after you load new data to Groonga. For the above sample configuration, run the following command to remove cache files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga DB_PATH < load.grn % rm \-rf /var/cache/groonga\-httpd/* .ft P .fi .UNINDENT .UNINDENT .sp If you use Groonga\(aqs query cache feature, you don\(aqt need to expire cache by hand. It is done automatically. .SS Available nginx modules .sp All standard HTTP modules are available. HttpRewriteModule is disabled when you don\(aqt have PCRE (Perl Compatible Regular Expressions). For the list of standard HTTP modules, see \fI\%http://wiki.nginx.org/Modules\fP\&. .SS groonga HTTPサーバー .SS 名前 .sp groonga HTTPサーバー .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga \-d \-\-protocol http DB_PATH .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp groongaサーバを起動する時に\-\-protocolオプションにhttpを指定すると、httpで通信可能になります。また、\-\-document\-root によって静的ページのパスを指定すると、httpリクエストに指定されたURIに対応する、パス配下に置かれたファイルを出力します。 .sp groongaにはHTML + JavaScriptで実装された管理ツールが標準で付属しています。\-\-document\-rootを指定しない場合は管理ツールがインストールされているパスが指定されたとみなされますので、ウェブブラウザでhttp://hostname:port/にアクセスすると、管理ツールを利用できます。 .SS コマンド .sp httpを指定して起動したgroongaサーバに対しても、他のモードで起動したgroongaと同じコマンドが使用できます。 .sp コマンドは、複数の引数をとります。引数にはそれぞれ名前があります。また、特殊な引数である「output_type」と「command_version」があります。 .sp スタンドアロンやクライアントモードでは、コマンドは以下のような形式で指定します。 .INDENT 0.0 .INDENT 3.5 形式1: コマンド名 値1 値2,.. .sp 形式2: コマンド名 \-\-引数名1 値1 \-\-引数名2 値2,.. .UNINDENT .UNINDENT .sp 形式1と形式2は混在させることができます。これらの形式では、output_typeという引数名を用いてoutput_typeを指定します。 .sp httpでgroongaサーバと通信する際には、以下のような形式でコマンドを指定します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 形式: /d/コマンド名.output_type?引数名1=値1&引数名2=値2&... .ft P .fi .UNINDENT .UNINDENT .sp ただし、コマンド名、引数名、値はURLエンコードが必要です。 .sp GETメソッドのみが使用可能です。 .sp output_typeにはjson, tsv, xmlが指定可能です。 .sp command_versionはコマンドの仕様の互換性を指定します。詳細は \fB/reference/command/command_version\fP を参照してください。 .SS 返値 .sp output_typeの指定に従って、コマンドの実行結果を出力します。 .SS groonga\-suggest\-create\-dataset .SS NAME .sp groonga\-suggest\-create\-dataset \- Defines schema for a suggestion dataset .SS SYNOPSTIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-create\-dataset [options] DATABASE DATASET .ft P .fi .UNINDENT .UNINDENT .SS DESCTIPION .sp groonga\-suggest\-create\-dataset creates a dataset for \fB/suggest\fP\&. A database has many datasets. This command just defines schema for a suggestion dataset. .sp This command generates some tables and columns for \fB/suggest\fP\&. .sp Here is the list of such tables. If you specify \(aqquery\(aq as dataset name, following \(aq_DATASET\(aq suffix are replaced. Thus, \(aqitem_query\(aq, \(aqpair_query\(aq, \(aqsequence_query\(aq, \(aqevent_query\(aq tables are generated. .INDENT 0.0 .IP \(bu 2 event_type .IP \(bu 2 bigram .IP \(bu 2 kana .IP \(bu 2 item_DATASET .IP \(bu 2 pair_DATASET .IP \(bu 2 sequence_DATASET .IP \(bu 2 event_DATASET .IP \(bu 2 configuration .UNINDENT .SS OPTIONS .sp None. .SS EXIT STATUS .sp TODO .SS FILES .sp TODO .SS EXAMPLE .sp TODO .SS SEE ALSO .sp \fB/suggest\fP \fBgroonga\-suggest\-httpd\fP \fBgroonga\-suggest\-learner\fP .SS groonga\-suggest\-httpd .SS Summary .sp groonga\-suggest\-httpd is a program to provide interface which accepts HTTP request and returns suggestion dataset, then saves logs for learning. groonga\-suggest\-httpd behaves similar in point of view of suggestion functionality, but the name of parameter is different. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-httpd [options] database_path .ft P .fi .UNINDENT .UNINDENT .SS Usage .SS Set up .sp First you need to set up database for suggestion. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga\-suggest\-create\-dataset /tmp/groonga\-databases/groonga\-suggest\-httpd query .ft P .fi .UNINDENT .UNINDENT .SS Launch groonga\-suggest\-httpd .sp Execute groonga\-suggest\-httpd command: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga\-suggest\-httpd /tmp/groonga\-databases/groonga\-suggest\-httpd .ft P .fi .UNINDENT .UNINDENT .sp After executing above command, groonga\-suggest\-httpd accepts HTTP request on 8080 port. .sp If you just want to save requests into log file, use \fB\-l\fP option. .sp Here is the example to save log files under \fBlogs\fP directory with \fBlog\fP prefix for each file.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga\-suggest\-httpd \-l logs/log /tmp/groonga\-databases/groonga\-suggest\-httpd .ft P .fi .UNINDENT .UNINDENT .sp Under \fBlogs\fP directory, log files such as \fBlogYYYYmmddHHMMSS\-00\fP are created. .SS Request to groonga\-suggest\-httpd .sp Here is the sample requests to learn \fBgroonga\fP for \fBquery\fP dataset: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=92619&t=complete&q=g\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=93850&t=complete&q=gr\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=94293&t=complete&q=gro\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=94734&t=complete&q=groo\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=95147&t=complete&q=grooon\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=95553&t=complete&q=groonga\(aq % curl \(aqhttp://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=groonga .ft P .fi .UNINDENT .UNINDENT .SS Options .INDENT 0.0 .TP .B \-p, \-\-port Specify http server port number. The default value is 8080. .UNINDENT .INDENT 0.0 .TP .B \-t, \-\-n\-threads Specify number of threads. The default value is 8. This option accepts 128 as the max value, but use the number of CPU cores for performance. .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-send\-endpoint Specify endpoint for sender. .UNINDENT .INDENT 0.0 .TP .B \-r, \-\-receive\-endpoint Specify endpoint for receiver. .UNINDENT .INDENT 0.0 .TP .B \-l, \-\-log\-base\-path Specify path prefix of log. .UNINDENT .INDENT 0.0 .TP .B \-\-n\-lines\-per\-log\-file Specify the number of lines in a log file. The default value is 1,000,000. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Specify this option to daemonize. .UNINDENT .INDENT 0.0 .TP .B \-\-disable\-max\-fd\-check Specify this option to disable checking max fd on start. .UNINDENT .SS Command line parameters .sp There is one required parameter \- \fBdatabase_path\fP\&. .SS \fBdatabase_path\fP .sp Specifies the path to a Groonga database. This database must be created by \fBgroonga\-suggest\-create\-dataset\fP command because it executes required initialization for suggestion. .SS GET parameters .sp groonga\-suggest\-httpd accepts following GET parameters. .sp There are required parameters which depends on type of query. .SS Required parameters .TS center; |l|l|l|. _ T{ Key T} T{ Description T} T{ Note T} _ T{ q T} T{ UTF\-8 encoded string which user fills in form T} T{ T} _ T{ t T} T{ The type of query. The value of type must be complete, correct, suggest or submit. It also accepts multiple type of query which is concatinated by \fB|\fP\&. Note that \fBsubmit\fP is invalid value when you specify multiple type of query. T} T{ T} _ .TE .SS Required parameters for learning .TS center; |l|l|l|. _ T{ Key T} T{ Description T} T{ Note T} _ T{ s T} T{ Elapsed time from 0:00 January 1, 1970 T} T{ Note that you need specify the value of \fBs\fP in milliseconds T} _ T{ i T} T{ Unique ID to distinct user T} T{ Use session ID or IP address for example T} _ T{ l T} T{ Specify the name of dataset for learning. It also accepts multiple dataset name which is concatinated by \fB|\fP T} T{ Note that dataset name must be matched to following regular expression \fB[A\-Za\-z ][A\-Za\-z0\-9 ]{0,15}\fP T} _ .TE .SS Required parameters for suggestion .TS center; |l|l|l|. _ T{ Key T} T{ Description T} T{ Note T} _ T{ n T} T{ Specify the name of dataset for suggestion T} T{ This dataset name is used to calculate suggestion results T} _ .TE .SS Optional parameter .TS center; |l|l|l|. _ T{ Key T} T{ Description T} T{ Note T} _ T{ callback T} T{ Specify the name of function if you prefer JSONP as response format T} T{ The name of function must be matched to reqular expression \fB[A\-Za\-z ][A\-Za\-z0\-9 ]{0,15}\fP T} _ .TE .SS Return value .sp \fBgroonga\-suggest\-httpd\fP command returns following response in JSON or JSONP format. .sp In JSON format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {TYPE: [[CANDIDATE_1, SCORE_1], [CANDIDATE_2, SCORE_2], ... [CANDIDATE_N, SCORE_N]]} .ft P .fi .UNINDENT .UNINDENT .sp In JSONP format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C FUNCTION({TYPE: [[CANDIDATE_1, SCORE_1], [CANDIDATE_2, SCORE_2], ... [CANDIDATE_N, SCORE_N]]}) .ft P .fi .UNINDENT .UNINDENT .sp \fBTYPE\fP .INDENT 0.0 .INDENT 3.5 One of \fBcomplete\fP, \fBcorrect\fP and \fBsuggest\fP\&. .UNINDENT .UNINDENT .sp \fBCANDIDATE_N\fP .INDENT 0.0 .INDENT 3.5 The string of candidate (UTF\-8). .UNINDENT .UNINDENT .sp \fBSCORE_N\fP .INDENT 0.0 .INDENT 3.5 The score. .UNINDENT .UNINDENT .SS groonga\-suggest\-learner .SS Summary .sp groonga\-suggest\-learner is a program to learn suggest result from data which derived from groonga\-suggest\-httpd. Usually, it is used with groonga\-suggest\-httpd, but It is allowed to launch standalone. In such a case, groonga\-suggest\-learner loads data from log directory. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-learner [options] database_path .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp groonga\-suggest\-leaner supports the two way of learning data. One is learning data from groonga\-suggest\-httpd, the other is learning data from already existing log files. .SS Learning data from groonga\-suggest\-httpd .sp Execute groonga\-suggest\-learner.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-learner testdb/db .ft P .fi .UNINDENT .UNINDENT .SS Learning data from log files .sp Execute groonga\-suggest\-learner with \fB\-l\fP option. .sp Here is the sample to load log data under \fBlogs\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-learner \-l logs testdb/db .ft P .fi .UNINDENT .UNINDENT .SS Options .INDENT 0.0 .TP .B \-r , \-\-receive\-endpoint Uses \fB\fP as the receiver endpoint. .UNINDENT .INDENT 0.0 .TP .B \-s , \-\-send\-endpoint Uses \fB\fP as the sender endpoint. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Runs as a daemon. .UNINDENT .INDENT 0.0 .TP .B \-l , \-\-log\-base\-path Reads logs from \fB\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-path Outputs log to \fB\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-level Uses \fB\fP for log level. \fB\fP must be between 1 and 9. Larger level outputs more logs. .UNINDENT .SS Parameters .sp There is one required parameter \- \fBdatabase_path\fP\&. .SS \fBdatabase_path\fP .sp Specifies the path to a groonga database. .SS Related tables .sp Here is the list of table which learned data is stored. If you specify \fBquery\fP as dataset name, following \fB_DATASET\fP suffix are replaced. Thus, \fBevent_query\fP table is used. .INDENT 0.0 .IP \(bu 2 event_DATASET .UNINDENT .SS Output .sp Groonga supports the following output format types: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%JSON\fP .IP \(bu 2 \fI\%XML\fP .IP \(bu 2 TSV (Tab Separated Values) .IP \(bu 2 \fI\%MessagePack\fP .UNINDENT .UNINDENT .UNINDENT .sp JSON is the default output format. .SS Usage .sp Groonga has the following query interfaces: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 command line .IP \(bu 2 HTTP .UNINDENT .UNINDENT .UNINDENT .sp They provides different ways to change output format type. .SS Command line .sp You can use command line query interface by \fBgroonga DB_PATH\fP or \fBgroonga \-c\fP\&. Those groonga commands shows \fB> \(ga\(ga prompt. In this query interface, you can specify output format type by \(ga\(gaoutput_type\fP option. .sp If you don\(aqt specify \fBoutput_type\fP option, you will get a result in JSON format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > status [[0,1327721628.10738,0.000131845474243164],{"alloc_count":142,"starttime":1327721626,"uptime":2,"version":"1.2.9\-92\-gb87d9f8","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] .ft P .fi .UNINDENT .UNINDENT .sp You can specify \fBjson\fP as \fBoutput_type\fP value to get a result in JSON format explicitly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > status \-\-output_type json [[0,1327721639.08321,7.93933868408203e\-05],{"alloc_count":144,"starttime":1327721626,"uptime":13,"version":"1.2.9\-92\-gb87d9f8","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBxml\fP as \fBoutput_type\fP value to get a result in XML format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > status \-\-output_type xml alloc_count 146 starttime 1327721626 uptime 23 version 1.2.9\-92\-gb87d9f8 n_queries 0 cache_hit_rate 0.0 command_version 1 default_command_version 1 max_command_version 2 .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBtsv\fP as \fBoutput_type\fP value to get a result in TSV format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > status \-\-output_type tsv 0 1327721664.82675 0.000113964080810547 "alloc_count" 146 "starttime" 1327721626 "uptime" 38 "version" "1.2.9\-92\-gb87d9f8" "n_queries" 0 "cache_hit_rate" 0.0 "command_version" 1 "default_command_version" 1 "max_command_version" 2 END .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBmsgpack\fP as \fBoutput_type\fP value to get a result in MessagePack format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > status \-\-output_type msgpack (... omitted because MessagePack is binary data format. ...) .ft P .fi .UNINDENT .UNINDENT .SS HTTP .sp You can use HTTP query interface by \fBgroonga \-\-protocol http \-s DB_PATH\fP\&. Groonga HTTP server starts on port 10041 by default. In this query interface, you can specify output format type by extension. .sp If you don\(aqt specify extension, you will get a result in JSON format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status [[0,1327809294.54311,0.00082087516784668],{"alloc_count":155,"starttime":1327809282,"uptime":12,"version":"1.2.9\-92\-gb87d9f8","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] .ft P .fi .UNINDENT .UNINDENT .sp You can specify \fBjson\fP as extension to get a result in JSON format explicitly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status.json [[0,1327809319.01929,9.5367431640625e\-05],{"alloc_count":157,"starttime":1327809282,"uptime":37,"version":"1.2.9\-92\-gb87d9f8","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBxml\fP as extension to get a result in XML format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status.xml alloc_count 159 starttime 1327809282 uptime 57 version 1.2.9\-92\-gb87d9f8 n_queries 0 cache_hit_rate 0.0 command_version 1 default_command_version 1 max_command_version 2 .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBtsv\fP as extension to get a result in TSV format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status.tsv 0 1327809366.84187 8.44001770019531e\-05 "alloc_count" 159 "starttime" 1327809282 "uptime" 84 "version" "1.2.9\-92\-gb87d9f8" "n_queries" 0 "cache_hit_rate" 0.0 "command_version" 1 "default_command_version" 1 "max_command_version" 2 END .ft P .fi .UNINDENT .UNINDENT .sp You need to specify \fBmsgpack\fP as extension to get a result in MessagePack format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl http://localhost:10041/d/status.msgpack (... omitted because MessagePack is binary data format. ...) .ft P .fi .UNINDENT .UNINDENT .SS Command .sp Command is the most important processing unit in query API. You request a processing to groonga by a command. .sp This section describes about command and built\-in commands. .SS コマンドバージョン .SS 概要 .sp Groonga1.1からコマンドバージョンという概念が導入されます。コマンドバージョンは、selectやloadなどのGroongaのコマンドの仕様の互換性を表します。Groongaパッケージのバージョンが新しくなったとしても、同一のコマンドバージョンが使用可能であるなら、すべてのコマンドについて互換性が保証されます。コマンドバージョンが異なれば、同じ名前のコマンドであっても、動作に互換性がない可能性があります。 .sp あるバージョンのGroongaは、二つのコマンドバージョンを同時にサポートするようになります。 使用するコマンドバージョンは、groongaを起動する際のコマンドラインオプションないしコンフィグファイルにdefault\-commnad\-versionパラメータを与えることによって指定できます。また、個々のコマンドを実行する際に、command_versionパラメータを与えることによっても指定することができます。 .sp コマンドバージョンは1からはじまり、更新されるたびに1ずつ大きくなります。現状のGroongaのコマンドの仕様はcommand\-version 1という扱いになります。次回提供するGroongaは、command\-version 1とcommand\-version 2の二つをサポートすることになります。 .SS バージョンの位置づけ .sp あるバージョンのGroongaにおいてサポートされるコマンドバージョンは、develop, stable,deprecatedのいずれかの位置づけとなります。 .INDENT 0.0 .TP .B develop まだ開発中であり、仕様が変更される可能性があります。 .TP .B stable 使用可能であり仕様も安定しています。その時点で使用することが推奨されます。 .TP .B deprecated 使用可能であり仕様も安定していますが、廃止予定であり使用が推奨されません。 .UNINDENT .sp あるバージョンのGroongaがサポートする二つのコマンドバージョンのうち、いずれか一つが必ずstableの位置づけとなります。残りの一つは、developないしdeprecatedとなります。 .sp たとえば下記のようにGroongaのサポートするコマンドバージョンは推移します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga1.1: command\-version1=stable command\-version2=develop groonga1.2: command\-version1=deprecated command\-version2=stable groonga1.3: command\-version2=stable command\-version3=develop groonga1.4: command\-version2=deprecated command\-version3=stable groonga1.5: command\-version3=stable command\-version4=develop .ft P .fi .UNINDENT .UNINDENT .sp あるコマンドバージョンははじめにdevelop扱いとしてリリースされ、やがてstableに移行します。 その後二世代経過するとそのコマンドバージョンはdeprecated扱いとなります。さらに次のコマンドバージョンがリリースされると、deprecatedだったコマンドバージョンはサポート対象外となります。 .sp default\-commnad\-versionパラメータやcommand_versionパラメータを指定せずにgroongaコマンドを実行した際には、その時点でstableであるコマンドバージョンが指定されたものとみなします。 .sp groongaプロセス起動時に、default\-command\-versionパラメータにstable扱いでないコマンドバージョンを指定した場合には、警告メッセージがログファイルに出力されます。また、サポート範囲外のコマンドバージョンを指定した場合にはエラーとなり、プロセスは速やかに停止します。 .SS コマンドバージョンの指定方法 .sp コマンドバージョンの指定方法はgroonga実行モジュールの引数として指定する方法と各コマンドの引数として指定する方法があります。 .SS default\-command\-versionパラメータ .sp groonga実行モジュールの引数としてdefault\-command\-versionパラメータを指定できます。 (configファイルの中に指定することも可能です) .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga \-\-default\-command\-version 1 .ft P .fi .UNINDENT .UNINDENT .sp そのプロセスで実行するすべてのコマンドについて、デフォルトのコマンドバージョンとして指定されたバージョンを使用します。指定されたコマンドバージョンがstableであった場合にはなんのメッセージも表示されずそのまま起動します。指定されたコマンドバージョンがdevelopあるいはdeprecatedであった場合には、groonga.logファイルに警告メッセージを出力します。指定されたコマンドバージョンがサポート対象外であった場合には標準エラー出力にエラーメッセージを出力し、プロセスは速やかに終了します。 .SS command_versionパラメータ .sp select,loadなどのすべてのgroongaコマンドにcommand_versionが指定できます。 .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-command_version 1 \-\-table tablename .ft P .fi .UNINDENT .UNINDENT .sp 指定されたコマンドバージョンでコマンドを実行します。指定されたコマンドバージョンがサポート対象外であった場合にはエラーが返されます。command\-versionが指定されなかった場合は、当該プロセス起動時にdefault\-command\-versionに指定した値が指定されたものとみなします。 .SS Output format .SS Summary .sp Commands output their result as JSON, MessagePack, XML or TSV format. .sp JSON and MessagePack output have the same structure. XML and TSV are their original structure. .sp JSON or MessagePack is recommend format. XML is useful for visual result check. TSV is just for special use. Normally you doesn\(aqt need to use TSV. .SS JSON and MessagePack .sp This secsion describes the structure of command result on JSON and MessagePack format. JSON is used to show structure because MessagePack is binary format. Binary format isn\(aqt proper for documenataion. .sp JSON and MessagePack uses the following structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, BODY] .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ [ 0, 1337566253.89858, 0.000355720520019531 ], [ [ [ 1 ], [ [ "_id", "UInt32" ], [ "_key", "ShortText" ], [ "content", "Text" ], [ "n_likes", "UInt32" ] ], [ 2, "Groonga", "I started to use groonga. It\(aqs very fast!", 10 ] ] ] ] .ft P .fi .UNINDENT .UNINDENT .sp In the example, the following part is \fBHEADER\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ 0, 1337566253.89858, 0.000355720520019531 ] .ft P .fi .UNINDENT .UNINDENT .sp The following part is \fBBODY\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ [ [ 1 ], [ [ "_id", "UInt32" ], [ "_key", "ShortText" ], [ "content", "Text" ], [ "n_likes", "UInt32" ] ], [ 2, "Groonga", "I started to use groonga. It\(aqs very fast!", 10 ] ] ] .ft P .fi .UNINDENT .UNINDENT .SS \fBHEADER\fP .sp \fBHEADER\fP is an array. The content of \fBHEADER\fP has some patterns. .SS Success case .sp \fBHEADER\fP has three elements on success: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME] .ft P .fi .UNINDENT .UNINDENT .sp The first element is always \fB0\fP\&. .sp \fBUNIX_TIME_WHEN_COMMAND_IS_STARTED\fP is the number of seconds since 1970\-01\-01 00:00:00 UTC when the command is started processing. \fBELAPSED_TIME\fP is the elapsed time for processing the command in seconds. Both \fBUNIX_TIME_WHEN_COMMAND_IS_STARTED\fP and \fBELAPSED_TIME\fP are float value. The precision of them are nanosecond. .SS Error case .sp \fBHEADER\fP has four or five elements on error: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ RETURN_CODE, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME, ERROR_MESSAGE, ERROR_LOCATION ] .ft P .fi .UNINDENT .UNINDENT .sp \fBERROR_LOCATION\fP may not be included in \fBHEADER\fP but other four elements are always included. .sp \fBRETURN_CODE\fP is non 0 value. See \fBreturn_code\fP about available return codes. .sp \fBUNIX_TIME_WHEN_COMMAND_IS_STARTED\fP and \fBELAPSED_TIME\fP are the same as success case. .sp \fBERROR_MESSAGE\fP is an error message in string. .sp \fBERROR_LOCATION\fP is optional. If error location is collected, \fBERROR_LOCATION\fP is included. \fBERROR_LOCATION\fP is an array. \fBERROR_LOCATION\fP has one ore two elements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ LOCATION_IN_GROONGA, LOCATION_IN_INPUT ] .ft P .fi .UNINDENT .UNINDENT .sp \fBLOCATION_IN_GROONGA\fP is the source location that error is occurred in groonga. It is useful for groonga developers but not useful for users. \fBLOCATION_IN_GROONGA\fP is an array. \fBLOCATION_IN_GROONGA\fP has three elements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ FUNCTION_NAME, SOURCE_FILE_NAME, LINE_NUMBER ] .ft P .fi .UNINDENT .UNINDENT .sp \fBFUNCTION_NAME\fP is the name of function that error is occurred. .sp \fBSOURCE_FILE_NAME\fP is the name of groonga\(aqs source file that error is occurred. .sp \fBLINE_NUMBER\fP is the line number of \fBSOURCE_FILE_NAME\fP that error is occurred. .sp \fBLOCATION_IN_INPUT\fP is optional. \fBLOCATION_IN_INPUT\fP is included when the location that error is occurred in input file is collected. Input file can be specified by \fB\-\-file\fP command line option for \fBgroonga\fP command. \fBLOCATION_IN_GROONGA\fP is an array. \fBLOCATION_IN_GROONGA\fP has three elements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ INPUT_FILE_NAME, LINE_NUMBER, LINE_CONTENT ] .ft P .fi .UNINDENT .UNINDENT .sp \fBINPUT_FILE_NAME\fP is the input file name that error is occurred. .sp \fBLINE_NUMBER\fP is the line number of \fBINPUT_FILE_NAME\fP that error is occurred. .sp \fBLINE_CONTENT\fP is the content at \fBLINE_NUMBER\fP in \fBINPUT_FILE_NAME\fP\&. .SS \fBBODY\fP .sp \fBBODY\fP content depends on the executed command. It may be omitted. .sp \fBBODY\fP may be an error message on error case. .SS XML .sp TODO .SS TSV .sp TODO .SS See also .INDENT 0.0 .IP \(bu 2 \fBreturn_code\fP describes about return code. .UNINDENT .SS Return code .SS Summary .sp Return code is used to show whether a processing is succeeded or not. If the processing is not succeeded, return code shows error type. .sp Return code is used in C API and query API. You can check return code via \fBgrn_ctx_t::rc\fP in C API. You can check return code by looking the header element in query API. See \fBoutput_format\fP about the header element in query API. .SS List .sp Here is a list of return codes. \fBGRN_SUCCESS\fP (= 0) means that the processing is succeeded. Return codes that have negative value show error type. \fBGRN_END_OF_DATA\fP is a special return code. It is used only C API. It is not showen in query API. .INDENT 0.0 .IP \(bu 2 0: \fBGRN_SUCCESS\fP .IP \(bu 2 1: \fBGRN_END_OF_DATA\fP .IP \(bu 2 \-1: \fBGRN_UNKNOWN_ERROR\fP .IP \(bu 2 \-2: \fBGRN_OPERATION_NOT_PERMITTED\fP .IP \(bu 2 \-3: \fBGRN_NO_SUCH_FILE_OR_DIRECTORY\fP .IP \(bu 2 \-4: \fBGRN_NO_SUCH_PROCESS\fP .IP \(bu 2 \-5: \fBGRN_INTERRUPTED_FUNCTION_CALL\fP .IP \(bu 2 \-6: \fBGRN_INPUT_OUTPUT_ERROR\fP .IP \(bu 2 \-7: \fBGRN_NO_SUCH_DEVICE_OR_ADDRESS\fP .IP \(bu 2 \-8: \fBGRN_ARG_LIST_TOO_LONG\fP .IP \(bu 2 \-9: \fBGRN_EXEC_FORMAT_ERROR\fP .IP \(bu 2 \-10: \fBGRN_BAD_FILE_DESCRIPTOR\fP .IP \(bu 2 \-11: \fBGRN_NO_CHILD_PROCESSES\fP .IP \(bu 2 \-12: \fBGRN_RESOURCE_TEMPORARILY_UNAVAILABLE\fP .IP \(bu 2 \-13: \fBGRN_NOT_ENOUGH_SPACE\fP .IP \(bu 2 \-14: \fBGRN_PERMISSION_DENIED\fP .IP \(bu 2 \-15: \fBGRN_BAD_ADDRESS\fP .IP \(bu 2 \-16: \fBGRN_RESOURCE_BUSY\fP .IP \(bu 2 \-17: \fBGRN_FILE_EXISTS\fP .IP \(bu 2 \-18: \fBGRN_IMPROPER_LINK\fP .IP \(bu 2 \-19: \fBGRN_NO_SUCH_DEVICE\fP .IP \(bu 2 \-20: \fBGRN_NOT_A_DIRECTORY\fP .IP \(bu 2 \-21: \fBGRN_IS_A_DIRECTORY\fP .IP \(bu 2 \-22: \fBGRN_INVALID_ARGUMENT\fP .IP \(bu 2 \-23: \fBGRN_TOO_MANY_OPEN_FILES_IN_SYSTEM\fP .IP \(bu 2 \-24: \fBGRN_TOO_MANY_OPEN_FILES\fP .IP \(bu 2 \-25: \fBGRN_INAPPROPRIATE_I_O_CONTROL_OPERATION\fP .IP \(bu 2 \-26: \fBGRN_FILE_TOO_LARGE\fP .IP \(bu 2 \-27: \fBGRN_NO_SPACE_LEFT_ON_DEVICE\fP .IP \(bu 2 \-28: \fBGRN_INVALID_SEEK\fP .IP \(bu 2 \-29: \fBGRN_READ_ONLY_FILE_SYSTEM\fP .IP \(bu 2 \-30: \fBGRN_TOO_MANY_LINKS\fP .IP \(bu 2 \-31: \fBGRN_BROKEN_PIPE\fP .IP \(bu 2 \-32: \fBGRN_DOMAIN_ERROR\fP .IP \(bu 2 \-33: \fBGRN_RESULT_TOO_LARGE\fP .IP \(bu 2 \-34: \fBGRN_RESOURCE_DEADLOCK_AVOIDED\fP .IP \(bu 2 \-35: \fBGRN_NO_MEMORY_AVAILABLE\fP .IP \(bu 2 \-36: \fBGRN_FILENAME_TOO_LONG\fP .IP \(bu 2 \-37: \fBGRN_NO_LOCKS_AVAILABLE\fP .IP \(bu 2 \-38: \fBGRN_FUNCTION_NOT_IMPLEMENTED\fP .IP \(bu 2 \-39: \fBGRN_DIRECTORY_NOT_EMPTY\fP .IP \(bu 2 \-40: \fBGRN_ILLEGAL_BYTE_SEQUENCE\fP .IP \(bu 2 \-41: \fBGRN_SOCKET_NOT_INITIALIZED\fP .IP \(bu 2 \-42: \fBGRN_OPERATION_WOULD_BLOCK\fP .IP \(bu 2 \-43: \fBGRN_ADDRESS_IS_NOT_AVAILABLE\fP .IP \(bu 2 \-44: \fBGRN_NETWORK_IS_DOWN\fP .IP \(bu 2 \-45: \fBGRN_NO_BUFFER\fP .IP \(bu 2 \-46: \fBGRN_SOCKET_IS_ALREADY_CONNECTED\fP .IP \(bu 2 \-47: \fBGRN_SOCKET_IS_NOT_CONNECTED\fP .IP \(bu 2 \-48: \fBGRN_SOCKET_IS_ALREADY_SHUTDOWNED\fP .IP \(bu 2 \-49: \fBGRN_OPERATION_TIMEOUT\fP .IP \(bu 2 \-50: \fBGRN_CONNECTION_REFUSED\fP .IP \(bu 2 \-51: \fBGRN_RANGE_ERROR\fP .IP \(bu 2 \-52: \fBGRN_TOKENIZER_ERROR\fP .IP \(bu 2 \-53: \fBGRN_FILE_CORRUPT\fP .IP \(bu 2 \-54: \fBGRN_INVALID_FORMAT\fP .IP \(bu 2 \-55: \fBGRN_OBJECT_CORRUPT\fP .IP \(bu 2 \-56: \fBGRN_TOO_MANY_SYMBOLIC_LINKS\fP .IP \(bu 2 \-57: \fBGRN_NOT_SOCKET\fP .IP \(bu 2 \-58: \fBGRN_OPERATION_NOT_SUPPORTED\fP .IP \(bu 2 \-59: \fBGRN_ADDRESS_IS_IN_USE\fP .IP \(bu 2 \-60: \fBGRN_ZLIB_ERROR\fP .IP \(bu 2 \-61: \fBGRN_LZO_ERROR\fP .IP \(bu 2 \-62: \fBGRN_STACK_OVER_FLOW\fP .IP \(bu 2 \-63: \fBGRN_SYNTAX_ERROR\fP .IP \(bu 2 \-64: \fBGRN_RETRY_MAX\fP .IP \(bu 2 \-65: \fBGRN_INCOMPATIBLE_FILE_FORMAT\fP .IP \(bu 2 \-66: \fBGRN_UPDATE_NOT_ALLOWED\fP .IP \(bu 2 \-67: \fBGRN_TOO_SMALL_OFFSET\fP .IP \(bu 2 \-68: \fBGRN_TOO_LARGE_OFFSET\fP .IP \(bu 2 \-69: \fBGRN_TOO_SMALL_LIMIT\fP .IP \(bu 2 \-70: \fBGRN_CAS_ERROR\fP .IP \(bu 2 \-71: \fBGRN_UNSUPPORTED_COMMAND_VERSION\fP .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fBoutput_format\fP shows where return code is appeared in query API response. .IP \(bu 2 \fB/spec/gqtp\fP: GQTP protocol also uses return code as status but it uses 2byte unsigned integer. So return codes that have negative value are statuses that have positive value in GQTP protocol. You can convert status value in GQTP protocol to return code by handling it as 2byte signed integer. .UNINDENT .SS \fBcache_limit\fP .SS Summary .sp \fBcache_limit\fP gets or sets the max number of query cache entries. Query cache is used only by \fBselect\fP command. .sp If the max number of query cache entries is 100, the recent 100 \fBselect\fP commands are only cached. The cache expire algorithm is LRU (least recently used). .SS Syntax .sp \fBcache_limit\fP has one optional parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_limit [max=null] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp You can get the current max number of cache entries by executing \fBcache_limit\fP without parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_limit # [[0, 1337566253.89858, 0.000355720520019531], 100] .ft P .fi .UNINDENT .UNINDENT .sp You can set the max number of cache entries by executing \fBcache_limit\fP with \fBmax\fP parameter. .sp Here is an example that sets \fB10\fP as the max number of cache entries. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_limit 10 # [[0, 1337566253.89858, 0.000355720520019531], 100] cache_limit # [[0, 1337566253.89858, 0.000355720520019531], 10] .ft P .fi .UNINDENT .UNINDENT .sp If \fBmax\fP parameter is used, the return value is the max number of cache entries before \fBmax\fP parameter is set. .SS Parameters .sp This section describes all parameters. .SS \fBmax\fP .sp It specifies the max number of query cache entries as a number. .sp If \fBmax\fP parameter isn\(aqt specified, the current max number of query cache entries isn\(aqt changed. \fBcache_limit\fP just returns the current max number of query cache entries. .SS Return value .sp \fBcache_limit\fP returns the current max number of query cache entries: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, N_ENTRIES] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBN_ENTRIES\fP .INDENT 0.0 .INDENT 3.5 \fBN_ENTRIES\fP is the current max number of query cache entries. It is a number. .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fBselect\fP .UNINDENT .SS \fBcheck\fP .SS Summary .sp check \- オブジェクトの状態表示 .sp Groonga組込コマンドの一つであるcheckについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp checkコマンドは、groongaプロセス内の指定したオブジェクトの状態を表示します。主にデータベースが壊れた場合など異常時の問題解決のために使用することを想定しています。デバッグ用のため、返値のフォーマットが安定しているということは保証されません。（フォーマットが変更される可能性が高い） .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check obj .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp テーブルTermsのインデックスカラムnameの状態を表示します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check Terms.name [{"flags":"00008202", "max sid":1, "number of garbage segments":0, "number of array segments":1, "max id of array segment":1, "number of buffer segments":110, "max id of buffer segment":111, "max id of physical segment in use":111, "number of unmanaged segments":4294967185, "total chunk size":7470239, "max id of chunk segments in use":127, "number of garbage chunk":[0,0,0,0,0,0,0,0,2,2,0,0,0,0,0]}, {"buffer id":0, "chunk size":94392, "buffer term":["596","59777","6",...], "buffer free":152944, "size in buffer":7361, "nterms":237, "nterms with chunk":216, "buffer id":1, "chunk size":71236, "buffer term":[["に述",18149,18149,2,25,6,6], ["に追",4505,4505,76,485,136,174], ["に退",26568,26568,2,9,2,2], ...], "buffer free":120000, "size in buffer":11155, "nterms":121, "nterms with chunk":116}, {"buffer id":1, ...}, ...] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBobj\fP .INDENT 0.0 .INDENT 3.5 状態を表示するオブジェクトの名前を指定します。 .UNINDENT .UNINDENT .SS Return value .sp チェックするオブジェクトにより返される値が変わります。 .sp インデックスカラムの場合: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 下記のような配列が出力されます。 [インデックスの状態, バッファの状態1, バッファの状態2, ...] .ft P .fi .UNINDENT .UNINDENT .sp \fBインデックスの状態\fP には下記の項目がハッシュ形式で出力されます。 .INDENT 0.0 .INDENT 3.5 \fBflags\fP .INDENT 0.0 .INDENT 3.5 指定されているフラグ値です。16進数で表現されています。 .UNINDENT .UNINDENT .sp \fBmax sid\fP .INDENT 0.0 .INDENT 3.5 セグメントのうち最も大きなIDです。 .UNINDENT .UNINDENT .sp \fBnumber of garbage segments\fP .INDENT 0.0 .INDENT 3.5 ゴミセグメントの数です。 .UNINDENT .UNINDENT .sp \fBnumber of array segments\fP .INDENT 0.0 .INDENT 3.5 配列セグメントの数です。 .UNINDENT .UNINDENT .sp \fBmax id of array segment\fP .INDENT 0.0 .INDENT 3.5 配列セグメントのうち最も大きなIDです。 .UNINDENT .UNINDENT .sp \fBnumber of buffer segments\fP .INDENT 0.0 .INDENT 3.5 バッファセグメントの数です。 .UNINDENT .UNINDENT .sp \fBmax id of buffer segment\fP .INDENT 0.0 .INDENT 3.5 バッファセグメントのうち最も大きなIDです。 .UNINDENT .UNINDENT .sp \fBmax id of physical segment in use\fP .INDENT 0.0 .INDENT 3.5 使用中の論理セグメントのうち最も大きなIDです。 .UNINDENT .UNINDENT .sp \fBnumber of unmanaged segments\fP .INDENT 0.0 .INDENT 3.5 管理されていないセグメントの数です。 .UNINDENT .UNINDENT .sp \fBtotal chunk size\fP .INDENT 0.0 .INDENT 3.5 チャンクサイズの合計です。 .UNINDENT .UNINDENT .sp \fBmax id of chunk segments in use\fP .INDENT 0.0 .INDENT 3.5 使用中のチャンクセグメントのうち最も大きなIDです。 .UNINDENT .UNINDENT .sp \fBnumber of garbage chunk\fP .INDENT 0.0 .INDENT 3.5 各チャンク毎のゴミの数です。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBバッファの状態\fP には下記の項目がハッシュ形式で出力されます。 .INDENT 0.0 .INDENT 3.5 \fBbuffer id\fP .INDENT 0.0 .INDENT 3.5 バッファIDです。 .UNINDENT .UNINDENT .sp \fBchunk size\fP .INDENT 0.0 .INDENT 3.5 チャンクのサイズです。 .UNINDENT .UNINDENT .sp \fBbuffer term\fP .INDENT 0.0 .INDENT 3.5 バッファ内にある語の一覧です。各語の状態は以下のような配列となっています。 .INDENT 0.0 .INDENT 3.5 [語, バッファに登録されている語のID, 用語集に登録されている語のID, バッファ内でのサイズ, チャンク内でのサイズ] .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBbuffer free\fP .INDENT 0.0 .INDENT 3.5 バッファの空き容量です。 .UNINDENT .UNINDENT .sp \fBsize in buffer\fP .INDENT 0.0 .INDENT 3.5 バッファの使用量です。 .UNINDENT .UNINDENT .sp \fBnterms\fP .INDENT 0.0 .INDENT 3.5 バッファ内にある語の数です。 .UNINDENT .UNINDENT .sp \fBnterms with chunk\fP .INDENT 0.0 .INDENT 3.5 バッファ内にある語のうち、チャンクを使っている語の数です。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fBclearlock\fP .SS Summary .sp clearlock \- オブジェクトにセットされたロックを解除する .sp Groonga組込コマンドの一つであるclearlockについて説明します。組込コマンドは、groonga実行ファイルの引数、標準>入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp clearlockは、対象となるオブジェクト(データベース,テーブル,インデックス等)を指定し、オブジェクトにかけられた>ロックを再帰的に解除します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clearlock objname .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp 開いているデータベースのロックをすべて解除する: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clearlock [true] .ft P .fi .UNINDENT .UNINDENT .sp テーブル名 Entry のカラム body のロックを解除する: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clearlock Entry.body [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBobjname\fP .INDENT 0.0 .INDENT 3.5 対象となるオブジェクト名を指定します。空の場合、開いているdbオブジェクトが対象となります。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS See also .sp \fBload\fP .SS \fBcolumn_create\fP .SS Summary .sp column_create \- カラムの追加 .sp Groonga組込コマンドの一つであるcolumn_createについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp column_createは、使用しているデータベースのテーブルに対してカラムを追加します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create table name flags type [source] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp テーブルEntryに、ShortText型の値を格納するカラム、bodyを作成します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create Entry body \-\-type ShortText [true] .ft P .fi .UNINDENT .UNINDENT .sp テーブルTermに、Entryテーブルのbodyカラムの値を対象とする完全転置インデックス型カラム、entry_bodyを作成します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create Term entry_body COLUMN_INDEX|WITH_POSITION Entry body [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 カラムを追加するテーブルの名前を指定します。 .UNINDENT .UNINDENT .sp \fBname\fP .INDENT 0.0 .INDENT 3.5 作成するカラムの名前を指定します。カラム名は、テーブルの中で一意でなければなりません。 .sp ピリオド(\(aq.\(aq), コロン(\(aq:\(aq)を含む名前のカラムは作成できません。また、アンダースコア(\(aq_\(aq)で始まる名前は予約済みであり、使用できません。 .UNINDENT .UNINDENT .sp \fBflags\fP .INDENT 0.0 .INDENT 3.5 カラムの属性を表す以下の数値か、パイプ(\(aq|\(aq)で組み合わせたシンボル名を指定します。 .INDENT 0.0 .TP .B 0, \fBCOLUMN_SCALAR\fP 単一の値が格納できるカラムを作成します。 .TP .B 1, \fBCOLUMN_VECTOR\fP 複数の値の配列を格納できるカラムを作成します。 .TP .B 2, \fBCOLUMN_INDEX\fP インデックス型のカラムを作成します。 .UNINDENT .sp There are two flags to compress the value of column, but you can\(aqt specify these flags for now because there are memory leaks issue \fI\%GitHub#6\fP when refers the value of column. This issue occurs both of them (zlib and lzo). .INDENT 0.0 .TP .B 16, \fBCOMPRESS_ZLIB\fP Reserved. Compress the value of column by using zlib. This flag is disabled feature even if you build groonga with \fB\-\-with\-zlib\fP\&. .TP .B 32, \fBCOMPRESS_LZO\fP Reserved. Compress the value of column by using lzo. This flag is disabled feature even if you build groonga with \fB\-\-with\-lzo\fP\&. .UNINDENT .sp インデックス型のカラムについては、flagsの値に以下の値を加えることによって、追加の属 性を指定することができます。 .INDENT 0.0 .TP .B 128, \fBWITH_SECTION\fP 段落情報を格納するインデックスを作成します。 .TP .B 256, \fBWITH_WEIGHT\fP ウェイト情報を格納するインデックスを作成します。 .TP .B 512, \fBWITH_POSITION\fP 位置情報を格納するインデックス(完全転置インデックス)を作成します。 .UNINDENT .UNINDENT .UNINDENT .sp \fBtype\fP .INDENT 0.0 .INDENT 3.5 値の型を指定します。Groongaの組込型か、同一データベースに定義済みのユーザ定義型、定義済みのテーブルを指定することができます。 .UNINDENT .UNINDENT .sp \fBsource\fP .INDENT 0.0 .INDENT 3.5 インデックス型のカラムを作成した場合は、インデックス対象となるカラムをsource引数に指定します。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, SUCCEEDED] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBSUCCEEDED\fP .INDENT 0.0 .INDENT 3.5 If command is succeeded, it returns true on success, false otherwise. .UNINDENT .UNINDENT .SS \fBcolumn_list\fP .SS Summary .sp \fBcolumn_list\fP command lists columns in a table. .SS Syntax .sp \fBcolumn_list\fP command takes one required parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_list table .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example of \fBcolumn_list\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Users TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users age COLUMN_SCALAR UInt8 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users tags COLUMN_VECTOR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_list Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # "id", # "UInt32" # ], # [ # "name", # "ShortText" # ], # [ # "path", # "ShortText" # ], # [ # "type", # "ShortText" # ], # [ # "flags", # "ShortText" # ], # [ # "domain", # "ShortText" # ], # [ # "range", # "ShortText" # ], # [ # "source", # "ShortText" # ] # ], # [ # 256, # "_key", # "", # "", # "COLUMN_SCALAR", # "Users", # "ShortText", # [] # ], # [ # 257, # "age", # "/tmp/groonga\-databases/commands_column_list.0000101", # "fix", # "COLUMN_SCALAR|PERSISTENT", # "Users", # "UInt8", # [] # ], # [ # 258, # "tags", # "/tmp/groonga\-databases/commands_column_list.0000102", # "var", # "COLUMN_VECTOR|PERSISTENT", # "Users", # "ShortText", # [] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp This section describes parameters of \fBcolumn_list\fP\&. .SS Required parameters .sp All parameters are required. .SS \fBtable\fP .sp It specifies the name of table to be listed columns. .SS Return value .sp \fBcolumn_list\fP returns the list of column information in the table: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ HEADER, [ COLUMN_LIST_HEADER, COLUMN_INFORMATION1, COLUMN_INFORMATION2, ... ] ] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBCOLUMN_LIST_HEADER\fP .INDENT 0.0 .INDENT 3.5 \fBCOLUMN_LIST_HEADER\fP describes about content of each \fBCOLUMN_INFORMATION\fP\&. .sp \fBCOLUMN_LIST_HEADER\fP is the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ ["id", "UInt32"], ["name", "ShortText"], ["path", "ShortText"], ["type", "ShortText"], ["flags", "ShortText"], ["domain", "ShortText"], ["range", "ShortText"], ["source", "ShortText"] ] .ft P .fi .UNINDENT .UNINDENT .sp It means the following: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 The first content in \fBCOLUMN_INFORMATION\fP is \fBid\fP value and the value type is \fBUInt32\fP\&. .IP \(bu 2 The second content in \fBCOLUMN_INFORMATION\fP is \fBname\fP value and the value type is \fBShortText\fP\&. .IP \(bu 2 The third content .... .UNINDENT .UNINDENT .UNINDENT .sp See the following \fBCOLUMN_INFORMATION\fP description for details. .sp This field provides meta\-data of column information. So this field will be useful for programs rather than humans. .UNINDENT .UNINDENT .sp \fBCOLUMN_INFORMATION\fP .INDENT 0.0 .INDENT 3.5 Each \fBCOLUMN_INFORMATION\fP is the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ ID, NAME, PATH, TYPE, FLAGS, DOMAIN, RANGE, SOURCES ] .ft P .fi .UNINDENT .UNINDENT .sp \fBID\fP .INDENT 0.0 .INDENT 3.5 The column ID in the Groonga database. Normally, you don\(aqt care about it. .UNINDENT .UNINDENT .sp \fBNAME\fP .INDENT 0.0 .INDENT 3.5 The column name. .UNINDENT .UNINDENT .sp \fBPATH\fP .INDENT 0.0 .INDENT 3.5 The path for storing column data. .UNINDENT .UNINDENT .sp \fBTYPE\fP .INDENT 0.0 .INDENT 3.5 The type of the column. It is one of the followings: .TS center; |l|l|. _ T{ Value T} T{ Description T} _ T{ \fBfix\fP T} T{ The column is a fixed size column. Scalar column that its type is fixed size type is fixed size column. T} _ T{ \fBvar\fP T} T{ The column is a variable size column. Vector column or scalar column that its type is variable size type are variable size column. T} _ T{ \fBindex\fP T} T{ The column is an index column. T} _ .TE .UNINDENT .UNINDENT .sp \fBFLAGS\fP .INDENT 0.0 .INDENT 3.5 The flags of the column. Each flag is separated by \fB|\fP like \fBCOLUMN_VECTOR|WITH_WEIGHT\fP\&. \fBFLAGS\fP must include one of \fBCOLUMN_SCALAR\fP, \fBCOLUMN_VECTOR\fP or \fBCOLUMN_INDEX\fP\&. Other flags are optional. .sp Here is the available flags: .TS center; |l|l|. _ T{ Flag T} T{ Description T} _ T{ \fBCOLUMN_SCALAR\fP T} T{ The column is a scalar column. T} _ T{ \fBCOLUMN_VECTOR\fP T} T{ The column is a vector column. T} _ T{ \fBCOLUMN_INDEX\fP T} T{ The column is an index column. T} _ T{ \fBWITH_WEIGHT\fP T} T{ The column can have weight. \fBCOLUMN_VECTOR\fP and \fBCOLUMN_INDEX\fP may have it. \fBCOLUMN_SCALAR\fP doesn\(aqt have it. T} _ T{ \fBWITH_SECTION\fP T} T{ The column can have section information. \fBCOLUMN_INDEX\fP may have it. \fBCOLUMN_SCALAR\fP and \fBCOLUMN_VECTOR\fP don\(aqt have it. .sp Multiple column index has it. T} _ T{ \fBWITH_POSITION\fP T} T{ The column can have position information. \fBCOLUMN_INDEX\fP may have it. \fBCOLUMN_SCALAR\fP and \fBCOLUMN_VECTOR\fP don\(aqt have it. .sp Full text search index must has it. T} _ T{ \fBPERSISTENT\fP T} T{ The column is a persistent column. It means that the column isn\(aqt a \fB/reference/columns/pseudo\fP\&. T} _ .TE .UNINDENT .UNINDENT .sp \fBDOMAIN\fP .INDENT 0.0 .INDENT 3.5 The name of table that has the column. .UNINDENT .UNINDENT .sp \fBRANGE\fP .INDENT 0.0 .INDENT 3.5 The value type name of the column. It is a type name or a table name. .UNINDENT .UNINDENT .sp \fBSOURCES\fP .INDENT 0.0 .INDENT 3.5 An array of the source column names of the index. If the index column is multiple column index, the array has two or more source column names. .sp It is always an empty array for \fBCOLUMN_SCALAR\fP and \fBCOLUMN_VECTOR\fP\&. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/column_create\fP .IP \(bu 2 \fB/reference/column\fP .UNINDENT .SS \fBcolumn_remove\fP .SS Summary .sp column_remove \- テーブルに定義されているカラムの削除 .sp Groonga組込コマンドの一つであるcolumn_removeについて説明します。組込コマンドは、groonga実行ファイルの引数、>標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp column_removeはテーブルに定義されているカラムを削除します。 また、付随するインデックスも削除されます。[1] .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_remove table name .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_remove Entry body [true] .ft P .fi .UNINDENT .UNINDENT 脚注 .IP [1] 5 マルチセクションインデックスの一部である場合も、インデックスが削除されます。 .SS Parameters .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 削除対象のカラムが定義されているテーブルの名前を指定します。 .UNINDENT .UNINDENT .sp \fBname\fP .INDENT 0.0 .INDENT 3.5 削除対象のカラム名を指定します。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS \fBcolumn_rename\fP .SS Summary .sp \fBcolumn_rename\fP command renames a column. .sp It is a light operation. It just changes a relationship between name and the column object. It doesn\(aqt copy column values. .sp It is a dangerous operation. You must stop all operations including read operations while you run \fBcolumn_rename\fP\&. If the following case is occurred, Groonga process may be crashed: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Starts an operation (like \fBselect\fP) that accesses the column to be renamed by the current column name. The current column name is called as \fBthe old column name\fP in the below because the column name is renamed. .IP \(bu 2 Runs \fBcolumn_rename\fP\&. The \fBselect\fP is still running. .IP \(bu 2 The \fBselect\fP accesses the column to be renamed by the old column name. But the \fBselect\fP can\(aqt find the column by the old name because the column has been renamed to the new column name. It may crash the Groonga process. .UNINDENT .UNINDENT .UNINDENT .SS Syntax .sp \fBcolumn_rename\fP command takes three parameters. All parameters are required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_rename table name new_name .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example of \fBcolumn_rename\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Users TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users score COLUMN_SCALAR Int32 # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Users [ {"_key": "Alice", "score": 2}, {"_key": "Bob", "score": 0}, {"_key": "Carlos", "score": \-1} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] column_rename Users score point # [[0, 1337566253.89858, 0.000355720520019531], true] column_list Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # "id", # "UInt32" # ], # [ # "name", # "ShortText" # ], # [ # "path", # "ShortText" # ], # [ # "type", # "ShortText" # ], # [ # "flags", # "ShortText" # ], # [ # "domain", # "ShortText" # ], # [ # "range", # "ShortText" # ], # [ # "source", # "ShortText" # ] # ], # [ # 256, # "_key", # "", # "", # "COLUMN_SCALAR", # "Users", # "ShortText", # [] # ], # [ # 257, # "point", # "/tmp/groonga\-databases/commands_column_rename.0000101", # "fix", # "COLUMN_SCALAR|PERSISTENT", # "Users", # "Int32", # [] # ] # ] # ] select Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "point", # "Int32" # ] # ], # [ # 1, # "Alice", # 2 # ], # [ # 2, # "Bob", # 0 # ], # [ # 3, # "Carlos", # \-1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp This section describes parameters of \fBcolumn_rename\fP\&. .SS Required parameters .sp All parameters are required. .SS \fBtable\fP .sp It specifies the name of table that has the column to be renamed. .SS \fBname\fP .sp It specifies the column name to be renamed. .SS \fBnew_name\fP .sp It specifies the new column name. .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, SUCCEEDED_OR_NOT] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBSUCCEEDED_OR_NOT\fP .INDENT 0.0 .INDENT 3.5 It is \fBtrue\fP on success, \fBfalse\fP otherwise. .UNINDENT .UNINDENT .SS \fBdefine_selector\fP .SS Summary .sp define_selector \- 検索コマンドを定義 .sp Groonga組込コマンドの一つであるdefine_selectorについて説明します。組込コマンドは、groonga実行ファイルの引数>、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp define_selectorは、検索条件をカスタマイズした新たな検索コマンドを定義します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C define_selector name table [match_columns [query [filter [scorer [sortby [output_columns [offset [limit [drilldown [drilldown_sortby [drilldown_output_columns [drilldown_offset [drilldown_limit]]]]]]]]]]]]] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp テーブルEntryの全レコード・全カラムの値を出力するselectorコマンドを定義します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C define_selector entry_selector Entry [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBname\fP .INDENT 0.0 .INDENT 3.5 定義するselectorコマンドの名前を指定します。 .UNINDENT .UNINDENT .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 検索対象のテーブルを指定します。 .UNINDENT .UNINDENT .sp \fBmatch_columns\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのmatch_columns引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBquery\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのquery引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBfilter\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのfilter引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBscorer\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのscorer引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBsortby\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのsortby引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBoutput_columns\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのoutput_columns引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBoffset\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのoffset引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBlimit\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのlimit引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのdrilldown引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown_sortby\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのdrilldown_sortby引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown_output_columns\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのdrilldown_output_columns引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown_offset\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのdrilldown_offset引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown_limit\fP .INDENT 0.0 .INDENT 3.5 追加するselectorコマンドのdrilldown_limit引数のデフォルト値を指定します。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS See also .sp \fB/reference/grn_expr\fP .SS \fBdefrag\fP .SS Summary .sp \fBdefrag\fP command resolves fragmentation of specified objects. .sp Groonga組込コマンドの一つであるdefragについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力 、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp defragは、対象となるオブジェクト(データベースか可変長サイズカラム)を指定し、オブジェクトのフラグメンテーショ ンを解消します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C defrag objname threshold .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp 開いているデータベースのフラグメンテーションを解消する: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C defrag [300] .ft P .fi .UNINDENT .UNINDENT .sp テーブル名 Entry のカラム body のフラグメンテーションを解消する: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C defrag Entry.body [30] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBobjname\fP .INDENT 0.0 .INDENT 3.5 対象となるオブジェクト名を指定します。空の場合、開いているdbオブジェクトが対象となります。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [フラグメンテーション解消を実行したセグメントの数] .ft P .fi .UNINDENT .UNINDENT .sp \fBフラグメンテーション解消を実行したセグメントの数\fP .INDENT 0.0 .INDENT 3.5 フラグメンテーション解消を実行したセグメントの数を返す。 .UNINDENT .UNINDENT .SS \fBdelete\fP .SS Summary .sp \fBdelete\fP command deletes specified record of table. .SS Cascade delete .sp There is a case that multiple table is associated. For example, the key of one table are referenced by other table\(aqs records. In such a case, if you delete the key of one table, other table\(aqs records are also removed. .sp Note that the type of other table\(aqs column is COLUMN_VECTOR, only the value of referencing key is removed from the vector value. .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete table [key [id [filter]]] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Delete the record from Entry table which has "2" as the key. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete Entry 2 # [[0, 1337566253.89858, 0.000355720520019531], true] select Entry # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "UInt32" # ], # [ # "status", # "ShortText" # ] # ], # [ # 1, # 1, # "OK" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is the example about cascaded delete. .sp The country column of Users table associates with Country table. .sp "Cascaded delete" removes the records which matches specified key and refers that key. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Country TABLE_HASH_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Users TABLE_HASH_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users name COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users country COLUMN_SCALAR Country # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Users [ {"_key": 1, "name": "John", country: "United States"} {"_key": 2, "name": "Mike", country: "United States"} {"_key": 3, "name": "Takashi", country: "Japan"} {"_key": 4, "name": "Hanako", country: "Japan"} ] # [[0, 1337566253.89858, 0.000355720520019531], 4] load \-\-table Country [ {"_key": "United States"} {"_key": "Japan"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] delete Country "United States" # [[0, 1337566253.89858, 0.000355720520019531], true] select Country # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 2, # "Japan" # ] # ] # ] # ] select Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "UInt32" # ], # [ # "country", # "Country" # ], # [ # "name", # "ShortText" # ] # ], # [ # 1, # 1, # "", # "John" # ], # [ # 2, # 2, # "", # "Mike" # ], # [ # 3, # 3, # "Japan", # "Takashi" # ], # [ # 4, # 4, # "Japan", # "Hanako" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 It specifies the name of table to delete the records. .UNINDENT .UNINDENT .sp \fBkey\fP .INDENT 0.0 .INDENT 3.5 It specifies the key of record to delete. If you use the table with TABLE_NO_KEY, the key is just ignored. (Use \fBid\fP parameter in such a case) .UNINDENT .UNINDENT .sp \fBid\fP .INDENT 0.0 .INDENT 3.5 It specifies the id of record to delete. If you specify \fBid\fP parameter, you must not specify \fBkey\fP parameter. .UNINDENT .UNINDENT .sp \fBfilter\fP .INDENT 0.0 .INDENT 3.5 It specifies the expression of grn_expr to identify the record. If you specify \fBfilter\fP parameter, you must not specify \fBkey\fP and \fBid\fP parameter. .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, SUCCEEDED_OR_NOT] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBSUCCEEDED_OR_NOT\fP .INDENT 0.0 .INDENT 3.5 If command succeeded, it returns true, otherwise it returns false on error. .UNINDENT .UNINDENT .SS See also .sp \fBload\fP .SS \fBdump\fP .SS Summary .sp dump \- データベースのスキーマとデータを出力する .sp Groonga組込コマンドの一つであるdumpについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、 またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp dumpはデータベースのスキーマとデータを後から読み込めるフォーマットで出力します。dumpの結果は大きくなるため、 主にコマンドラインから使うことを想定しています。データベースのバックアップが主な利用方法です。 .sp dumpが出力するフォーマットは直接Groongaが解釈できるフォーマットです。そのため、以下のようにしてデータベース>をコピーすることができます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % groonga original/db dump > dump.grn % mkdir backup % groonga \-n backup/db < dump.grn .ft P .fi .UNINDENT .UNINDENT .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dump [tables] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp データベース内のすべてのデータを出力: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > dump table_create LocalNames 48 ShortText table_create Entries 48 ShortText column_create Entries local_name 0 LocalNames column_create LocalNames Entries_local_name 2 Entries local_name \&... load \-\-table LocalNames [ ["_key"], ["Items"], ["BLT"], \&... ] \&... .ft P .fi .UNINDENT .UNINDENT .sp データベース内のスキーマと特定のテーブルのデータのみ出力: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > dump \-\-tables Users,Sites table_create Users TABLE_HASH_KEY ShortText column_create Users name COLUMN_SCALAR ShortText table_create Comments TABLE_PAT_KEY ShortText column_create Comments text COLUMN_SCALAR ShortText table_create Sites TABLE_NO_KEY column_create Sites url COLUMN_SCALAR ShortText load \-\-table Users [ ["_key"], ["mori"], ["yu"], \&... ] load \-\-table Sites [ ["_id","url"], [1,"http://groonga.org/"], [2,"http://qwik.jp/senna/"], \&... ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBtables\fP .INDENT 0.0 .INDENT 3.5 出力対象のテーブルを「,」（カンマ）区切りで指定します。存在しないテーブルを指定した場合は無視されます。 .UNINDENT .UNINDENT .SS Return value .sp データベースのスキーマとデータをGroongaの組み込みコマンド呼び出し形式で出力します。output_type指定は無視されます。 .SS \fBload\fP .SS Summary .sp \fBload\fP loads data as records in the current database and updates values of each columns. .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load values table [columns [ifexists [input_type]]] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp This section describes all parameters. .sp \fBvalues\fP .INDENT 0.0 .INDENT 3.5 It specifies values loaded to records. Values should satisfy \fBinput_type\fP format. If you specify "json" as \fBinput_type\fP, you can choose a format from below: .INDENT 0.0 .TP .B \fBFormat 1:\fP [[COLUMN_NAME1, COLUMN_NAME2,..], [VALUE1, VALUE2,..], [VALUE1, VALUE2,..],..] .TP .B \fBFormat 2:\fP [{COLUMN_NAME1: VALUE1, COLUMN_NAME2: VALUE2}, {COLUMN_NAME1: VALUE1, COLUMN_NAME2: VALUE2},..] .UNINDENT .sp \fB[COLUMN_NAME1, COLUMN_NAME2,..]\fP format in \fBFormat 1\fP is effective only when \fBcolumn\fP parameter isn\(aqt specified. .sp When a target table contains primary key, you must specify \fB_key\fP column (pseudo column associated primary key) as the one of \fBCOLUMN_NAME\fP\&. .sp If \fBvalues\fP isn\(aqt specified any values, they are read from the standard input until all opened parenthes match their closed ones. You don\(aqt have to enclose them with single\-quotes or double\-quotes, but if you specified values with \fBvalues\fP parameter, you should do. .sp In following values, you also don\(aqt have to enclose any spaces (\(aq \(aq) with single\-quotes or double\-quotes. .UNINDENT .UNINDENT .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 It specifies a table name you want to add records. .UNINDENT .UNINDENT .sp \fBcolumns\fP .INDENT 0.0 .INDENT 3.5 It specifies column names in added records with comma separations. .UNINDENT .UNINDENT .sp \fBifexists\fP .INDENT 0.0 .INDENT 3.5 It specifies executed \fBgrn_expr\fP string when the same primary key as added records already exists in your table. If \fBifexists\fP specifies \fBgrn_expr\fP string (default: true) and its value is true, values in other (all columns excluding \fB_key\fP column) columns is updated. .UNINDENT .UNINDENT .sp \fBinput_type\fP .INDENT 0.0 .INDENT 3.5 It specifies an input format for \fBvalues\fP\&. It supports JSON only. .UNINDENT .UNINDENT .SS Usage .sp Here is an example to add records to "Entry" table. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Entry \-\-input_type json \-\-values [{\e"_key\e":\e"Groonga\e",\e"body\e":\e"It\(aqs very fast!!\e"}] [1] .ft P .fi .UNINDENT .UNINDENT .sp This example shows how to add values from standard input. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Entry \-\-input_type json [ {"_key": "Groonga", "body": "It\(aqs very fast!!"} ] [1] .ft P .fi .UNINDENT .UNINDENT .SS Return value .SS JSON format .INDENT 0.0 .INDENT 3.5 \fBload\fP returns the number of added records such as .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [NUMBER] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS See also .sp \fB/reference/grn_expr\fP .SS \fBlog_level\fP .SS Summary .sp log_level \- ログ出力レベルの設定 .sp Groonga組込コマンドの一つであるlog_levelについて説明します。組込コマンドは、groonga実行ファイルの引数、標準>入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_levelは、ログ出力レベルを設定します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level level .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level warning [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBlevel\fP .INDENT 0.0 .INDENT 3.5 設定するログ出力レベルの値を以下のいずれかで指定します。 .INDENT 0.0 .INDENT 3.5 EMERG ALERT CRIT error warning notice info debug .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS See also .sp \fBlog_put\fP \fBlog_reopen\fP .SS \fBlog_put\fP .SS Summary .sp log_put \- ログ出力 .sp groonga組込コマンドの一つであるlog_putについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入>力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_putは、ログにmessageを出力します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_put level message .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_put ERROR ****MESSAGE**** [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp \fBlevel\fP .INDENT 0.0 .INDENT 3.5 設定するログ出力レベルの値を以下のいずれかで指定します。 .INDENT 0.0 .INDENT 3.5 EMERG ALERT CRIT error warning notice info debug .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBmessage\fP .INDENT 0.0 .INDENT 3.5 出力する文字列を指定します。 .UNINDENT .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS See also .sp \fBlog_level\fP \fBlog_reopen\fP .SS \fBlog_reopen\fP .SS Summary .sp log_reopen \- ログファイルの再読み込み .sp Groonga組込コマンドの一つであるlog_reopenについて説明します。組込コマンドは、groonga実行ファイルの引数、標準 入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_reopenは、ログファイルを再読み込みします。 .sp 現在、デフォルトのログ関数を用いている場合のみに対応しています。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_reopen .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_reopen [true] .ft P .fi .UNINDENT .UNINDENT .SS log_reopenを用いたログのローテーション .INDENT 0.0 .IP 1. 3 ログファイルをmvなどで移動する。 ログはmvで移動された先のファイルに書き込まれる。 .IP 2. 3 log_reopenコマンドを実行する。 .IP 3. 3 既存のログファイル名と同じファイル名で、新たなログファイルが作成される。 今後のログは新たなログファイルに書き込まれる。 .UNINDENT .SS Parameters .sp ありません。 .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS See also .sp \fBlog_level\fP \fBlog_put\fP .SS \fBnormalize\fP .sp \fBCAUTION:\fP .INDENT 0.0 .INDENT 3.5 \fBnormalize\fP command is the experimental feature. This command may be changed in the future. .UNINDENT .UNINDENT .SS Summary .sp \fBnormalize\fP command normalizes text by the specified normalizer. .sp There is no need to create table to use \fBnormalize\fP command. It is useful for you to check the results of normalizer. .SS Syntax .sp \fBnormalize\fP commands has two required parameters. They are \fBnormalizer\fP and \fBstring\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C normalize normalizer string [flags=NONE] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example of \fBnormalize\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C normalize NormalizerAuto "aBcDe 123" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "normalized": "abcde 123", # "types": [], # "checks": [] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp This section describes parameters of \fBnormalizer\fP\&. .SS Required parameter .sp There are required parameters, \fBnormalizer\fP and \fBstring\fP\&. .SS \fBnormalizer\fP .sp It specifies the normalizer name. \fBnormalize\fP command uses the normalizer that is named \fBnormalizer\fP\&. .sp See \fB/reference/normalizers\fP about built\-in normalizers. .sp Here is an example to use built\-in \fBNormalizerAuto\fP normalizer. .sp TODO .sp If you want to use other normalizers, you need to register additional normalizer plugin by \fBregister\fP command. For example, you can use MySQL compatible normalizer by registering \fI\%groonga\-normalizer\-mysql\fP\&. .SS \fBstring\fP .sp It specifies any string which you want to normalize. .sp If you want to include spaces in \fBstring\fP, you need to quote \fBstring\fP by single quotation (\fB\(aq\fP) or double quotation (\fB"\fP). .sp Here is an example to use spaces in \fBstring\fP\&. .sp TODO .SS Optional parameters .sp There are optional parameters. .SS \fBflags\fP .sp It specifies a normalization customize options. You can specify multiple options separated by "\fB|\fP". For example, \fBREMOVE_BLANK|WITH_TYPES\fP\&. .sp Here are available flags. .TS center; |l|l|. _ T{ Flag T} T{ Description T} _ T{ \fBNONE\fP T} T{ Just ignored. T} _ T{ \fBREMOVE_BLANK\fP T} T{ TODO T} _ T{ \fBWITH_TYPES\fP T} T{ TODO T} _ T{ \fBWITH_CHECKS\fP T} T{ TODO T} _ T{ \fBREMOVE_TOKENIZED_DELIMITER\fP T} T{ TODO T} _ .TE .sp Here is an example that uses \fBREMOVE_BLANK\fP\&. .sp TODO .sp Here is an example that uses \fBWITH_TYPES\fP\&. .sp TODO .sp Here is an example that uses \fBREMOVE_TOKENIZED_DELIMITER\fP\&. .sp TODO .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, normalized_text] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBnormalized_text\fP .INDENT 0.0 .INDENT 3.5 \fBnormalized_text\fP is an object that has the following attributes. .TS center; |l|l|. _ T{ Name T} T{ Description T} _ T{ \fBnormalized\fP T} T{ The normalized text. T} _ T{ \fBtypes\fP T} T{ An array of types of the normalized text. The N\-th \fBtypes\fP shows the type of the N\-th character in \fBnormalized\fP\&. T} _ .TE .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/normalizers\fP .UNINDENT .SS \fBnormalizer_list\fP .SS Summary .sp \fBnormalizer_list\fP command lists normalizers in a database. .SS Syntax .sp \fBnormalizer_list\fP command takes no parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C normalizer_list .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C normalzer_list # [ # [ # 0, # 0.0, # 0.0 # ], # [ # { # "name": "NormalizerAuto" # }, # { # "name": "NormalizerNFKC51" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It returns normalizers in a database. .SS Return value .sp \fBnormalizer_list\fP command returns normalizers. Each normalizers has an attribute that contains the name. The attribute will be increased in the feature: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, normalizers] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBnormalizers\fP .INDENT 0.0 .INDENT 3.5 \fBnormalizers\fP is an array of normalizer. Normalizer is an object that has the following attributes. .TS center; |l|l|. _ T{ Name T} T{ Description T} _ T{ \fBname\fP T} T{ Normalizer name. T} _ .TE .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/normalizers\fP .IP \(bu 2 \fB/reference/commands/normalize\fP .UNINDENT .SS \fBquit\fP .SS Summary .sp quit \- セッション終了 .sp Groonga組込コマンドの一つであるquitについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、 またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp quitは、groongaプロセスとのセッションを終了します。クライアントプロセスならばgroongaプロセスとの接続を切りま す。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C quit .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C quit .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp ありません。 .SS Return value .sp ありません。 .SS \fBregister\fP .SS Summary .sp \fBregister\fP command registers a plugin. You need to register a plugin before you use a plugin. .sp You need just one \fBregister\fP command for a plugin in the same database because registered plugin information is written into the database. When you restart your \fBgroonga\fP process, \fBgroonga\fP process loads all registered plugins without \fBregister\fP command. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Registered plugins can\(aqt be removed for now. .UNINDENT .UNINDENT .SS Syntax .sp \fBregister\fP has a parameter \fBpath\fP\&. It is required parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register path .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a sample that registers \fBQueryExpanderTSV\fP query expander that is included in \fB${PREFIX}/lib/groonga/plugins/query_expanders/tsv.so\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register query_expanders/tsv # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp You can omit \fB${PREFIX}/lib/groonga/plugins/\fP and suffix (\fB\&.so\fP). They are completed automatically. .sp You can specify absolute path such as \fBregister /usr/lib/groonga/plugins/query_expanders/tsv.so\fP\&. .SS Return value .sp \fBregister\fP returns \fBtrue\fP as body on success such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, true] .ft P .fi .UNINDENT .UNINDENT .sp If \fBregister\fP fails, error details are in \fBHEADER\fP\&. .sp See \fB/reference/command/output_format\fP for \fBHEADER\fP\&. .SS \fBruby_eval\fP .SS Summary .sp \fBruby_eval\fP command evaluates Ruby script and returns the result. .SS Syntax .sp \fBruby_eval\fP has one required parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ruby_eval script .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp You can execute any scripts which mruby supports by calling \fBruby_eval\fP\&. .sp Here is an example that just calculate \fB1 + 2\fP as Ruby script. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register ruby/eval # [[0, 1337566253.89858, 0.000355720520019531], true] ruby_eval "1 + 2" # [[0, 1337566253.89858, 0.000355720520019531], {"value": 3}] .ft P .fi .UNINDENT .UNINDENT .sp Register \fBruby/eval\fP plugin to use \fBruby_eval\fP command in advance. .sp Note that \fBruby_eval\fP is implemented as an experimental plugin, and the specification may be changed in the future. .SS Parameters .sp This section describes all parameters. .SS \fBscript\fP .sp It specifies the Ruby script which you want to evaluate. .SS Return value .sp \fBruby_eval\fP returns the evaluated result with metadata such as exception information (Including metadata isn\(aqt implemented yet): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, {"value": EVALUATED_VALUE}] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBEVALUATED_VALUE\fP .INDENT 0.0 .INDENT 3.5 \fBEVALUATED_VALUE\fP is the evaludated value of \fBruby_script\fP\&. .sp \fBruby_eval\fP supports only a number for evaluated value for now. Supported types will be increased in the future. .UNINDENT .UNINDENT .SS See also .SS \fBruby_load\fP .SS Summary .sp \fBruby_load\fP command loads specified Ruby script. .SS Syntax .sp \fBruby_load\fP has one required parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ruby_load path .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp You can load any script file which mruby supports by calling \fBruby_load\fP\&. .sp Here is an example that just load \fBexpression.rb\fP as Ruby script. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register ruby/load # [[0, 1337566253.89858, 0.000355720520019531], true] ruby_load "expression.rb" # [[0, 1337566253.89858, 0.000355720520019531], {"value": null}] .ft P .fi .UNINDENT .UNINDENT .sp Register \fBruby/load\fP plugin to use \fBruby_load\fP command in advance. .sp Note that \fBruby_load\fP is implemented as an experimental plugin, and the specification may be changed in the future. .SS Parameters .sp This section describes all parameters. .SS \fBpath\fP .sp It specifies the Ruby script path which you want to load. .SS Return value .sp \fBruby_load\fP returns the loaded result with metadata such as exception information (Including metadata isn\(aqt implemented yet): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, {"value": LOADED_VALUE}] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBLOADED_VALUE\fP .INDENT 0.0 .INDENT 3.5 \fBLOADED_VALUE\fP is the loaded value of ruby script. .sp \fBruby_load\fP just return \fBnull\fP as \fBLOADED_VALUE\fP for now, it will be supported in the future. .UNINDENT .UNINDENT .SS See also .sp \fB/reference/commands/ruby_eval\fP .SS \fBselect\fP .SS Summary .sp \fBselect\fP searches records that are matched to specified conditions from a table and then outputs them. .sp \fBselect\fP is the most important command in groonga. You need to understand \fBselect\fP to use the full power of groonga. .SS Syntax .sp \fBselect\fP has many parameters. The required parameter is only \fBtable\fP and others are optional: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select table [match_columns=null] [query=null] [filter=null] [scorer=null] [sortby=null] [output_columns="_id, _key, *"] [offset=0] [limit=10] [drilldown=null] [drilldown_sortby=null] [drilldown_output_columns="_key, _nsubrecs"] [drilldown_offset=0] [drilldown_limit=10] [cache=yes] [match_escalation_threshold=0] [query_expansion=null] [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN|ALLOW_UPDATE|ALLOW_LEADING_NOT|NONE] [query_expander=null] [adjuster=null] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Let\(aqs learn about \fBselect\fP usage with examples. This section shows many popular usages. .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_HASH_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries n_likes COLUMN_SCALAR UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Entries [ {"_key": "The first post!", "content": "Welcome! This is my first post!", "n_likes": 5}, {"_key": "Groonga", "content": "I started to use groonga. It\(aqs very fast!", "n_likes": 10}, {"_key": "Mroonga", "content": "I also started to use mroonga. It\(aqs also very fast! Really fast!", "n_likes": 15}, {"_key": "Good\-bye Senna", "content": "I migrated all Senna system!", "n_likes": 3}, {"_key": "Good\-bye Tritonn", "content": "I also migrated all Tritonn system!", "n_likes": 3} ] # [[0, 1337566253.89858, 0.000355720520019531], 5] .ft P .fi .UNINDENT .UNINDENT .sp There is a table, \fBEntries\fP, for blog entries. An entry has title, content and the number of likes for the entry. Title is key of \fBEntries\fP\&. Content is value of \fBEntries.content\fP column. The number of likes is value of \fBEntries.n_likes\fP column. .sp \fBEntries._key\fP column and \fBEntries.content\fP column are indexed using \fBTokenBigram\fP tokenizer. So both \fBEntries._key\fP and \fBEntries.content\fP are fulltext search ready. .sp OK. The schema and data for examples are ready. .SS Simple usage .sp Here is the most simple usage with the above schema and data. It outputs all records in \fBEntries\fP table. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Why does the command output all records? There are two reasons. The first reason is that the command doesn\(aqt specify any search conditions. No search condition means all records are matched. The second reason is that the number of all records is 5. \fBselect\fP command outputs 10 records at a maximum by default. There are only 5 records. It is less than 10. So the command outputs all records. .SS Search conditions .sp Search conditions are specified by \fBquery\fP or \fBfilter\fP\&. You can also specify both \fBquery\fP and \fBfilter\fP\&. It means that selected records must be matched against both \fBquery\fP and \fBfilter\fP\&. .SS Search condition: \fBquery\fP .sp \fBquery\fP is designed for search box in Web page. Imagine a search box in google.com. You specify search conditions for \fBquery\fP as space separated keywords. For example, \fBsearch engine\fP means a matched record should contain two words, \fBsearch\fP and \fBengine\fP\&. .sp Normally, \fBquery\fP parameter is used for specifying fulltext search conditions. It can be used for non fulltext search conditions but \fBfilter\fP is used for the propose. .sp \fBquery\fP parameter is used with \fBmatch_columns\fP parameter when \fBquery\fP parameter is used for specifying fulltext search conditions. \fBmatch_columns\fP specifies which columnes and indexes are matched against \fBquery\fP\&. .sp Here is a simple \fBquery\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query fast # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command searches records that contain a word \fBfast\fP in \fBcontent\fP column value from \fBEntries\fP table. .sp \fBquery\fP has query syntax but its deatils aren\(aqt described here. See \fB/reference/grn_expr/query_syntax\fP for datails. .SS Search condition: \fBfilter\fP .sp \fBfilter\fP is designed for complex search conditions. You specify search conditions for \fBfilter\fP as ECMAScript like syntax. .sp Here is a simple \fBfilter\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent @ "fast" && _key == "Groonga"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command searches records that contain a word \fBfast\fP in \fBcontent\fP column value and has \fBGroonga\fP as \fB_key\fP from \fBEntries\fP table. There are three operators in the command, \fB@\fP, \fB&&\fP and \fB==\fP\&. \fB@\fP is fulltext search operator. \fB&&\fP and \fB==\fP are the same as ECMAScript. \fB&&\fP is logical AND operator and \fB==\fP is equality operator. .sp \fBfilter\fP has more operators and syntax like grouping by \fB(...)\fP its deatils aren\(aqt described here. See \fB/reference/grn_expr/script_syntax\fP for datails. .SS Paging .sp You can specify range of outputted records by \fBoffset\fP and \fBlimit\fP\&. Here is an example to output only the 2nd record. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-offset 1 \-\-limit 1 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fBoffset\fP is zero\-origin. \fB\-\-offset 1\fP means output range is started from the 2nd record. .sp \fBlimit\fP specifies the max number of output records. \fB\-\-limit 1\fP means the number of output records is 1 at a maximium. If no records are matched, \fBselect\fP command outputs no records. .SS The total number of records .sp You can use \fB\-\-limit 0\fP to retrieve the total number of recrods without any contents of records. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-limit 0 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fB\-\-limit 0\fP is also useful for retrieving only the number of matched records. .SS Parameters .sp This section describes all parameters. Parameters are categorized. .SS Required parameter .sp There is a required parameter, \fBtable\fP\&. .SS \fBtable\fP .sp It specifies a table to be searched. \fBtable\fP must be specified. .sp If nonexistent table is specified, an error is returned. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Nonexistent # [ # [ # \-22, # 1337566253.89858, # 0.000355720520019531, # "invalid table name: ", # [ # [ # "grn_select", # "proc.c", # 778 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Search related parameters .sp There are search related parameters. Typically, \fBmatch_columns\fP and \fBquery\fP parameters are used for implementing a search box. \fBfilter\fP parameters is used for implementing complex search feature. .sp If both \fBquery\fP and \fBfilter\fP are specified, selected records must be matched against both \fBquery\fP and \fBfilter\fP\&. If both \fBquery\fP and \fBfilter\fP aren\(aqt specified, all records are selected. .SS \fBmatch_columns\fP .sp It specifies the default target column for fulltext search by \fBquery\fP parameter value. A target column for fulltext search can be specified in \fBquery\fP parameter. The difference between \fBmatch_columns\fP and \fBquery\fP is whether weight is supported or not. \fBmatch_columns\fP supports weight but \fBquery\fP doesn\(aqt. .sp Weight is relative importance of target column. A higher weight target column gets more hit score rather than a lower weight target column when a record is matched by fulltext search. The default weight is 1. .sp Here is a simple \fBmatch_columns\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query fast \-\-output_columns \(aq_key, _score\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Groonga", # 1 # ], # [ # "Mroonga", # 2 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fB\-\-match_columns content\fP means the default target column for fulltext search is \fBcontent\fP column and its weight is 1. \fB\-\-output_columns \(aq_key, _score\(aq\fP means that the \fBselect\fP command outputs \fB_key\fP value and \fB_score\fP value for matched records. .sp Pay attention to \fB_score\fP value. \fB_score\fP value is the number of matched counts against \fBquery\fP parameter value. In the example, \fBquery\fP parameter value is \fBfast\fP\&. The fact that \fB_score\fP value is 1 means that \fBfast\fP appers in \fBcontent\fP column only once. The fact that \fB_score\fP value is 2 means that \fBfast\fP appears in \fBcontent\fP column twice. .sp To specify weight, \fBcolumn * weight\fP syntax is used. Here is a weight usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns \(aqcontent * 2\(aq \-\-query fast \-\-output_columns \(aq_key, _score\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Groonga", # 2 # ], # [ # "Mroonga", # 4 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fB\-\-match_columns \(aqcontent * 2\(aq\fP means the default target column for fulltext search is \fBcontent\fP column and its weight is 2. .sp Pay attention to \fB_score\fP value. \fB_score\fP value is doubled because weight is 2. .sp You can specify one or more columns as the default target columns for fulltext search. If one or more columns are specified, fulltext search is done for all columns and scores are accumulated. If one of the columns is matched against \fBquery\fP parameter value, the record is treated as matched. .sp To specify one or more columns, \fBcolumn1 * weight1 || column2 * weight2 || ...\fP syntax is used. \fB* weight\fP can be omitted. If it is omitted, 1 is used for weight. Here is a one or more columns usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns \(aq_key * 10 || content\(aq \-\-query groonga \-\-output_columns \(aq_key, _score\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Groonga", # 11 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fB\-\-match_columns \(aq_key * 10 || content\(aq\fP means the default target columns for fulltext search are \fB_key\fP and \fBcontent\fP columns and \fB_key\fP column\(aqs weight is 10 and \fBcontent\fP column\(aqs weight is 1. This weight allocation means \fB_key\fP column value is more important rather than \fBcontent\fP column value. In this example, title of blog entry is more important rather thatn content of blog entry. .SS \fBquery\fP .sp It specifies the query text. Normally, it is used for fulltext search with \fBmatch_columns\fP parameter. \fBquery\fP parameter is designed for a fulltext search form in a Web page. A query text should be formatted in \fB/reference/grn_expr/query_syntax\fP\&. The syntax is similar to common search form like Google\(aqs search form. For example, \fBword1 word2\fP means that groonga searches records that contain both \fBword1\fP and \fBword2\fP\&. \fBword1 OR word2\fP means that groogna searches records that contain either \fBword1\fP or \fBword2\fP\&. .sp Here is a simple logical and search example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query "fast groonga" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command searches records that contain two words \fBfast\fP and \fBgroonga\fP in \fBcontent\fP column value from \fBEntries\fP table. .sp Here is a simple logical or search example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query "groonga OR mroonga" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command searches records that contain one of two words \fBgroonga\fP or \fBmroonga\fP in \fBcontent\fP column value from \fBEntries\fP table. .sp See \fB/reference/grn_expr/query_syntax\fP for other syntax. .sp It can be used for not only fulltext search but also other conditions. For example, \fBcolumn:value\fP means the value of \fBcolumn\fP column is equal to \fBvalue\fP\&. \fBcolumn:=10"]} ] # [[0, 1337566253.89858, 0.000355720520019531], 1] select Entries \-\-match_columns content \-\-query "popular" \-\-query_expander Thesaurus.synonym # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBload\fP command registers a new synonym \fB"popular"\fP\&. It is substituted with \fB((popular) OR (n_likes:>=10))\fP\&. The substituted query means that "popular" is containing the word "popular" or 10 or more liked entries. .sp The \fBselect\fP command outputs records that \fBn_likes\fP column value is equal to or more than \fB10\fP from \fBEntries\fP table. .SS Output related parameters .SS \fBoutput_columns\fP .sp It specifies output columns separated by \fB,\fP\&. .sp Here is a simple \fBoutput_columns\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \(aq_id, _key\(aq \-\-limit 1 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 1, # "The first post!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command just outputs \fB_id\fP and \fB_key\fP column values. .sp \fB*\fP is a special value. It means that all columns that are not \fB/reference/columns/pseudo\fP\&. .sp Here is a \fB*\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \(aq_key, *\(aq \-\-limit 1 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command outputs \fB_key\fP pseudo column, \fBcontent\fP column and \fBn_likes\fP column values but doesn\(aqt output \fB_id\fP pseudo column value. .sp The default value is \fB_id, _key, *\fP\&. It means that all column values except \fB_score\fP are outputted. .SS \fBsortby\fP .sp It specifies sort keys separated by \fB,\fP\&. Each sort key is column name. .sp Here is a simple \fBsortby\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-sortby \(aqn_likes, _id\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command sorts by \fBn_likes\fP column value in ascending order. For records that has the same \fBn_likes\fP are sorted by \fB_id\fP in ascending order. \fB"Good\-bye Senna"\fP and \fB"Good\-bye Tritonn"\fP are the case. .sp If you want to sort in descending order, add \fB\-\fP before column name. .sp Here is a descending order \fBsortby\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-sortby \(aq\-n_likes, _id\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command sorts by \fBn_likes\fP column value in descending order. But ascending order is used for sorting by \fB_id\fP\&. .sp You can use \fB_score\fP pseudo column in \fBsortby\fP if you use \fBquery\fP or \fBfilter\fP parameter. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query fast \-\-sortby \-_score \-\-output_columns \(aq_key, _score\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Mroonga", # 2 # ], # [ # "Groonga", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command sorts matched records by hit score in descending order and outputs record key and hit score. .sp If you use \fB_score\fP without \fBquery\fP nor \fBfilter\fP parameters, it\(aqs just ignored but get a warning in log file. .SS \fBoffset\fP .sp It specifies offset to determine output records range. Offset is zero\-origin. \fB\-\-offset 1\fP means output range is started from the 2nd record. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-sortby _id \-\-offset 3 \-\-output_columns _key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "Good\-bye Senna" # ], # [ # "Good\-bye Tritonn" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command outputs from the 4th record. .sp You can specify negative value. It means that \fBthe number of matched records + offset\fP\&. If you have 3 matched records and specify \fB\-\-offset \-2\fP, you get records from the 1st (\fB3 + \-2 = 1\fP) record to the 3rd record. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-sortby _id \-\-offset \-2 \-\-output_columns _key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "Good\-bye Senna" # ], # [ # "Good\-bye Tritonn" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command outputs from the 4th record because the total number of records is \fB5\fP\&. .sp The default value is \fB0\fP\&. .SS \fBlimit\fP .sp It specifies the max number of output records. If the number of matched records is less than \fBlimit\fP, all records are outputted. .sp Here is a simple \fBlimit\fP usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-sortby _id \-\-offset 2 \-\-limit 3 \-\-output_columns _key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "Mroonga" # ], # [ # "Good\-bye Senna" # ], # [ # "Good\-bye Tritonn" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command outputs the 3rd, the 4th and the 5th records. .sp You can specify negative value. It means that \fBthe number of matched records + limit + 1\fP\&. For example, \fB\-\-limit \-1\fP outputs all records. It\(aqs very useful value to show all records. .sp Here is a simple negative \fBlimit\fP value usage example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-limit \-1 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command outputs all records. .sp The default value is \fB10\fP\&. .SS \fBscorer\fP .sp TODO: write in English and add example. .sp 検索条件にマッチする全てのレコードに対して適用するgrn_exprをscript形式で指定します。 .sp scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。 .SS Facet related parameters .SS \fBdrilldown\fP .sp TODO: write in English and add example. .sp グループ化のキーとなるカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。検索条件にマッチした各レコードを出力したのちに、drilldownに指定されたカラムの値が同一であるレコードをとりまとめて、それぞれについて結果レコードを出力します。 .SS \fBdrilldown_sortby\fP .sp TODO: write in English and add example. .sp drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、ソートキーとなるカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。sortbyパラメータと同様に昇降順を指定できます。 .SS \fBdrilldown_output_columns\fP .sp TODO: write in English and add example. .sp drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力するカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。 .SS \fBdrilldown_offset\fP .sp TODO: write in English and add example. .sp drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。drilldown_offsetに負の値を指定した場合は、ヒットした件数 + drilldown_offsetによって算出される値が指定されたものとみなされます。 .SS \fBdrilldown_limit\fP .sp TODO: write in English and add example. .sp drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、drilldown_offset + drilldown_limit がヒットした件数を超えない範囲でレコードが出力されます。drilldown_limitに負の値を指定した場合は、ヒットした件数 + drilldown_limit + 1 によって算出される値が指定されたものとみなされます。 .SS Cache related parameter .SS \fBcache\fP .sp TODO: write in English and add example. .sp クエリキャッシュに関する動作を設定します。 .sp \fBno\fP .INDENT 0.0 .INDENT 3.5 検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。 .UNINDENT .UNINDENT .SS Score related parameters .sp There is a score related parameter, \fBadjuster\fP\&. .SS \fBadjuster\fP .sp It specifies one or more score adjust expressions. You need to use \fBadjuster\fP with \fBquery\fP or \fBfilter\fP\&. \fBadjuster\fP doesn\(aqt work with not searched request. .sp You can increase score of specific records by \fBadjuster\fP\&. You can use \fBadjuster\fP to set high score for important records. .sp For example, you can use \fBadjuster\fP to increase score of records that have \fBgroonga\fP tag. .sp Here is the syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-adjuster "SCORE_ADJUST_EXPRESSION1 + SCORE_ADJUST_EXPRESSION2 + ..." .ft P .fi .UNINDENT .UNINDENT .sp Here is the \fBSCORE_ADJUST_EXPRESSION\fP syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C COLUMN @ "KEYWORD" * FACTOR .ft P .fi .UNINDENT .UNINDENT .sp Note the following: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBCOLUMN\fP must be indexed. .IP \(bu 2 \fB"KEYWORD"\fP must be a string. .IP \(bu 2 \fBFACTOR\fP must be a positive integer. .UNINDENT .UNINDENT .UNINDENT .sp Here is a sample \fBadjuster\fP usage example that uses just one \fBSCORE_ADJUST_EXPRESSION\fP: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \e \-\-filter true \e \-\-adjuster \(aqcontent @ "groonga" * 5\(aq \e \-\-output_columns _key,content,_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "_score", # "Int32" # ] # ], # [ # "The first post!", # "Welcome! This is my first post!", # 1 # ], # [ # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 6 # ], # [ # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 1 # ], # [ # "Good\-bye Senna", # "I migrated all Senna system!", # 1 # ], # [ # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBselect\fP command matches all records. Then it applies \fBadjuster\fP\&. The adjuster increases score of records that have \fB"groonga"\fP in \fBEntries.content\fP column by 5. There is only one record that has \fB"groonga"\fP in \fBEntries.content\fP column. So the record that its key is \fB"Groonga"\fP has score 6 (\fB= 1 + 5\fP). .sp You can omit \fBFACTOR\fP\&. If you omit \fBFACTOR\fP, it is treated as 1. .sp Here is a sample \fBadjuster\fP usage example that omits \fBFACTOR\fP: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \e \-\-filter true \e \-\-adjuster \(aqcontent @ "groonga"\(aq \e \-\-output_columns _key,content,_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "_score", # "Int32" # ] # ], # [ # "The first post!", # "Welcome! This is my first post!", # 1 # ], # [ # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 2 # ], # [ # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 1 # ], # [ # "Good\-bye Senna", # "I migrated all Senna system!", # 1 # ], # [ # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBadjuster\fP in the \fBselect\fP command doesn\(aqt have \fBFACTOR\fP\&. So the factor is treated as 1. There is only one record that has \fB"groonga"\fP in \fBEntries.content\fP column. So the record that its key is \fB"Groonga"\fP has score 2 (\fB= 1 + 1\fP). .sp Here is a sample \fBadjuster\fP usage example that uses multiple \fBSCORE_ADJUST_EXPRESSION\fP: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \e \-\-filter true \e \-\-adjuster \(aqcontent @ "groonga" * 5 + content @ "started" * 3\(aq \e \-\-output_columns _key,content,_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "_score", # "Int32" # ] # ], # [ # "The first post!", # "Welcome! This is my first post!", # 1 # ], # [ # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 9 # ], # [ # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 4 # ], # [ # "Good\-bye Senna", # "I migrated all Senna system!", # 1 # ], # [ # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The \fBadjuster\fP in the \fBselect\fP command has two \fBSCORE_ADJUST_EXPRESSION\fP s. The final increased score is sum of scores of these \fBSCORE_ADJUST_EXPRESSION\fP s. All \fBSCORE_ADJUST_EXPRESSION\fP s in the \fBselect\fP command are applied to a record that its key is \fB"Groonga"\fP\&. So the final increased score of the record is sum of scores of all \fBSCORE_ADJUST_EXPRESSION\fP s. .sp The first \fBSCORE_ADJUST_EXPRESSION\fP is \fBcontent @ "groonga" * 5\fP\&. It increases score by 5. .sp The second \fBSCORE_ADJUST_EXPRESSION\fP is \fBcontent @ "started" * 3\fP\&. It increases score by 3. .sp The final increased score is 9 (\fB= 1 + 5 + 3\fP). .sp A \fBSCORE_ADJUST_EXPRESSION\fP has a factor for \fB"KEYWORD"\fP\&. This means that increased scores of all records that has \fB"KEYWORD"\fP are the same value. You can change increase score for each record that has the same \fB"KEYWORD"\fP\&. It is useful to tune search score. See \fIweight\-vector\-column\fP for details. .SS 返値 .sp TODO: write in English and add example. .sp 以下のようなjson形式で値が返却されます。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [[リターンコード, 処理開始時間, 処理時間], [検索結果, ドリルダウン結果]] .ft P .fi .UNINDENT .UNINDENT .sp \fBリターンコード\fP .INDENT 0.0 .INDENT 3.5 grn_rcに対応する数値が返されます。0(GRN_SUCCESS)以外の場合は、続いてエラー内容を示す 文字列が返されます。 .UNINDENT .UNINDENT .sp \fB処理開始時間\fP .INDENT 0.0 .INDENT 3.5 処理を開始した時間について、1970年1月1日0時0分0秒を起点とした秒数を小数で返します。 .UNINDENT .UNINDENT .sp \fB処理時間\fP .INDENT 0.0 .INDENT 3.5 処理にかかった秒数を返します。 .UNINDENT .UNINDENT .sp \fB検索結果\fP .INDENT 0.0 .INDENT 3.5 drilldown条件が実行される前の検索結果が以下のように出力されます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [[ヒット数], [[カラム名1,カラム型1],..], 検索結果1,..] .ft P .fi .UNINDENT .UNINDENT .sp \fBヒット数\fP .INDENT 0.0 .INDENT 3.5 検索条件にヒットしたレコードの数が出力されます。 \fB\-\-limit\fP オプションで出力件数を制限した場合は出力するレコード数と一致しません。 \fBヒット数\fP は \fB\-\-limit\fP オプションに関係なく常にヒットしたレコードの数になります。 .UNINDENT .UNINDENT .sp \fBカラム名n\fP .INDENT 0.0 .INDENT 3.5 output_columnsに指定された条件に従って、対象となるカラム名が出力されます。 .UNINDENT .UNINDENT .sp \fBカラム型n\fP .INDENT 0.0 .INDENT 3.5 output_columnsに指定された条件に従って、対象となるカラム型が出力されます。 .UNINDENT .UNINDENT .sp \fB検索結果n\fP .INDENT 0.0 .INDENT 3.5 output_columns, offset, limitによって指定された条件に従って各レコードの値が出力されます。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBdrilldown結果\fP .INDENT 0.0 .INDENT 3.5 drilldown処理の結果が以下のように出力されます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [[[件数], [[カラム名1,カラム型1],..], 検索結果1,..],..] .ft P .fi .UNINDENT .UNINDENT .sp \fB件数\fP .INDENT 0.0 .INDENT 3.5 drilldownに指定されたカラムの値の異なり数が出力されます。 .UNINDENT .UNINDENT .sp \fBカラム名n\fP .INDENT 0.0 .INDENT 3.5 drilldown_output_columnsに指定された条件に従って、対象となるカラム名が出力されます。 .UNINDENT .UNINDENT .sp \fBカラム型n\fP .INDENT 0.0 .INDENT 3.5 drilldown_output_columnsに指定された条件に従って、対象となるカラム型が出力されます。 .UNINDENT .UNINDENT .sp \fBドリルダウン結果n\fP .INDENT 0.0 .INDENT 3.5 drilldown_output_columns, drilldown_offset, drilldown_limitによって指定された条件に従って各レコードの値が出力されます。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB/reference/grn_expr/query_syntax\fP .IP \(bu 2 \fB/reference/grn_expr/script_syntax\fP .UNINDENT .UNINDENT .UNINDENT .SS \fBshutdown\fP .SS Summary .sp shutdown \- サーバプロセスの停止 .sp Groonga組込コマンドの一つであるshutdownについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入 力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp shutdownは、接続しているgroongaサーバプロセスを停止します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C shutdown .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C shutdown .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp ありません。 .SS Return value .sp ありません。 .SS \fBstatus\fP .SS Summary .sp status \- groongaプロセスの状態表示 .sp Groonga組込コマンドの一つであるstatusについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp statusコマンドは、groongaプロセスの状態を表示します。主にgroongaサーバプロセスに対して使用することを想定しています。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C status .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C status # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "uptime": 7, # "max_command_version": 2, # "n_queries": 39, # "cache_hit_rate": 0.0, # "version": "4.0.1", # "alloc_count": 309, # "command_version": 1, # "starttime": 1395806014, # "default_command_version": 1 # } # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp ありません。 .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 下記の項目がハッシュ形式で出力されます。 .ft P .fi .UNINDENT .UNINDENT .sp \fBalloc_count\fP .INDENT 0.0 .INDENT 3.5 groongaプロセスの内部でアロケートされ、まだ解放されてないメモリブロックの数を示します。Groongaをbuildする際に、configureオプションで \-\-enable\-exact\-alloc\-countが指定されていたならば、正確な値を返します。それ以外の場合は不正確な値を返す場合があります。 .UNINDENT .UNINDENT .sp \fBstarttime\fP .INDENT 0.0 .INDENT 3.5 groongaプロセスが起動した時刻のtvsec値を返します。 .UNINDENT .UNINDENT .sp \fBuptime\fP .INDENT 0.0 .INDENT 3.5 groongaプロセスが起動してから経過した秒数を返します。 .UNINDENT .UNINDENT .SS \fBsuggest\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The suggest feature specification isn\(aqt stable. The specification may be changed. .UNINDENT .UNINDENT .SS Summary .sp suggest \- returns completion, correction and/or suggestion for a query. .sp The suggest command returns completion, correction and/or suggestion for a specified query. .sp See \fB/suggest/introduction\fP about completion, correction and suggestion. .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest types table column query [sortby [output_columns [offset [limit [frequency_threshold [conditional_probability_threshold [prefix_search]]]]]]] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are learned data for completion. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "1", "time": 1312950803.86057, "item": "e"}, {"sequence": "1", "time": 1312950803.96857, "item": "en"}, {"sequence": "1", "time": 1312950804.26057, "item": "eng"}, {"sequence": "1", "time": 1312950804.56057, "item": "engi"}, {"sequence": "1", "time": 1312950804.76057, "item": "engin"}, {"sequence": "1", "time": 1312950805.86057, "item": "engine", "type": "submit"} ] # [[0, 1337566253.89858, 0.000355720520019531], 6] .ft P .fi .UNINDENT .UNINDENT .sp Here are learned data for correction. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "2", "time": 1312950803.86057, "item": "s"}, {"sequence": "2", "time": 1312950803.96857, "item": "sa"}, {"sequence": "2", "time": 1312950804.26057, "item": "sae"}, {"sequence": "2", "time": 1312950804.56057, "item": "saer"}, {"sequence": "2", "time": 1312950804.76057, "item": "saerc"}, {"sequence": "2", "time": 1312950805.76057, "item": "saerch", "type": "submit"}, {"sequence": "2", "time": 1312950809.76057, "item": "serch"}, {"sequence": "2", "time": 1312950810.86057, "item": "search", "type": "submit"} ] # [[0, 1337566253.89858, 0.000355720520019531], 8] .ft P .fi .UNINDENT .UNINDENT .sp Here are learned data for suggestion. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table event_query \-\-each \(aqsuggest_preparer(_id, type, item, sequence, time, pair_query)\(aq [ {"sequence": "3", "time": 1312950803.86057, "item": "search engine", "type": "submit"}, {"sequence": "3", "time": 1312950808.86057, "item": "web search realtime", "type": "submit"} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] .ft P .fi .UNINDENT .UNINDENT .sp Here is a completion example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query en # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "complete": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "engine", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is a correction example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types correct \-\-frequency_threshold 1 \-\-query saerch # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "correct": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is a suggestion example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types suggest \-\-frequency_threshold 1 \-\-query search # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "suggest": [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search engine", # 1 # ], # [ # "web search realtime", # 1 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is a mixed example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C suggest \-\-table item_query \-\-column kana \-\-types complete|correct|suggest \-\-frequency_threshold 1 \-\-query search # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # { # "suggest": [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search engine", # 1 # ], # [ # "web search realtime", # 1 # ] # ], # "complete": [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search", # 2 # ], # [ # "search engine", # 2 # ] # ], # "correct": [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "search", # 2 # ] # ] # } # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .INDENT 0.0 .TP .B \fBtypes\fP It specifies what types are returned by the suggest command. .sp Here are available types: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBcomplete\fP The suggest command does completion. .TP .B \fBcorrect\fP The suggest command does correction. .TP .B \fBsuggest\fP The suggest command does suggestion. .UNINDENT .UNINDENT .UNINDENT .sp You can specify one or more types separated by \fB|\fP\&. Here are examples: .INDENT 7.0 .INDENT 3.5 It returns correction: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C correct .ft P .fi .UNINDENT .UNINDENT .sp It returns correction and suggestion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C correct|suggest .ft P .fi .UNINDENT .UNINDENT .sp It returns complete, correction and suggestion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C complete|correct|suggest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B \fBtable\fP It specifies table name that has \fBitem_${DATA_SET_NAME}\fP format. For example, \fBitem_query\fP is a table name if you created dataset by the following command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C groonga\-suggest\-create\-dataset /tmp/db\-path query .ft P .fi .UNINDENT .UNINDENT .TP .B \fBcolumn\fP It specifies a column name that has furigana in Katakana in \fBtable\fP table. .TP .B \fBquery\fP It specifies query for completion, correction and/or suggestion. .TP .B \fBsortby\fP It specifies sort key. .INDENT 7.0 .TP .B Default: \fB\-_score\fP .UNINDENT .TP .B \fBoutput_columns\fP It specifies output columns. .INDENT 7.0 .TP .B Default: \fB_key,_score\fP .UNINDENT .TP .B \fBoffset\fP It specifies returned records offset. .INDENT 7.0 .TP .B Default: \fB0\fP .UNINDENT .TP .B \fBlimit\fP It specifies number of returned records. .INDENT 7.0 .TP .B Default: \fB10\fP .UNINDENT .TP .B \fBfrequency_threshold\fP It specifies threshold for item frequency. Returned records must have \fB_score\fP that is greater than or equal to \fBfrequency_threshold\fP\&. .INDENT 7.0 .TP .B Default: \fB100\fP .UNINDENT .UNINDENT .sp \fBconditional_probability_threshold\fP .INDENT 0.0 .INDENT 3.5 It specifies threshold for conditional probability. Conditional probability is used for learned data. It is probability of query submission when \fBquery\fP is occurred. Returned records must have conditional probability that is greater than or equal to \fBconditional_probability_threshold\fP\&. .INDENT 0.0 .TP .B Default: \fB0.2\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBprefix_search\fP It specifies whether optional prefix search is used or not in completion. .sp Here are available values: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fByes\fP Prefix search is always used. .TP .B \fBno\fP Prefix search is never used. .TP .B \fBauto\fP Prefix search is used only when other search can\(aqt find any records. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Default: \fBauto\fP .UNINDENT .TP .B \fBsimilar_search\fP It specifies whether optional similar search is used or not in correction. .sp Here are available values: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fByes\fP Similar search is always used. .TP .B \fBno\fP Similar search is never used. .TP .B \fBauto\fP Similar search is used only when other search can\(aqt find any records. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Default: \fBauto\fP .UNINDENT .UNINDENT .SS Return value .sp Here is a returned JSON format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"type1": [["candidate1", score of candidate1], ["candidate2", score of candidate2], ...], "type2": [["candidate1", score of candidate1], ["candidate2", score of candidate2], ...], ...} .ft P .fi .UNINDENT .UNINDENT .sp \fBtype\fP .INDENT 0.0 .INDENT 3.5 A type specified by \fBtypes\fP\&. .UNINDENT .UNINDENT .sp \fBcandidate\fP .INDENT 0.0 .INDENT 3.5 A candidate for completion, correction or suggestion. .UNINDENT .UNINDENT .sp \fBscore of candidate\fP .INDENT 0.0 .INDENT 3.5 A score of corresponding \fBcandidate\fP\&. It means that higher score candidate is more likely candidate for completion, correction or suggestion. Returned candidates are sorted by \fBscore of candidate\fP descending by default. .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/suggest\fP .IP \(bu 2 \fB/reference/executables/groonga\-suggest\-create\-dataset\fP .UNINDENT .SS \fBtable_create\fP .SS Summary .sp \fBtable_create\fP creates a new table in the current database. You need to create one or more tables to store and search data. .SS Syntax .sp \fBtable_create\fP has many parameters. The required parameter is only \fBname\fP and otehrs are optional: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create name [flags=TABLE_HASH_KEY] [key_type=null] [value_type=null] [default_tokenizer=null] [normalizer=null] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp \fBtable_create\fP command creates a new persistent table. See \fB/reference/tables\fP for table details. .SS Create data store table .sp You can use all table types for data store table. See \fB/reference/tables\fP for all table types. .sp Table type is specified as \fBTABLE_${TYPE}\fP to \fBflags\fP parameter. .sp Here is an example to create \fBTABLE_NO_KEY\fP table: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Logs TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fBtable_create\fP command creates a table that is named \fBLogs\fP and is \fBTABLE_NO_KEY\fP type. .sp If your records aren\(aqt searched by key, \fBTABLE_NO_KEY\fP type table is suitable. Because \fBTABLE_NO_KEY\fP doesn\(aqt support key but it is fast and small table. Storing logs into Groonga database is the case. .sp If your records are searched by key or referenced by one or more columns, \fBTABLE_NO_KEY\fP type isn\(aqt suitable. Lexicon for fulltext search is the case. .SS Create lexicon table .sp You can use all table types except \fBTABLE_NO_KEY\fP for lexicon table. Lexicon table needs key support but \fBTABLE_NO_KEY\fP doesn\(aqt support key. .sp Here is an example to create \fBTABLE_PAT_KEY\fP table: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Lexicon TABLE_PAT_KEY ShortText \-\-default_tokenizer TokenBigram \-\-normalizer NormalizerAuto # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fBtable_create\fP command creates the following table: .INDENT 0.0 .IP \(bu 2 The table is named \fBLexicon\fP\&. .IP \(bu 2 The table is \fBTABLE_PAT_KEY\fP type table. .IP \(bu 2 The table\(aqs key is \fBShortText\fP type. .IP \(bu 2 The table uses \fBTokenBigram\fP tokenizer to extract tokens from a normalized text. .IP \(bu 2 The table uses \fBNormalizerAuto\fP normalizer to normalize a text. .UNINDENT .sp \fBTABLE_PAT_KEY\fP is suitable table type for lexicon table. Lexicon table is used for fulltext search. .sp In fulltext search, predictive search may be used for fuzzy search. Predictive search is supported by \fBTABLE_PAT_KEY\fP and \fBTABLE_DAT_KEY\fP\&. .sp Lexicon table has many keys because a fulltext target text has many tokens. Table that has many keys should consider table size because large table requires large memory. Requiring large memory causes disk I/O. It blocks fast search. So table size is important for a table that has many keys. \fBTABLE_PAT_KEY\fP is less table size than \fBTABLE_DAT_KEY\fP\&. .sp Because of the above reasons, \fBTABLE_PAT_KEY\fP is suitable table type for lexicon table. .SS Create tag index table .sp You can use all table types except \fBTABLE_NO_KEY\fP for tag index table. Tag index table needs key support but \fBTABLE_NO_KEY\fP doesn\(aqt support key. .sp Here is an example to create \fBTABLE_HASH_KEY\fP table: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Ages TABLE_DAT_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fBtable_create\fP command creates a table that is named \fBTags\fP, is \fBTABLE_HASH_KEY\fP type and has \fBShortText\fP type key. .sp \fBTABLE_HASH_KEY\fP or \fBTABLE_DAT_KEY\fP are suitable table types for tag index table. .sp If you need only exact match tag search feature, \fBTABLE_HASH_KEY\fP is suitable. It is the common case. .sp If you also need predictive tag search feature (for example, searching \fB"groonga"\fP by \fB"gr"\fP keyword.), \fBTABLE_DAT_KEY\fP is suitable. \fBTABLE_DAT_KEY\fP is large table size but it is not important because the number of tags will not be large. .SS Create range index table .sp You can use \fBTABLE_PAT_KEY\fP and \fBTABLE_DAT_KEY\fP table types for range index table. Range index table needs range search support but \fBTABLE_NO_KEY\fP and \fBTABLE_HASH_KEY\fP don\(aqt support it. .sp Here is an example to create \fBTABLE_DAT_KEY\fP table: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Ages TABLE_DAT_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp The \fBtable_create\fP command creates a table that is named \fBAges\fP, is \fBTABLE_DAT_KEY\fP type and has \fBUInt32\fP type key. .sp \fBTABLE_PAT_KEY\fP and \fBTABLE_DAT_KEY\fP are suitable table types for range index table. .sp If you don\(aqt have many indexed items, \fBTABLE_DAT_KEY\fP is suitable. Index for age is the case in the above example. Index for age will have only 0\-100 items because human doesn\(aqt live so long. .sp If you have many indexed items, \fBTABLE_PAT_KEY\fP is suitable. Because \fBTABLE_PAT_KEY\fP is smaller than \fBTABLE_DAT_KEY\fP\&. .SS Parameters .sp This section describes all parameters. .SS \fBname\fP .sp It specifies a table name to be created. \fBname\fP must be specified. .sp Here are available characters: .INDENT 0.0 .IP \(bu 2 \fB0\fP .. \fB9\fP (digit) .IP \(bu 2 \fBa\fP .. \fBz\fP (alphabet, lower case) .IP \(bu 2 \fBA\fP .. \fBZ\fP (alphabet, upper case) .IP \(bu 2 \fB#\fP (hash) .IP \(bu 2 \fB@\fP (at mark) .IP \(bu 2 \fB\-\fP (hyphen) .IP \(bu 2 \fB_\fP (underscore) (NOTE: Underscore can\(aqt be used as the first character.) .UNINDENT .sp You need to create a name with one or more the above chracters. Note that you cannot use \fB_\fP as the first character such as \fB_name\fP\&. .SS \fBflags\fP .sp It specifies a table type and table customize options. .sp Here are available flags: .TS center; |l|l|. _ T{ flags T} T{ description T} _ T{ \fBTABLE_NO_KEY\fP T} T{ Array table. T} _ T{ \fBTABLE_HASH_KEY\fP T} T{ Hash table. T} _ T{ \fBTABLE_PAT_KEY\fP T} T{ Patricia trie. T} _ T{ \fBTABLE_DAT_KEY\fP T} T{ Double Array trie. T} _ T{ \fBKEY_WITH_SIS\fP T} T{ Enable Semi Infinite String. Require \fBTABLE_PAT_KEY\fP\&. T} _ .TE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since Groonga 2.1.0 \fBKEY_NORMALIZE\fP flag is deprecated. Use \fBnormalizer\fP option with \fBNormalizerAuto\fP instead. .UNINDENT .UNINDENT .sp You must specify one of \fBTABLE_${TYPE}\fP flags. You cannot specify two or more \fBTABLE_${TYPE}\fP flags. For example, \fBTABLE_NO_KEY|TABLE_HASH_KEY\fP is invalid. .sp You can combine flags with \fB|\fP (vertical bar) such as \fBTABLE_PAT_KEY|KEY_WITH_SIS\fP\&. .sp See \fB/reference/tables\fP for difference between table types. .sp The default flags are \fBTABLE_HASH_KEY\fP\&. .SS \fBkey_type\fP .sp It specifies key type. .sp If you specify \fBTABLE_HASH_KEY\fP, \fBTABLE_PAT_KEY\fP or \fBTABLE_DAT_KEY\fP as \fBflags\fP parameter, you need to specify \fBkey_type\fP option. .sp See \fB/reference/types\fP for all types. .sp The default value is none. .SS \fBvalue_type\fP .sp It specifies value type. .sp You can use value when you specify \fBTABLE_NO_KEY\fP, \fBTABLE_HASH_KEY\fP or \fBTABLE_PAT_KEY\fP as \fBflags\fP parameter. Value type must be a fixed size type. For example, \fBUInt32\fP can be used but \fBShortText\fP cannot be used. Use columns instead of value. .sp The default value is none. .SS \fBdefault_tokenizer\fP .sp It specifies the default tokenizer that is used on searching and data loading. .sp You cannot use \fBdefault_tokenizer\fP with \fBTABLE_NO_KEY\fP because \fBTABLE_NO_KEY\fP cannot be used for index. .sp You must specify \fBdefault_tokenizer\fP for a table that is used for fulltext search index. .sp See \fB/reference/tokenizers\fP for all tokenizers .sp The default value is none. .SS \fBnormalizer\fP .sp It specifies a normalizer that is used to normalize key. .sp You cannot use \fBnormalizer\fP with \fBTABLE_NO_KEY\fP because \fBTABLE_NO_KEY\fP doesn\(aqt support key. .sp See \fB/reference/normalizers\fP for all normalizsers. .sp The default value is none. .SS Return value .sp \fBtable_create\fP returns \fBtrue\fP as body on success such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, true] .ft P .fi .UNINDENT .UNINDENT .sp If \fBtable_create\fP fails, error details are in \fBHEADER\fP\&. .sp See \fB/reference/command/output_format\fP for \fBHEADER\fP\&. .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/tables\fP .IP \(bu 2 \fB/reference/commands/column_create\fP .IP \(bu 2 \fB/reference/tokenizers\fP .IP \(bu 2 \fB/reference/normalizers\fP .IP \(bu 2 \fB/reference/command/output_format\fP .UNINDENT .SS \fBtable_list\fP .SS Summary .sp table_list \- DBに定義されているテーブルをリスト表示 .sp Groonga組込コマンドの一つであるtable_listについて説明します。組込コマンドは、groonga実行ファイルの引数、標準 入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp table_listは、DBに定義されているテーブルのリストを表示します。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_list .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_list # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # "id", # "UInt32" # ], # [ # "name", # "ShortText" # ], # [ # "path", # "ShortText" # ], # [ # "flags", # "ShortText" # ], # [ # "domain", # "ShortText" # ], # [ # "range", # "ShortText" # ], # [ # "default_tokenizer", # "ShortText" # ], # [ # "normalizer", # "ShortText" # ] # ], # [ # 259, # "Ages", # "/tmp/groonga\-databases/commands_table_create.0000103", # "TABLE_DAT_KEY|PERSISTENT", # "UInt32", # null, # null, # null # ], # [ # 257, # "Lexicon", # "/tmp/groonga\-databases/commands_table_create.0000101", # "TABLE_PAT_KEY|PERSISTENT", # "ShortText", # null, # "TokenBigram", # "NormalizerAuto" # ], # [ # 256, # "Logs", # "/tmp/groonga\-databases/commands_table_create.0000100", # "TABLE_NO_KEY|PERSISTENT", # null, # null, # null, # null # ], # [ # 258, # "Tags", # "/tmp/groonga\-databases/commands_table_create.0000102", # "TABLE_HASH_KEY|PERSISTENT", # "ShortText", # null, # null, # null # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp ありません。 .SS Return value .sp テーブル名一覧が以下の形式で返却されます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [[[テーブル情報名1,テーブル情報型1],...], テーブル情報1,...] .ft P .fi .UNINDENT .UNINDENT .sp \fBテーブル情報名n\fP .INDENT 0.0 .INDENT 3.5 \fBテーブル情報n\fP には複数の情報が含まれますが、そこに入る情報がどんな内容かを示す名前を出力します。 情報名は以下の通りです。 .sp \fBid\fP .INDENT 0.0 .INDENT 3.5 テーブルオブジェクトに割り当てられたID .UNINDENT .UNINDENT .sp \fBname\fP .INDENT 0.0 .INDENT 3.5 テーブル名 .UNINDENT .UNINDENT .sp \fBpath\fP .INDENT 0.0 .INDENT 3.5 テーブルのレコードを格納するファイル名 .UNINDENT .UNINDENT .sp \fBflags\fP .INDENT 0.0 .INDENT 3.5 テーブルのflags属性 .UNINDENT .UNINDENT .sp \fBdomain\fP .INDENT 0.0 .INDENT 3.5 主キー値の属する型 .UNINDENT .UNINDENT .sp \fBrange\fP .INDENT 0.0 .INDENT 3.5 valueが属する型 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBテーブル情報型n\fP .INDENT 0.0 .INDENT 3.5 テーブル情報の型を出力します。 .UNINDENT .UNINDENT .sp \fBテーブル情報n\fP .INDENT 0.0 .INDENT 3.5 \fBテーブル情報名n\fP で示された情報の配列を出力します。 情報の順序は \fBテーブル情報名n\fP の順序と同じです。 .UNINDENT .UNINDENT .SS \fBtable_remove\fP .SS Summary .sp table_remove \- テーブルの削除 .sp groonga組込コマンドの一つであるtable_removeについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp table_removeはテーブルと定義されているカラムを削除します。カラムに付随するインデックスも再帰的に削除されます。 .SS Syntax .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_remove name .ft P .fi .UNINDENT .UNINDENT .SS Usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_remove Entry [true] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .INDENT 0.0 .TP .B \fBname\fP 削除対象のカラムが定義されているテーブルの名前を指定します。 .UNINDENT .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [成功かどうかのフラグ] .ft P .fi .UNINDENT .UNINDENT .sp \fB成功かどうかのフラグ\fP .INDENT 0.0 .INDENT 3.5 エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .UNINDENT .UNINDENT .SS \fBtokenize\fP .SS Summary .sp \fBtokenize\fP command tokenizes text by the specified tokenizer. It is useful to debug tokenization. .SS Syntax .sp \fBtokenize\fP command has required parameters and optional parameters. \fBtokenizer\fP and \fBstring\fP are required parameters. Others are optional: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize tokenizer string [normalizer=null] [flags=NONE] [mode=ADD] .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Fulltext Search" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "Fu" # }, # { # "position": 1, # "value": "ul" # }, # { # "position": 2, # "value": "ll" # }, # { # "position": 3, # "value": "lt" # }, # { # "position": 4, # "value": "te" # }, # { # "position": 5, # "value": "ex" # }, # { # "position": 6, # "value": "xt" # }, # { # "position": 7, # "value": "t " # }, # { # "position": 8, # "value": " S" # }, # { # "position": 9, # "value": "Se" # }, # { # "position": 10, # "value": "ea" # }, # { # "position": 11, # "value": "ar" # }, # { # "position": 12, # "value": "rc" # }, # { # "position": 13, # "value": "ch" # }, # { # "position": 14, # "value": "h" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It has only required parameters. \fBtokenizer\fP is \fBTokenBigram\fP and \fBstring\fP is \fB"Fulltext Search"\fP\&. It returns tokens that is generated by tokenizing \fB"Fulltext Search"\fP with \fBTokenBigram\fP tokenizer. It doesn\(aqt normalize \fB"Fulltext Search"\fP\&. .SS Parameters .sp This section describes all parameters. Parameters are categorized. .SS Required parameters .sp There are required parameters, \fBtokenizer\fP and \fBstring\fP\&. .SS \fBtokenizer\fP .sp It specifies the tokenizer name. \fBtokenize\fP command uses the tokenizer that is named \fBtokenizer\fP\&. .sp See \fB/reference/tokenizers\fP about built\-in tokenizers. .sp Here is an example to use built\-in \fBTokenTrigram\fP tokenizer. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenTrigram "Fulltext Search" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "Ful" # }, # { # "position": 1, # "value": "ull" # }, # { # "position": 2, # "value": "llt" # }, # { # "position": 3, # "value": "lte" # }, # { # "position": 4, # "value": "tex" # }, # { # "position": 5, # "value": "ext" # }, # { # "position": 6, # "value": "xt " # }, # { # "position": 7, # "value": "t S" # }, # { # "position": 8, # "value": " Se" # }, # { # "position": 9, # "value": "Sea" # }, # { # "position": 10, # "value": "ear" # }, # { # "position": 11, # "value": "arc" # }, # { # "position": 12, # "value": "rch" # }, # { # "position": 13, # "value": "ch" # }, # { # "position": 14, # "value": "h" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp If you want to use other tokenizers, you need to register additional tokenizer plugin by \fBregister\fP command. For example, you can use \fI\%KyTea\fP based tokenizer by registering \fBtokenizers/kytea\fP\&. .SS \fBstring\fP .sp It specifies any string which you want to tokenize. .sp If you want to include spaces in \fBstring\fP, you need to quote \fBstring\fP by single quotation (\fB\(aq\fP) or double quotation (\fB"\fP). .sp Here is an example to use spaces in \fBstring\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Groonga is a fast fulltext earch engine!" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "Gr" # }, # { # "position": 1, # "value": "ro" # }, # { # "position": 2, # "value": "oo" # }, # { # "position": 3, # "value": "on" # }, # { # "position": 4, # "value": "ng" # }, # { # "position": 5, # "value": "ga" # }, # { # "position": 6, # "value": "a " # }, # { # "position": 7, # "value": " i" # }, # { # "position": 8, # "value": "is" # }, # { # "position": 9, # "value": "s " # }, # { # "position": 10, # "value": " a" # }, # { # "position": 11, # "value": "a " # }, # { # "position": 12, # "value": " f" # }, # { # "position": 13, # "value": "fa" # }, # { # "position": 14, # "value": "as" # }, # { # "position": 15, # "value": "st" # }, # { # "position": 16, # "value": "t " # }, # { # "position": 17, # "value": " f" # }, # { # "position": 18, # "value": "fu" # }, # { # "position": 19, # "value": "ul" # }, # { # "position": 20, # "value": "ll" # }, # { # "position": 21, # "value": "lt" # }, # { # "position": 22, # "value": "te" # }, # { # "position": 23, # "value": "ex" # }, # { # "position": 24, # "value": "xt" # }, # { # "position": 25, # "value": "t " # }, # { # "position": 26, # "value": " e" # }, # { # "position": 27, # "value": "ea" # }, # { # "position": 28, # "value": "ar" # }, # { # "position": 29, # "value": "rc" # }, # { # "position": 30, # "value": "ch" # }, # { # "position": 31, # "value": "h " # }, # { # "position": 32, # "value": " e" # }, # { # "position": 33, # "value": "en" # }, # { # "position": 34, # "value": "ng" # }, # { # "position": 35, # "value": "gi" # }, # { # "position": 36, # "value": "in" # }, # { # "position": 37, # "value": "ne" # }, # { # "position": 38, # "value": "e!" # }, # { # "position": 39, # "value": "!" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Optional parameters .sp There are optional parameters. .SS \fBnormalizer\fP .sp It specifies the normalizer name. \fBtokenize\fP command uses the normalizer that is named \fBnormalizer\fP\&. Normalizer is important for N\-gram family tokenizers such as \fBTokenBigram\fP\&. .sp Normalizer detects character type for each character while normalizing. N\-gram family tokenizers use character types while tokenizing. .sp Here is an example that doesn\(aqt use normalizer. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Fulltext Search" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "Fu" # }, # { # "position": 1, # "value": "ul" # }, # { # "position": 2, # "value": "ll" # }, # { # "position": 3, # "value": "lt" # }, # { # "position": 4, # "value": "te" # }, # { # "position": 5, # "value": "ex" # }, # { # "position": 6, # "value": "xt" # }, # { # "position": 7, # "value": "t " # }, # { # "position": 8, # "value": " S" # }, # { # "position": 9, # "value": "Se" # }, # { # "position": 10, # "value": "ea" # }, # { # "position": 11, # "value": "ar" # }, # { # "position": 12, # "value": "rc" # }, # { # "position": 13, # "value": "ch" # }, # { # "position": 14, # "value": "h" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp All alphabets are tokenized by two characters. For example, \fBFu\fP is a token. .sp Here is an example that uses normalizer. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Fulltext Search" NormalizerAuto # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "fulltext" # }, # { # "position": 1, # "value": "search" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Continuous alphabets are tokenized as one token. For example, \fBfulltext\fP is a token. .sp If you want to tokenize by two characters with noramlizer, use \fBTokenBigramSplitSymbolAlpha\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigramSplitSymbolAlpha "Fulltext Search" NormalizerAuto # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "fu" # }, # { # "position": 1, # "value": "ul" # }, # { # "position": 2, # "value": "ll" # }, # { # "position": 3, # "value": "lt" # }, # { # "position": 4, # "value": "te" # }, # { # "position": 5, # "value": "ex" # }, # { # "position": 6, # "value": "xt" # }, # { # "position": 7, # "value": "t" # }, # { # "position": 8, # "value": "se" # }, # { # "position": 9, # "value": "ea" # }, # { # "position": 10, # "value": "ar" # }, # { # "position": 11, # "value": "rc" # }, # { # "position": 12, # "value": "ch" # }, # { # "position": 13, # "value": "h" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp All alphabets are tokenized by two characters. And they are normalized to lower case characters. For example, \fBfu\fP is a token. .SS \fBflags\fP .sp It specifies a tokenization customize options. You can specify multiple options separated by "\fB|\fP". For example, \fBNONE|ENABLE_TOKENIZED_DELIMITER\fP\&. .sp Here are available flags. .TS center; |l|l|. _ T{ Flag T} T{ Description T} _ T{ \fBNONE\fP T} T{ Just ignored. T} _ T{ \fBENABLE_TOKENIZED_DELIMITER\fP T} T{ Enables tokenized delimiter. See \fB/reference/tokenizers\fP about tokenized delimiter details. T} _ .TE .sp Here is an example that uses \fBENABLE_TOKENIZED_DELIMITER\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenDelimit "Full￾text Sea￾crch" NormalizerAuto ENABLE_TOKENIZED_DELIMITER # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # { # "position": 0, # "value": "full" # }, # { # "position": 1, # "value": "text sea" # }, # { # "position": 2, # "value": "crch" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fBTokenDelimit\fP tokenizer is one of tokenized delimiter supported tokenizer. \fBENABLE_TOKENIZED_DELIMITER\fP enables tokenized delimiter. Tokenized delimiter is special character that indicates token border. It is \fBU+FFFE\fP\&. The character is not assigned any character. It means that the character is not appeared in normal string. So the character is good character for this puropose. If \fBENABLE_TOKENIZED_DELIMITER\fP is enabled, the target string is treated as already tokenized string. Tokenizer just tokenizes by tokenized delimiter. .SS \fBmode\fP .sp It specifies a tokenize mode. If the mode is specified \fBADD\fP, the text is tokenized by the rule that adding a document. If the mode is specified \fBGET\fP, the text is tokenized by the rule that searching a document. If the mode is omitted, the text is tokenized by the \fBADD\fP mode. .sp The default mode is \fBADD\fP\&. .sp Here is an example to the \fBADD\fP mode. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Fulltext Search" \-\-mode ADD # [ # [ # 0, # 1408017697.66886, # 0.00126171112060547 # ], # [ # { # "value": "Fu", # "position": 0 # }, # { # "value": "ul", # "position": 1 # }, # { # "value": "ll", # "position": 2 # }, # { # "value": "lt", # "position": 3 # }, # { # "value": "te", # "position": 4 # }, # { # "value": "ex", # "position": 5 # }, # { # "value": "xt", # "position": 6 # }, # { # "value": "t ", # "position": 7 # }, # { # "value": " S", # "position": 8 # }, # { # "value": "Se", # "position": 9 # }, # { # "value": "ea", # "position": 10 # }, # { # "value": "ar", # "position": 11 # }, # { # "value": "rc", # "position": 12 # }, # { # "value": "ch", # "position": 13 # }, # { # "value": "h", # "position": 14 # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The last alphabet is tokenized by one character. .sp Here is an example to the \fBGET\fP mode. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenize TokenBigram "Fulltext Search" \-\-mode GET # [ # [ # 0, # 1408017732.62883, # 0.000665903091430664 # ], # [ # { # "value": "Fu", # "position": 0 # }, # { # "value": "ul", # "position": 1 # }, # { # "value": "ll", # "position": 2 # }, # { # "value": "lt", # "position": 3 # }, # { # "value": "te", # "position": 4 # }, # { # "value": "ex", # "position": 5 # }, # { # "value": "xt", # "position": 6 # }, # { # "value": "t ", # "position": 7 # }, # { # "value": " S", # "position": 8 # }, # { # "value": "Se", # "position": 9 # }, # { # "value": "ea", # "position": 10 # }, # { # "value": "ar", # "position": 11 # }, # { # "value": "rc", # "position": 12 # }, # { # "value": "ch", # "position": 13 # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The last alphabet is tokenized by two characters. .SS Return value .sp \fBtokenize\fP command returns tokenized tokens. Each token has some attributes except token itself. The attributes will be increased in the feature: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, tokens] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBtokens\fP .INDENT 0.0 .INDENT 3.5 \fBtokens\fP is an array of token. Token is an object that has the following attributes. .TS center; |l|l|. _ T{ Name T} T{ Description T} _ T{ \fBvalue\fP T} T{ Token itself. T} _ T{ \fBposition\fP T} T{ The N\-th token. T} _ .TE .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/tokenizers\fP .UNINDENT .SS \fBtokenizer_list\fP .SS Summary .sp \fBtokenizer_list\fP command lists tokenizers in a database. .SS Syntax .sp \fBtokenizer_list\fP command takes no parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenizer_list .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tokenizer_list # [ # [ # 0, # 0.0, # 0.0 # ], # [ # { # "name": "TokenMecab" # }, # { # "name": "TokenDelimit" # }, # { # "name": "TokenUnigram" # }, # { # "name": "TokenBigram" # }, # { # "name": "TokenTrigram" # }, # { # "name": "TokenBigramSplitSymbol" # }, # { # "name": "TokenBigramSplitSymbolAlpha" # }, # { # "name": "TokenBigramSplitSymbolAlphaDigit" # }, # { # "name": "TokenBigramIgnoreBlank" # }, # { # "name": "TokenBigramIgnoreBlankSplitSymbol" # }, # { # "name": "TokenBigramIgnoreBlankSplitSymbolAlpha" # }, # { # "name": "TokenBigramIgnoreBlankSplitSymbolAlphaDigit" # }, # { # "name": "TokenDelimitNull" # } # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It returns tokenizers in a database. .SS Return value .sp \fBtokenizer_list\fP command returns tokenizers. Each tokenizers has an attribute that contains the name. The attribute will be increased in the feature: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, tokenizers] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBtokenizers\fP .INDENT 0.0 .INDENT 3.5 \fBtokenizers\fP is an array of tokenizer. Tokenizer is an object that has the following attributes. .TS center; |l|l|. _ T{ Name T} T{ Description T} _ T{ \fBname\fP T} T{ Tokenizer name. T} _ .TE .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/tokenizers\fP .IP \(bu 2 \fB/reference/commands/tokenize\fP .UNINDENT .SS \fBtruncate\fP .SS Summary .sp \fBtruncate\fP command deletes all records from specified table. .SS Syntax .sp \fBtruncate\fP command takes only one parameter. .sp The required parameter is only \fBtable\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C truncate table .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here is a simple example of \fBtruncate\fP command. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Users TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Users [ {"_key": "Alice", "score": 2}, {"_key": "Bob", "score": 0}, {"_key": "Carlos", "score": \-1} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] select Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 1, # "Alice" # ], # [ # 2, # "Bob" # ], # [ # 3, # "Carlos" # ] # ] # ] # ] truncate Users # [[0, 1337566253.89858, 0.000355720520019531], true] select Users # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 0 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp This section describes parameters of \fBtruncate\fP\&. .SS Required parameter .sp There is required parameter, \fBtable_name\fP\&. .SS \fBtable_name\fP .sp It specifies the name of table. .SS Return value .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HEADER, SUCCEEDED_OR_NOT] .ft P .fi .UNINDENT .UNINDENT .sp \fBHEADER\fP .INDENT 0.0 .INDENT 3.5 See \fB/reference/command/output_format\fP about \fBHEADER\fP\&. .UNINDENT .UNINDENT .sp \fBSUCCEEDED_OR_NOT\fP .INDENT 0.0 .INDENT 3.5 If command succeeded, it returns true, otherwise it returns false on error. .UNINDENT .UNINDENT .SS データ型 .SS 名前 .sp Groonga データ型 .SS 説明 .sp Groonga は、格納するデータの型を区別します。 .sp Groongaのデータベースでは、テーブルの主キーや、カラムの値はいずれも何らかの型に属します。また通常は、一つのテーブルの中の全てのレコードについて、カラムの値は共通となります。 .sp 主キーの型とカラムの型には、Groongaで予め定義済みの型か、ユーザが定義する型、またはユーザが定義したテーブルを指定することができます。 .sp 主キーの型に他のテーブルを指定する場合は、そのテーブルは、主キーの型となるテーブルのサブセットとなります。 .sp カラムの型に他のテーブルを指定する場合は、そのカラムは、カラムの型となるテーブルの参照キーとなります。 .SS 組込型 .sp 以下の型が組込型としてあらかじめ定義されています。 .sp \fBObject\fP .INDENT 0.0 .INDENT 3.5 任意のテーブルに属する全てのレコードです。 [1] .UNINDENT .UNINDENT .sp \fBBool\fP .INDENT 0.0 .INDENT 3.5 ブーリアン型やブール型などと呼ばれる型であり、真偽値を表します。取り得る値はtrueとfalseです。（デフォルト値: false） .sp \fB/reference/commands/load\fP コマンドで値を格納するときは、false、0、空文字列のいずれかを指定するとfalseになり、それ以外を指定するとtrueになります。 .UNINDENT .UNINDENT .sp \fBInt8\fP .INDENT 0.0 .INDENT 3.5 8bit符号付き整数であり、\-128以上127以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBUInt8\fP .INDENT 0.0 .INDENT 3.5 8bit符号なし整数であり、0以上255以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBInt16\fP .INDENT 0.0 .INDENT 3.5 16bit符号付き整数であり、\-32,768以上32,767以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBUInt16\fP .INDENT 0.0 .INDENT 3.5 16bit符号なし整数であり、0以上65,535以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBInt32\fP .INDENT 0.0 .INDENT 3.5 32bit符号付き整数であり、\-2,147,483,648以上2,147,483,647以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBUInt32\fP .INDENT 0.0 .INDENT 3.5 32bit符号なし整数であり、0以上4,294,967,295以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBInt64\fP .INDENT 0.0 .INDENT 3.5 64bit符号付き整数であり、\-9,223,372,036,854,775,808以上9,223,372,036,854,775,807以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBUInt64\fP .INDENT 0.0 .INDENT 3.5 64bit符号なし整数であり、0以上18,446,744,073,709,551,615以下の整数を表します。（デフォルト値: 0） .UNINDENT .UNINDENT .sp \fBFloat\fP .INDENT 0.0 .INDENT 3.5 IEEE 754形式の倍精度浮動小数点数であり、実数を表します。（デフォルト値: 0.0） .sp IEEE 754形式の詳細については、 \fI\%IEEE 754 \- Wikipedia\fP や \fI\%IEEE 754: Standard for Binary Floating\-Point\fP を参照してください。 .UNINDENT .UNINDENT .sp \fBTime\fP .INDENT 0.0 .INDENT 3.5 日時を表す型であり、1970年1月1日0時0分0秒からの経過時間を、マイクロ秒単位で64bit符号付き整数により表現します。（デフォルト値: 0） .sp \fB/reference/commands/load\fP コマンドで値を格納するときは、1970年1月1日0時0分0秒からの経過秒数を指定します。秒単位より詳細な日時を指定するには、小数を使います。 .UNINDENT .UNINDENT .sp \fBShortText\fP .INDENT 0.0 .INDENT 3.5 4,095バイト以下の文字列を表します。（デフォルト値: ""） .UNINDENT .UNINDENT .sp \fBText\fP .INDENT 0.0 .INDENT 3.5 65,535バイト以下の文字列を表します。（デフォルト値: ""） .UNINDENT .UNINDENT .sp \fBLongText\fP .INDENT 0.0 .INDENT 3.5 2,147,483,647バイト以下の文字列を表します。（デフォルト値: ""） .UNINDENT .UNINDENT .sp \fBTokyoGeoPoint\fP .INDENT 0.0 .INDENT 3.5 旧日本測地系による経緯度であり、経度と緯度をミリ秒単位で表現した整数の組により表現します。（デフォルト値: 0x0） .sp 度分秒形式でx度y分z秒となる経度・緯度は、(((x * 60) + y) * 60 + z) * 1000という計算式でミリ秒単位へと変換されます。 \fB/reference/commands/load\fP コマンドで値を格納するときは、"ミリ秒単位の経度xミリ秒単位の緯度" もしくは "経度の小数表記x緯度の小数表記" という文字列表現を使って指定します。経度と緯度の区切りとしては、\(aqx\(aq のほかに \(aq,\(aq を使うことができます。 .sp 測地系の詳細については、 \fI\%測地系 \- Wikipedia\fP を参照してください。 .UNINDENT .UNINDENT .sp \fBWGS84GeoPoint\fP .INDENT 0.0 .INDENT 3.5 世界測地系（World Geodetic System, WGS 84）による経緯度であり、経度と緯度をミリ秒単位で表現した整数の組により表現します。（デフォルト値: 0x0） .sp 度分秒形式からミリ秒形式への変換方法や \fB/reference/commands/load\fP コマンドにおける指定方法はTokyoGeoPointと同じです。 .UNINDENT .UNINDENT .SS 型に関する制限事項 .SS テーブルの主キーに指定できない型 .sp Text型とLongText型については、テーブルの主キーに指定することはできません。 .SS ベクターとして格納できない型 .sp Groongaのカラムは、ある型のベクターを保存することができます。しかし、ShortText, Text, LongTextの３つの型についてはベクターとして保存したり出力したりすることはできますが、検索条件やドリルダウン条件に指定することができません。 .sp テーブル型は、ベクターとして格納することができます。よって、ShortTextのベクターを検索条件やドリルダウン条件に使用したい場合には、主キーがShortText型のテーブルを別途作成し、そのテーブルを型として利用します。 脚注 .IP [1] 5 Object型はv1.2でサポートされます。 .SS Tables .SS Summary .sp Table in Groonga manages relation between ID and key. Groonga provides four table types. They are \fBTABLE_NO_KEY\fP, \fBTABLE_HASH_KEY\fP, \fBTABLE_PAT_KEY\fP and \fBTABLE_DAT_KEY\fP\&. .sp All tables except \fBTABLE_NO_KEY\fP provides both fast ID search by key and fast key search by ID. \fBTABLE_NO_KEY\fP doesn\(aqt support key. \fBTABLE_NO_KEY\fP only manages ID. So \fBTABLE_NO_KEY\fP doesn\(aqt provides ID search and key search. .SS Characteristics .sp Here is a chracteristic table of all tables in Groonga. (\fBTABLE_\fP prefix is omitted in the table.) .TS center; |l|l|l|l|l|. _ T{ T} T{ \fBNO_KEY\fP T} T{ \fBHASH_KEY\fP T} T{ \fBPAT_KEY\fP T} T{ \fBDAT_KEY\fP T} _ T{ Data structure T} T{ Array T} T{ Hash table T} T{ Patricia trie T} T{ Double array trie T} _ T{ ID support T} T{ o T} T{ o T} T{ o T} T{ o T} _ T{ Key support T} T{ x T} T{ o T} T{ o T} T{ o T} _ T{ Value support T} T{ o T} T{ o T} T{ o T} T{ x T} _ T{ Key \-> ID speed .INDENT 0.0 .IP \(bu 2 o: fast .IP \(bu 2 x: slow .UNINDENT T} T{ \- T} T{ oo T} T{ x T} T{ o T} _ T{ Update speed .INDENT 0.0 .IP \(bu 2 o: fast .IP \(bu 2 x: slow .UNINDENT T} T{ ooo T} T{ o T} T{ o T} T{ x T} _ T{ Size .INDENT 0.0 .IP \(bu 2 o: small .IP \(bu 2 x: large .UNINDENT T} T{ ooo T} T{ o T} T{ oo T} T{ x T} _ T{ Key update T} T{ \- T} T{ x T} T{ x T} T{ o T} _ T{ Common prefix search T} T{ \- T} T{ x T} T{ o T} T{ o T} _ T{ Predictive search T} T{ \- T} T{ x T} T{ o T} T{ o T} _ T{ Range search T} T{ \- T} T{ x T} T{ o T} T{ o T} _ .TE .SS \fBTABLE_NO_KEY\fP .sp \fBTABLE_NO_KEY\fP is very fast and very small but it doesn\(aqt support key. \fBTABLE_NO_KEY\fP is a only table that doesn\(aqt support key. .sp You cannot use \fBTABLE_NO_KEY\fP for lexicon for fulltext search because lexicon stores tokens as key. \fBTABLE_NO_KEY\fP is useful for no key records such as log. .SS \fBTABLE_HASH_KEY\fP .sp \fBTABLE_HASH_KEY\fP is fast but it doesn\(aqt support advanced search functions such as common prefix search and predictive search. .sp \fBTABLE_HASH_KEY\fP is useful for index for exact search such as tag search. .SS \fBTABLE_PAT_KEY\fP .sp \fBTABLE_PAT_KEY\fP is small and supports advanced search functions. .sp \fBTABLE_PAT_KEY\fP is useful for lexicon for fulltext search and index for range search. .SS \fBTABLE_DAT_KEY\fP .sp \fBTABLE_DAT_KEY\fP is fast and supports key update but it is large. It is not suitable for storing many records. \fBTABLE_DAT_KEY\fP is a only table that supports key update. .sp \fBTABLE_DAT_KEY\fP is used in Groonga database. Groonga database needs to convert object name such as \fBShortText\fP, \fBTokenBigram\fP and table names to object ID. And Groonga database needs to rename object name. Those features are implemented by \fBTABLE_DAT_KEY\fP\&. The number of objects is small. So large data size demerit of \fBTABLE_DAT_KEY\fP can be ignored. .SS Record ID .sp Record ID is assigned automatically. You cannot assign record ID. .sp Record ID of deleted record may be reused. .sp Valid record ID range is between 1 and 268435455. (1 and 268435455 are valid IDs.) .SS Persistent table and temporary table .sp Table is persistent table or temporary table. .SS Persistent table .sp Persistent table is named and registered to database. Records in persistent table aren\(aqt deleted after closing table or database. .sp Persistent table can be created by \fB/reference/commands/table_create\fP command. .SS Temporary table .sp Temporary table is anonymous. Records in temporary table are deleted after closing table. Temporary table is used to store search result, sort result, group (drilldown) result and so on. \fBTABLE_HASH_KEY\fP is used for search result and group result. \fBTABLE_NO_KEY\fP is used for sort result. .SS Limitations .sp The max number of records is 268435455. You cannot add 268435456 or more records in a table. .sp The max number of a key size is 4096byte. You cannot use 4097byte or larger key. You can use column instead of key for 4097byte or larger size data. \fBText\fP and \fBLargeText\fP types supports 4097byte or larger size data. .sp The max number of total key size is 4GiB. You need to split a table, split a database (sharding) or reduce each key size to handle 4GiB or more larger total key size. .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/table_create\fP .UNINDENT .SS Column .sp Column is a data store object or an index object for fast search. .sp A column belongs to a table. Table has zero or more columns. .sp Both data store column and index column have type. Type of data store column specifies data range. In other words, it is "value type". Type of index column specifies set of documents to be indexed. A set of documents is a table in Groonga. In other words, type of index column must be a table. .sp Here are data store columns: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBcolumns/scalar\fP .IP \(bu 2 \fBcolumns/vector\fP .IP \(bu 2 \fBcolumns/pseudo\fP .UNINDENT .UNINDENT .UNINDENT .sp Here is an index column: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBcolumns/index\fP .UNINDENT .UNINDENT .UNINDENT .SS Normalizers .SS Summary .sp Groonga has normalizer module that normalizes text. It is used when tokenizing text and storing table key. For example, \fBA\fP and \fBa\fP are processed as the same character after normalization. .sp Normalizer module can be added as a plugin. You can customize text normalization by registering your normalizer plugins to Groonga. .sp A normalizer module is attached to a table. A table can have zero or one normalizer module. You can attach a normalizer module to a table by \fItable\-create\-normalizer\fP option in \fB/reference/commands/table_create\fP\&. .sp Here is an example \fBtable_create\fP that uses \fBNormalizerAuto\fP normalizer module: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Dictionary TABLE_HASH_KEY ShortText \-\-normalizer NormalizerAuto # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga 2.0.9 or earlier doesn\(aqt have \fB\-\-normalizer\fP option in \fBtable_create\fP\&. \fBKEY_NORMALIZE\fP flag was used instead. .sp You can open an old database by Groonga 2.1.0 or later. An old database means that the database is created by Groonga 2.0.9 or earlier. But you cannot open the opened old database by Groonga 2.0.9 or earlier. Once you open the old database by Groonga 2.1.0 or later, \fBKEY_NORMALIZE\fP flag information in the old database is converted to normalizer information. So Groonga 2.0.9 or earlier cannot find \fBKEY_NORMALIZE\fP flag information in the opened old database. .UNINDENT .UNINDENT .sp Keys of a table that has a normalizer module are normalized: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Dictionary [ {"_key": "Apple"}, {"_key": "black"}, {"_key": "COLOR"} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] select Dictionary # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ] # ], # [ # 1, # "apple" # ], # [ # 2, # "black" # ], # [ # 3, # "color" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fBNormalizerAuto\fP normalizer normalizes a text as a downcased text. For example, \fB"Apple"\fP is normalized to \fB"apple"\fP, \fB"black"\fP is normalized to \fB"blank"\fP and \fB"COLOR"\fP is normalized to \fB"color"\fP\&. .sp If a table is a lexicon for fulltext search, tokenized tokens are normalized. Because tokens are stored as table keys. Table keys are normalized as described above. .SS Built\-in normalizers .sp Here is a list of built\-in normalizers: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBNormalizerAuto\fP .IP \(bu 2 \fBNormalizerNFKC51\fP .UNINDENT .UNINDENT .UNINDENT .SS \fBNormalizerAuto\fP .sp Normally you should use \fBNormalizerAuto\fP normalizer. \fBNormalizerAuto\fP was the normalizer for Groonga 2.0.9 or earlier. \fBKEY_NORMALIZE\fP flag in \fBtable_create\fP on Groonga 2.0.9 or earlier equals to \fB\-\-normalizer NormalizerAuto\fP option in \fBtable_create\fP on Groonga 2.1.0 or later. .sp \fBNormalizerAuto\fP supports all encoding. It uses Unicode NFKC (Normalization Form Compatibility Composition) for UTF\-8 encoding text. It uses encoding specific original normalization for other encodings. The results of those original normalization are similar to NFKC. .sp For example, half\-width katakana (such as U+FF76 HALFWIDTH KATAKANA LETTER KA) + half\-width katakana voiced sound mark (U+FF9E HALFWIDTH KATAKANA VOICED SOUND MARK) is normalized to full\-width katakana with voiced sound mark (U+30AC KATAKANA LETTER GA). The former is two chracters but the latter is one character. .sp Here is an example that uses \fBNormalizerAuto\fP normalizer: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create NormalLexicon TABLE_HASH_KEY ShortText \-\-normalizer NormalizerAuto # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .SS \fBNormalizerNFKC51\fP .sp \fBNormalizerNFKC51\fP normalizes texts by Unicode NFKC (Normalization Form Compatibility Composition) for Unicode version 5.1. It supports only UTF\-8 encoding. .sp Normally you don\(aqt need to use \fBNormalizerNFKC51\fP explicitly. You can use \fBNormalizerAuto\fP instead. .sp Here is an example that uses \fBNormalizerNFKC51\fP normalizer: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create NFKC51Lexicon TABLE_HASH_KEY ShortText \-\-normalizer NormalizerNFKC51 # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .SS Additional normalizers .sp Here is a list of additional normalizers provided by \fBgroonga\-normalizer\-mysql\fP plugins: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBNormalizerMySQLGeneralCI\fP .IP \(bu 2 \fBNormalizerMySQLUnicodeCI\fP .IP \(bu 2 \fBNormalizerMySQLUnicodeCIExceptKanaCIKanaWithVoicedSoundMark\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBgroonga\-normalizer\-mysql\fP is a Groonga plugin. It provides MySQL compatible normalizers to Groonga. \fBNormalizerMySQLGeneralCI\fP corresponds to \fButf8mb4_general_ci\fP\&. .sp You need to register \fBnormalizers/mysql\fP plugin in advance. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register normalizers/mysql # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Here is an example that uses \fBNormalizerMySQLGeneralCI\fP normalizer: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create MySQLGeneralLexicon TABLE_HASH_KEY ShortText \-\-normalizer NormalizerMySQLGeneralCI # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/table_create\fP .UNINDENT .SS Tokenizers .sp TODO: Write me. .sp Here are the list of built\-in tokenizers: .INDENT 0.0 .IP \(bu 2 TokenBigram .IP \(bu 2 TokenBigramSplitSymbol .IP \(bu 2 TokenBigramSplitSymbolAlpha .IP \(bu 2 TokenBigramSplitSymbolAlphaDigit .IP \(bu 2 TokenBigramIgnoreBlank .IP \(bu 2 TokenBigramIgnoreBlankSplitSymbol .IP \(bu 2 TokenBigramIgnoreBlankSplitAlpha .IP \(bu 2 TokenBigramIgnoreBlankSplitAlphaDigit .IP \(bu 2 TokenDelimit .IP \(bu 2 TokenDelimitNull .IP \(bu 2 TokenTrigram .IP \(bu 2 TokenUnigram .UNINDENT .SS Query expanders .SS QueryExpanderTSV .SS Summary .sp \fBQueryExpanderTSV\fP is a query expander plugin that reads synonyms from TSV (Tab Separated Values) file. This plugin provides poor feature than the embedded query expansion feature. For example, it doesn\(aqt support word normalization. But it may be easy to use because you can manage your synonyms by TSV file. You can edit your synonyms by spreadsheet application such as Excel. With the embedded query expansion feature, you manage your synonyms by Groonga\(aqs table. .SS Install .sp You need to register \fBquery_expanders/tsv\fP as a plugin before you use \fBQueryExpanderTSV\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register query_expanders/tsv .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp You just add \fB\-\-query_expansion QueryExpanderTSV\fP parameter to \fBselect\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "QUERY" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp If \fBQUERY\fP has registered synonyms, they are expanded. For example, there are the following synonyms. .TS center; |l|l|l|. _ T{ word T} T{ synonym 1 T} T{ synonym 2 T} _ T{ groonga T} T{ groonga T} T{ Senna T} _ T{ mroonga T} T{ mroonga T} T{ groonga MySQL T} _ .TE .sp The table means that \fBsynonym 1\fP and \fBsynonym 2\fP are synonyms of \fBword\fP\&. For example, \fBgroonga\fP and \fBSenna\fP are synonyms of \fBgroonga\fP\&. And \fBmroonga\fP and \fBgroonga MySQL\fP are synonyms of \fBmroonga\fP\&. .sp Here is an example of query expnasion that uses \fBgroonga\fP as query: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "groonga" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp The above command equals to the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "groonga OR Senna" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp Here is another example of query expnasion that uses \fBmroonga search\fP as query: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "mroonga search" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp The above command equals to the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "(mroonga OR (groonga MySQL)) search" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp It is important that registered words (\fBgroonga\fP and \fBmroonga\fP) are only expanded to synonyms and not registered words (\fBsearch\fP) are not expanded. Query expansion isn\(aqt occurred recursively. \fBgroonga\fP is appeared in \fB(mroonga OR (groonga MySQL))\fP as query expansion result but it isn\(aqt expanded. .sp Normally, you need to include \fBword\fP itself into synonyms. For example, \fBgroonga\fP and \fBmroonga\fP are included in synonyms of themselves. If you want to ignore \fBword\fP itself, you don\(aqt include \fBword\fP itself into synonyms. For example, if you want to use query expansion as spelling correction, you should use the following synonyms. .TS center; |l|l|. _ T{ word T} T{ synonym T} _ T{ gronga T} T{ groonga T} _ .TE .sp \fBgronga\fP in \fBword\fP has a typo. A \fBo\fP is missing. \fBgroonga\fP in \fBsynonym\fP is the correct word. .sp Here is an example of using query expnasion as spelling correction: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "gronga" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp The above command equals to the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select \-\-query "groonga" \-\-query_expansion QueryExpanderTSV .ft P .fi .UNINDENT .UNINDENT .sp The former command has a typo in \fB\-\-query\fP value but the latter command doesn\(aqt have any typos. .SS TSV File .sp Synonyms are defined in TSV format file. This section describes about it. .SS Location .sp The file name should be \fBsynonyms.tsv\fP and it is located at configuration directory. For example, \fB/etc/groonga/synonyms.tsv\fP is a TSV file location. The location is decided at build time. .sp You can change the location by environment variable \fBGRN_QUERY_EXPANDER_TSV_SYNONYMS_FILE\fP at run time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % env GRN_QUERY_EXPANDER_TSV_SYNONYMS_FILE=/tmp/synonyms.tsv groonga .ft P .fi .UNINDENT .UNINDENT .sp With the above command, \fB/tmp/synonyms.tsv\fP file is used. .SS Format .sp You can define zero or more synonyms in a TSV file. You define a \fBword\fP and \fBsynonyms\fP pair by a line. \fBword\fP is expanded to \fBsynonyms\fP in \fB\-\-query\fP value. \fBSynonyms\fP are combined by \fBOR\fP\&. For example, \fBgroonga\fP and \fBSenna\fP synonyms are expanded as \fBgroonga OR Senna\fP\&. .sp The first column is \fBword\fP and the rest columns are \fBsynonyms\fP of the \fBword\fP\&. Here is a sample line for \fBword\fP is \fBgroonga\fP and \fBsynonyms\fP are \fBgroonga\fP and \fBSenna\fP\&. \fB(TAB)\fP means a tab character (\fBU+0009\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga(TAB)groonga(TAB)Senna .ft P .fi .UNINDENT .UNINDENT .sp Comment line is supported. Lines that start with \fB#\fP are ignored. Here is an example for comment line. \fBgroonga\fP line is ignored as comment line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #groonga(TAB)groonga(TAB)Senna mroonga(TAB)mroonga(TAB)groonga MySQL .ft P .fi .UNINDENT .UNINDENT .SS Limitation .sp You need to restart groonga to reload your synonyms. TSV file is loaded only at the plugin load time. .SS See also .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fIquery\-expansion\fP .UNINDENT .UNINDENT .UNINDENT .SS grn_expr .sp Grn_expr is an object that searches records with specified conditions and manipulates a database. It\(aqs pronounced as \fBgurun expression\fP\&. .sp Conditions for searching records from a database can be represented by conbining condition expressions such as \fBequal condition expression\fP and \fBless than condition expression\fP with set operations such as \fBAND\fP, \fBOR\fP and \fBNOT\fP\&. Grn_expr executes those conditions to search records. You can also use advanced searches such as similar search and near search by grn_expr. You can also use flexible full text search. For example, you can control hit scores for specified words and improve recall by re\-searching with high\-recall algolithm dinamically. To determine whether re\-searching or not, the number of matched rescords is used. .sp There are three ways to create grn_expr: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Parsing \fB/reference/grn_expr/query_syntax\fP string. .IP \(bu 2 Parsing \fB/reference/grn_expr/script_syntax\fP string. .IP \(bu 2 Calling grn_expr related APIs. .UNINDENT .UNINDENT .UNINDENT .sp \fB/reference/grn_expr/query_syntax\fP is for common search form in Internet search site. It\(aqs simple and easy to use but it has a limitation. You can not use all condition expressions and set operations in \fB/reference/grn_expr/query_syntax\fP\&. You can use \fB/reference/grn_expr/query_syntax\fP with \fBquery\fP option in \fB/reference/commands/select\fP\&. .sp \fB/reference/grn_expr/script_syntax\fP is ECMAScript like syntax. You can use all condition expresssions and set operations in \fB/reference/grn_expr/script_syntax\fP\&. You can use \fB/reference/grn_expr/script_syntax\fP with \fBfilter\fP option and \fBscorer\fP option in \fB/reference/commands/select\fP\&. .sp You can use groonga as a library and create a grn_expr by calling grn_expr related APIs. You can use full features with calling APIs like \fB/reference/grn_expr/script_syntax\fP\&. Calling APIs is useful creating a custom syntax to create grn_expr. They are used in \fI\%rroonga\fP that is Ruby bindings of Groonga. Rroonga can create a grn_expr by Ruby\(aqs syntax instead of parsing string. .SS Query syntax .sp Query syntax is a syntax to specify search condition for common Web search form. It is similar to the syntax of Google\(aqs search form. For example, \fBword1 word2\fP means that groonga searches records that contain both \fBword1\fP and \fBword2\fP\&. \fBword1 OR word2\fP means that groogna searches records that contain either \fBword1\fP or \fBword2\fP\&. .sp Query syntax consists of \fBconditional expression\fP, \fBcombind expression\fP and \fBassignment expression\fP\&. Nomrally \fBassignment expression\fP can be ignored. Because \fBassignment expression\fP is disabled in \fB\-\-query\fP option of \fB/reference/commands/select\fP\&. You can use it if you use groonga as library and customize query syntax parser options. .sp \fBConditinal expression\fP specifies an condition. \fBCombinded expression\fP consists of one or more \fBconditional expression\fP, \fBcombined expression\fP or \fBassignment expression\fP\&. \fBAssignment expression\fP can assigns a column to a value. .SS Sample data .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries n_likes COLUMN_SCALAR UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Entries [ {"_key": "The first post!", "content": "Welcome! This is my first post!", "n_likes": 5}, {"_key": "Groonga", "content": "I started to use groonga. It\(aqs very fast!", "n_likes": 10}, {"_key": "Mroonga", "content": "I also started to use mroonga. It\(aqs also very fast! Really fast!", "n_likes": 15}, {"_key": "Good\-bye Senna", "content": "I migrated all Senna system!", "n_likes": 3}, {"_key": "Good\-bye Tritonn", "content": "I also migrated all Tritonn system!", "n_likes": 3} ] # [[0, 1337566253.89858, 0.000355720520019531], 5] .ft P .fi .UNINDENT .UNINDENT .sp There is a table, \fBEntries\fP, for blog entries. An entry has title, content and the number of likes for the entry. Title is key of \fBEntries\fP\&. Content is value of \fBEntries.content\fP column. The number of likes is value of \fBEntries.n_likes\fP column. .sp \fBEntries._key\fP column and \fBEntries.content\fP column are indexed using \fBTokenBigram\fP tokenizer. So both \fBEntries._key\fP and \fBEntries.content\fP are fulltext search ready. .sp OK. The schema and data for examples are ready. .SS Escape .sp There are special characters in query syntax. To use a special character as itself, it should be escaped by prepending \fB\e\fP\&. For example, \fB"\fP is a special character. It is escaped as \fB\e"\fP\&. .sp Here is a special character list: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB[space]\fP (escaped as \fB[backslash][space]\fP) (You should substitute \fB[space]\fP with a white space character that is 0x20 in ASCII and \fB[backslash]\fP with \fB\e\e\fP\&.) .IP \(bu 2 \fB"\fP (escaped as \fB\e"\fP) .IP \(bu 2 \fB\(aq\fP (escaped as \fB\e\(aq\fP) .IP \(bu 2 \fB(\fP (escaped as \fB\e(\fP) .IP \(bu 2 \fB)\fP (escaped as \fB\e)\fP) .IP \(bu 2 \fB\e\fP (escaped as \fB\e\e\fP) .UNINDENT .UNINDENT .UNINDENT .sp You can use quote instead of escape special characters except \fB\e\fP (backslash). You need to use backslash for escaping backslash like \fB\e\e\fP in quote. .sp Quote syntax is \fB"..."\fP or \fB\(aq...\(aq\fP\&. You need escape \fB"\fP as \fB\e"\fP in \fB"..."\fP quote syntax. You need escape \fB\(aq\fP as \fB\e\(aq\fP in \fB\(aq...\(aq\fP quote syntax. For example, \fBAlice\(aqs brother (Bob)\fP can be quoted \fB"Alice\(aqs brother (Bob)"\fP or \fB\(aqAlice\e\(aqs brother (Bob)\(aq\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is a important point which you have to care. The \(aq\(aq\e\(aq\(aq (backslash) character is interpreted by command line shell. So if you want to search \(aq\(aq(\(aq\(aq itself for example, you need to escape twice (\(aq\(aq\e\e(\(aq\(aq) in command line shell. The command line shell interprets \(aq\(aq\e\e(\(aq\(aq as \(aq\(aq\e(\(aq\(aq, then pass such a literal to groonga. groonga regards \(aq\(aq\e(\(aq\(aq as \(aq\(aq(\(aq\(aq, then search \(aq\(aq(\(aq\(aq itself from database. If you can\(aqt do intended search by groonga, confirm whether special character is escaped properly. .UNINDENT .UNINDENT .SS Conditional expression .sp Here is available conditional expression list. .SS Full text search condition .sp Its syntax is \fBkeyword\fP\&. .sp \fBFull text search condition\fP specifies a full text search condition against the default match columns. Match columns are full text search target columns. .sp You should specify the default match columns for full text search. They can be specified by \fB\-\-match_columns\fP option of \fB/reference/commands/select\fP\&. If you don\(aqt specify the default match columns, this conditional expression fails. .sp This conditional expression does full text search with \fBkeyword\fP\&. \fBkeyword\fP should not contain any spaces. If \fBkeyword\fP contains a space such as \fBsearch keyword\fP, it means two full text search conditions; \fBsearch\fP and \fBkeyword\fP\&. If you want to specifies a keyword that contains one or more spaces, you can use \fBphrase search condition\fP that is described below. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query fast # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a word \fBfast\fP in \fBcontent\fP column value. .sp \fBcontent\fP column is the default match column. .SS Phrase search condition .sp Its syntax is \fB"search keyword"\fP\&. .sp \fBPhrase search condition\fP specifies a phrase search condition against the default match columns. .sp You should specify the default match columns for full text search. They can be specified by \fB\-\-match_columns\fP option of \fB/reference/commands/select\fP\&. If you don\(aqt specify the default match columns, this conditional expression fails. .sp This conditional expression does phrase search with \fBsearch keyword\fP\&. Phrase search searches records that contain \fBsearch\fP and \fBkeyword\fP and those terms are appeared in the same order and adjacent. Thus, \fBPut a search keyword in the form\fP is matched but \fBSearch by the keyword\fP and \fBThere is a keyword. Search by it!\fP aren\(aqt matched. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-match_columns content \-\-query \(aq"I started"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a phrase \fBI started\fP in \fBcontent\fP column value. \fBI also started\fP isn\(aqt matched because \fBI\fP and \fBstarted\fP aren\(aqt adjacent. .sp \fBcontent\fP column is the default match column. .SS Full text search condition (with explicit match column) .sp Its syntax is \fBcolumn:@keyword\fP\&. .sp It\(aqs similar to \fBfull text search condition\fP but it doesn\(aqt require the default match columns. You need to specify match column for the full text search condition by \fBcolumn:\fP instead of \fB\-\-match_columns\fP option of \fB/reference/commands/select\fP\&. .sp This condtional expression is useful when you want to use two or more full text search against different columns. The default match columns specified by \fB\-\-match_columns\fP option can\(aqt be specified multiple times. You need to specify the second match column by this conditional expression. .sp The different between \fBfull text search condition\fP and \fBfull text search condition (with explicit match column)\fP is whether advanced match columns are supported or not. \fBFull text search condition\fP supports advanced match columns but \fBfull text search condition (with explicit match column)\fP isn\(aqt supported. Advanced match columns has the following features: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Weight is supported. .IP \(bu 2 Using multiple columns are supported. .IP \(bu 2 Using index column as a match column is supported. .UNINDENT .UNINDENT .UNINDENT .sp See description of \fB\-\-match_columns\fP option of \fB/reference/commands/select\fP about them. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query content:@fast # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a word \fBfast\fP in \fBcontent\fP column value. .SS Phrase search condition (with explicit match column) .sp Its syntax is \fBcolumn:@"search keyword"\fP\&. .sp It\(aqs similar to \fBphrase search condition\fP but it doesn\(aqt require the default match columns. You need to specify match column for the phrase search condition by \fBcolumn:\fP instead of \fB\-\-match_columns\fP option of \fB/reference/commands/select\fP\&. .sp The different between \fBphrase search condition\fP and \fBphrase search condition (with explicit match column)\fP is similar to between \fBfull text search condition\fP and \fBfull text search condition (with explicit match column)\fP\&. \fBPhrase search condition\fP supports advanced match columns but \fBphrase search condition (with explicit match column)\fP isn\(aqt supported. See description of \fBfull text search condition (with explicit match column)\fP about advanced match columns. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aqcontent:@"I started"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a phrase \fBI started\fP in \fBcontent\fP column value. \fBI also started\fP isn\(aqt matched because \fBI\fP and \fBstarted\fP aren\(aqt adjacent. .SS Prefix search condition .sp Its syntax is \fBcolumn:^value\fP or \fBvalue*\fP\&. .sp This conditional expression does prefix search with \fBvalue\fP\&. Prefix search searches records that contain a word that starts with \fBvalue\fP\&. .sp You can use fast prefix search against a column. The column must be indexed and index table must be patricia trie table (\fBTABLE_PAT_KEY\fP) or double array trie table (\fBTABLE_DAT_KEY\fP). You can also use fast prefix search against \fB_key\fP pseudo column of patricia trie table or double array trie table. You don\(aqt need to index \fB_key\fP\&. .sp Prefix search can be used with other table types but it causes all records scan. It\(aqs not problem for small records but it spends more time for large records. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aq_key:^Goo\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a word that starts with \fBGoo\fP in \fB_key\fP pseudo column value. \fBGood\-bye Senna\fP and \fBGood\-bye Tritonn\fP are matched with the expression. .SS Suffix search condition .sp Its syntax is \fBcolumn:$value\fP\&. .sp This conditional expression does suffix search with \fBvalue\fP\&. Suffix search searches records that contain a word that ends with \fBvalue\fP\&. .sp You can use fast suffix search against a column. The column must be indexed and index table must be patricia trie table (\fBTABLE_PAT_KEY\fP) with \fBKEY_WITH_SIS\fP flag. You can also use fast suffix search against \fB_key\fP pseudo column of patricia trie table (\fBTABLE_PAT_KEY\fP) with \fBKEY_WITH_SIS\fP flag. You don\(aqt need to index \fB_key\fP\&. We recommended that you use index column based fast suffix search instead of \fB_key\fP based fast suffix search. \fB_key\fP based fast suffix search returns automatically registered substrings. (TODO: write document about suffix search and link to it from here.) .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Fast suffix search can be used only for non\-ASCII characters such as hiragana in Japanese. You cannot use fast suffix search for ASCII character. .UNINDENT .UNINDENT .sp Suffix search can be used with other table types or patricia trie table without \fBKEY_WITH_SIS\fP flag but it causes all records scan. It\(aqs not problem for small records but it spends more time for large records. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. It uses fast suffix search for hiragana in Japanese that is one of non\-ASCII characters. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Titles TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Titles content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create SuffixSearchTerms TABLE_PAT_KEY|KEY_WITH_SIS ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create SuffixSearchTerms index COLUMN_INDEX Titles content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Titles [ {"content": "ぐるんが"}, {"content": "むるんが"}, {"content": "せな"}, {"content": "とりとん"} ] # [[0, 1337566253.89858, 0.000355720520019531], 4] select Titles \-\-query \(aqcontent:$んが\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "content", # "ShortText" # ] # ], # [ # 2, # "むるんが" # ], # [ # 1, # "ぐるんが" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that have value that ends with \fBんが\fP in \fBcontent\fP column value. \fBぐるんが\fP and \fBむるんが\fP are matched with the expression. .SS Equal condition .sp Its syntax is \fBcolumn:value\fP\&. .sp It matches records that \fBcolumn\fP value is equal to \fBvalue\fP\&. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query _key:Groonga # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fB_key\fP column value is equal to \fBGroonga\fP\&. .SS Not equal condition .sp Its syntax is \fBcolumn:!value\fP\&. .sp It matches records that \fBcolumn\fP value isn\(aqt equal to \fBvalue\fP\&. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query _key:!Groonga # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fB_key\fP column value is not equal to \fBGroonga\fP\&. .SS Less than condition .sp Its syntax is \fBcolumn:value\fP\&. .sp It matches records that \fBcolumn\fP value is greater than \fBvalue\fP\&. .sp If \fBcolumn\fP type is numerical type such as \fBInt32\fP, \fBcolumn\fP value and \fBvalue\fP are compared as number. If \fBcolumn\fP type is text type such as \fBShortText\fP, \fBcolumn\fP value and \fBvalue\fP are compared as bit sequence. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query n_likes:>10 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is greater than \fB10\fP\&. .SS Less than or equal to condition .sp Its syntax is \fBcolumn:<=value\fP\&. .sp It matches records that \fBcolumn\fP value is less than or equal to \fBvalue\fP\&. .sp If \fBcolumn\fP type is numerical type such as \fBInt32\fP, \fBcolumn\fP value and \fBvalue\fP are compared as number. If \fBcolumn\fP type is text type such as \fBShortText\fP, \fBcolumn\fP value and \fBvalue\fP are compared as bit sequence. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query n_likes:<=10 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is less than or equal to \fB10\fP\&. .SS Greater than or equal to condition .sp Its syntax is \fBcolumn:>=value\fP\&. .sp It matches records that \fBcolumn\fP value is greater than or equal to \fBvalue\fP\&. .sp If \fBcolumn\fP type is numerical type such as \fBInt32\fP, \fBcolumn\fP value and \fBvalue\fP are compared as number. If \fBcolumn\fP type is text type such as \fBShortText\fP, \fBcolumn\fP value and \fBvalue\fP are compared as bit sequence. .sp It doesn\(aqt require the default match columns such as \fBfull text search condition\fP and \fBphrase search condition\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query n_likes:>=10 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is greater than or equal to \fB10\fP\&. .SS Combined expression .sp Here is available combined expression list. .SS Logical OR .sp Its syntax is \fBa OR b\fP\&. .sp \fBa\fP and \fBb\fP are conditional expressions, conbinded expressions or assignment expressions. .sp If at least one of \fBa\fP and \fBb\fP are matched, \fBa OR b\fP is matched. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aqn_likes:>10 OR content:@senna\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is greater than \fB10\fP or contain a word \fBsenna\fP in \fBcontent\fP column value. .SS Logical AND .sp Its syntax is \fBa + b\fP or just \fBa b\fP\&. .sp \fBa\fP and \fBb\fP are conditional expressions, conbinded expressions or assignment expressions. .sp If both \fBa\fP and \fBb\fP are matched, \fBa + b\fP is matched. .sp You can specify \fB+\fP the first expression such as \fB+a\fP\&. The \fB+\fP is just ignored. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aqn_likes:>=10 + content:@groonga\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is greater than or equal to \fB10\fP and contain a word \fBgroonga\fP in \fBcontent\fP column value. .SS Logical NOT .sp Its syntax is \fBa \- b\fP\&. .sp \fBa\fP and \fBb\fP are conditional expressions, conbinded expressions or assignment expressions. .sp If \fBa\fP is matched and \fBb\fP is not matched, \fBa \- b\fP is matched. .sp You can not specify \fB\-\fP the first expression such as \fB\-a\fP\&. It\(aqs syntax error. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aqn_likes:>=10 \- content:@groonga\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is greater than or equal to \fB10\fP and don\(aqt contain a word \fBgroonga\fP in \fBcontent\fP column value. .SS Grouping .sp Its syntax is \fB(...)\fP\&. \fB\&...\fP is space separated expression list. .sp \fB(...)\fP groups one ore more expressions and they can be processed as an expression. \fBa b OR c\fP means that \fBa\fP and \fBb\fP are matched or \fBc\fP is matched. \fBa (b OR c)\fP means that \fBa\fP and one of \fBb\fP and \fBc\fP are matched. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-query \(aqn_likes:<5 content:@senna OR content:@fast\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] select Entries \-\-query \(aqn_likes:<5 (content:@senna OR content:@fast)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The first expression doesn\(aqt use grouping. It matches records that \fBn_likes:<5\fP and \fBcontent:@senna\fP are matched or \fBcontent:@fast\fP is matched. .sp The second expression uses grouping. It matches records that \fBn_likes:<5\fP and one of \fBcontent:@senna\fP or \fBcontent:@fast\fP are matched. .SS Assignment expression .sp This section is for advanced users. Because assignment expression is disabled in \fB\-\-query\fP option of \fB/reference/commands/select\fP by default. You need to specify \fBALLOW_COLUMN|ALLOW_UPDATE\fP as \fB\-\-query_flags\fP option value to enable assignment expression. .sp Assignment expression in query syntax has some limitations. So you should use \fB/reference/grn_expr/script_syntax\fP instead of query syntax for assignment. .sp There is only one syntax for assignment expression. It\(aqs \fBcolumn:=value\fP\&. .sp \fBvalue\fP is assigend to \fBcolumn\fP\&. \fBvalue\fP is always processed as string in query syntax. \fBvalue\fP is casted to the type of \fBcolumn\fP automatically. It causes some limitations. For example, you cannot use boolean literal such as \fBtrue\fP and \fBfalse\fP for \fBBool\fP type column. You need to use empty string for \fBfalse\fP but query syntax doesn\(aqt support \fBcolumn:=\fP syntax. .sp See \fB/reference/cast\fP about cast. .SS Script syntax .sp Script syntax is a syntax to specify complex search condition. It is similar to ECMAScript. For example, \fB_key == "book"\fP means that groonga searches records that \fB_key\fP value is \fB"book"\fP\&. All values are string in \fBquery_syntax\fP but its own type in script syntax. For example, \fB"book"\fP is string, \fB1\fP is integer, \fBTokenBigram\fP is the object whose name is \fBTokenBigram\fP and so on. .sp Script syntax doesn\(aqt support full ECMAScript syntax. For example, script syntax doesn\(aqt support statement such as \fBif\fP control statement, \fBfor\fP iteration statement and variable definition statement. Function definion is not supported too. But script syntax addes the original additional operators. They are described after ECMAScript syntax is described. .SS Sample data .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Entries n_likes COLUMN_SCALAR UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Entries [ {"_key": "The first post!", "content": "Welcome! This is my first post!", "n_likes": 5}, {"_key": "Groonga", "content": "I started to use groonga. It\(aqs very fast!", "n_likes": 10}, {"_key": "Mroonga", "content": "I also started to use mroonga. It\(aqs also very fast! Really fast!", "n_likes": 15}, {"_key": "Good\-bye Senna", "content": "I migrated all Senna system!", "n_likes": 3}, {"_key": "Good\-bye Tritonn", "content": "I also migrated all Tritonn system!", "n_likes": 3} ] # [[0, 1337566253.89858, 0.000355720520019531], 5] .ft P .fi .UNINDENT .UNINDENT .sp There is a table, \fBEntries\fP, for blog entries. An entry has title, content and the number of likes for the entry. Title is key of \fBEntries\fP\&. Content is value of \fBEntries.content\fP column. The number of likes is value of \fBEntries.n_likes\fP column. .sp \fBEntries._key\fP column and \fBEntries.content\fP column are indexed using \fBTokenBigram\fP tokenizer. So both \fBEntries._key\fP and \fBEntries.content\fP are fulltext search ready. .sp OK. The schema and data for examples are ready. .SS Literals .SS Integer .sp Integer literal is sequence of \fB0\fP to \fB9\fP such as \fB1234567890\fP\&. \fB+\fP or \fB\-\fP can be prepended as sign such as \fB+29\fP and \fB\-29\fP\&. Integer literal must be decimal. Octal notation, hex and so on can\(aqt be used. .sp The maximum value of integer literal is \fB9223372036854775807\fP (\fB= 2 ** 63 \- 1\fP). The minimum value of integer literal is \fB\-9223372036854775808\fP (\fB= \-(2 ** 63)\fP). .SS Float .sp Float literal is sequence of \fB0\fP to \fB9\fP, \fB\&.\fP and \fB0\fP to \fB9\fP such as \fB3.14\fP\&. \fB+\fP or \fB\-\fP can be prepended as sign such as \fB+3.14\fP and \fB\-3.14\fP\&. \fB${RADIX}e${EXPORNENTIAL}\fP and \fB${RADIX}E${EXPORNENTIAL}\fP formats are also supported. For example, \fB314e\-2\fP is the same as \fB3.14\fP\&. .SS String .sp String literal is \fB"..."\fP\&. You need to escape \fB"\fP in literal by prepending \fB\e\e\(aq\(aq such as \(ga\(ga\e"\fP\&. For example, \fB"Say \e"Hello!\e"."\fP is a literal for \fBSay "Hello!".\fP string. .sp String encoding must be the same as encoding of database. The default encoding is UTF\-8. It can be changed by \fB\-\-with\-default\-encoding\fP configure option, \fB\-\-encodiong\fP \fB/reference/executables/groonga\fP option and so on. .SS Boolean .sp Boolean literal is \fBtrue\fP and \fBfalse\fP\&. \fBtrue\fP means true and \fBfalse\fP means false. .SS Null .sp Null literal is \fBnull\fP\&. Groonga doesn\(aqt support null value but null literal is supported. .SS Time .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is the groonga original notation. .UNINDENT .UNINDENT .sp Time literal doesn\(aqt exit. There are string time notation, integer time notation and float time notation. .sp String time notation is \fB"YYYY/MM/DD hh:mm:ss.uuuuuu"\fP or \fB"YYYY\-MM\-DD hh:mm:ss.uuuuuu"\fP\&. \fBYYYY\fP is year, \fBMM\fP is month, \fBDD\fP is day, \fBhh\fP is hour, \fBmm\fP is minute, \fBss\fP is second and \fBuuuuuu\fP is micro second. It is local time. For example, \fB"2012/07/23 02:41:10.436218"\fP is \fB2012\-07\-23T02:41:10.436218\fP in ISO 8601 format. .sp Integer time notation is the number of seconds that have elapsed since midnight UTC, January 1, 1970. It is also known as POSIX time. For example, \fB1343011270\fP is \fB2012\-07\-23T02:41:10Z\fP in ISO 8601 format. .sp Float time notation is the number of seconds and micro seconds that have elapsed since midnight UTC, January 1, 1970. For example, \fB1343011270.436218\fP is \fB2012\-07\-23T02:41:10.436218Z\fP in ISO 8601 format. .SS Geo point .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is the groonga original notation. .UNINDENT .UNINDENT .sp Geo point literal doesn\(aqt exist. There is string geo point notation. .sp String geo point notation has the following patterns: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB"LATITUDE_IN_MSECxLONGITUDE_IN_MSEC"\fP .IP \(bu 2 \fB"LATITUDE_IN_MSEC,LONGITUDE_IN_MSEC"\fP .IP \(bu 2 \fB"LATITUDE_IN_DEGREExLONGITUDE_IN_DEGREE"\fP .IP \(bu 2 \fB"LATITUDE_IN_DEGREE,LONGITUDE_IN_DEGREE"\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBx\fP and \fB,\fP can be used for separator. Latitude and longitude can be represented in milliseconds or degree. .SS Array .sp Array literal is \fB[element1, element2, ...]\fP\&. .SS Object literal .sp Object literal is \fB{name1: value1, name2: value2, ...}\fP\&. Groonga doesn\(aqt support object literal yet. .SS Control syntaxes .sp Script syntax doesn\(aqt support statement. So you cannot use control statement such as \fBif\fP\&. You can only use \fBA ? B : C\fP expression as control syntax. .sp \fBA ? B : C\fP returns \fBB\fP if \fBA\fP is true, \fBC\fP otherwise. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == (_id == 1 ? 5 : 3)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fB_id\fP column value is equal to \fB1\fP and \fBn_likes\fP column value is equal to \fB5\fP or \fB_id\fP column value is not equal to 1 and \fBn_likes\fP column value is equal to \fB3\fP\&. .SS Grouping .sp Its syntax is \fB(...)\fP\&. \fB\&...\fP is comma separated expression list. .sp \fB(...)\fP groups one ore more expressions and they can be processed as an expression. \fBa && b || c\fP means that \fBa\fP and \fBb\fP are matched or \fBc\fP is matched. \fBa && (b || c)\fP means that \fBa\fP and one of \fBb\fP and \fBc\fP are matched. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes < 5 && content @ "senna" || content @ "fast"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] select Entries \-\-filter \(aqn_likes < 5 && (content @ "senna" || content @ "fast")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The first expression doesn\(aqt use grouping. It matches records that \fBn_likes < 5\fP and \fBcontent @ "senna"\fP are matched or \fBcontent @ "fast"\fP is matched. .sp The second expression uses grouping. It matches records that \fBn_likes < 5\fP and one of \fBcontent @ "senna"\fP or \fBcontent @ "fast"\fP are matched. .SS Function call .sp Its syntax is \fBname(arugment1, argument2, ...)\fP\&. .sp \fBname(argument1, argument2, ...)\fP calls a function that is named \fBname\fP with arguments \fBargument1\fP, \fBargument2\fP and \fB\&...\fP\&. .sp See \fB/reference/function\fP for available functin list. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqedit_distance(_key, "Groonga") <= 1\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression uses \fB/reference/functions/edit_distance\fP\&. It matches records that \fB_key\fP column value is similar to \fB"Groonga"\fP\&. Similality of \fB"Groonga"\fP is computed as edit distance. If edit distance is less than or equal to 1, the value is treated as similar. In this case, \fB"Groonga"\fP and \fB"Mroonga"\fP are treated as similar. .SS Basic operators .sp Groonga supports operators defined in ECMAScript. .SS Arithmetic operators .sp Here are arithmetic operators. .SS Addition operator .sp Its syntax is \fBnumber1 + number2\fP\&. .sp The operator adds \fBnumber1\fP and \fBnumber2\fP and returns the result. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 10 + 5\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB15\fP (= \fB10 + 5\fP). .SS Subtraction operator .sp Its syntax is \fBnumber1 \- number2\fP\&. .sp The operator subtracts \fBnumber2\fP from \fBnumber1\fP and returns the result. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 20 \- 5\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB15\fP (= \fB20 \- 5\fP). .SS Multiplication operator .sp Its syntax is \fBnumber1 * number2\fP\&. .sp The operator multiplies \fBnumber1\fP and \fBnumber2\fP and returns the result. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 3 * 5\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB15\fP (= \fB3 * 5\fP). .SS Division operator .sp Its syntax is \fBnumber1 / number2\fP and \fBnumber1 % number2\fP\&. .sp The operator divides \fBnumber2\fP by \fBnumber1\fP\&. \fB/\fP returns the quotient of result. \fB%\fP returns the remainder of result. .sp Here is simple examples. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 26 / 7\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB3\fP (= \fB26 / 7\fP). .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 26 % 7\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP (= \fB26 % 7\fP). .SS Logical operators .sp Here are logical operators. .SS Logical NOT operator .sp Its syntax is \fB!condition\fP\&. .sp The operator inverts boolean value of \fBcondition\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aq!(n_likes == 5)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is not equal to \fB5\fP\&. .SS Logical AND operator .sp Its syntax is \fBcondition1 && condition2\fP\&. .sp The operator returns true if both of \fBcondition1\fP and \fBcondition2\fP are true, false otherwise. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent @ "fast" && n_likes >= 10\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBcontent\fP column value has the word \fBfast\fP and \fBn_likes\fP column value is greater or equal to \fB10\fP\&. .SS Logical OR operator .sp Its syntax is \fBcondition1 || condition2\fP\&. .sp The operator returns true if either \fBcondition1\fP or \fBcondition2\fP is true, false otherwise. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 5 || n_likes == 10\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP or \fB10\fP\&. .SS Logical AND NOT operator .sp Its syntax is \fBcondition1 &! condition2\fP\&. .sp The operator returns true if \fBcondition1\fP is true but \fBcondition2\fP is false, false otherwise. It returns difference set. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent @ "fast" &! content @ "mroonga"\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBcontent\fP column value has the word \fBfast\fP but doesn\(aqt have the word \fBmroonga\fP\&. .SS Bitwise operators .sp Here are bitwise operators. .SS Bitwise NOT operator .sp Its syntax is \fB~number\fP\&. .sp The operator returns bitwise NOT of \fBnumber\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aq~n_likes == \-6\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP because bitwise NOT of \fB5\fP is equal to \fB\-6\fP\&. .SS Bitwise AND operator .sp Its syntax is \fBnumber1 & number2\fP\&. .sp The operator returns bitwise AND between \fBnumber1\fP and \fBnumber2\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aq(n_likes & 1) == 1\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is even number because bitwise AND between an even number and \fB1\fP is equal to \fB1\fP and bitwise AND between an odd number and \fB1\fP is equal to \fB0\fP\&. .SS Bitwise OR operator .sp Its syntax is \fBnumber1 | number2\fP\&. .sp The operator returns bitwise OR between \fBnumber1\fP and \fBnumber2\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == (1 | 4)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP (= \fB1 | 4\fP). .SS Bitwise XOR operator .sp Its syntax is \fBnumber1 ^ number2\fP\&. .sp The operator returns bitwise XOR between \fBnumber1\fP and \fBnumber2\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == (10 ^ 15)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP (= \fB10 ^ 15\fP). .SS Shift operators .sp Here are shift operators. .SS Left shift operator .sp Its syntax is \fBnumber1 << number2\fP\&. .sp The operator performs a bitwise left shift operation on \fBnumber1\fP by \fBnumber2\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == (5 << 1)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB10\fP (= \fB5 << 1\fP). .SS Signed right shift operator .sp Its syntax is \fBnumber1 >> number2\fP\&. .sp The operator shifts bits of \fBnumber1\fP to right by \fBnumber2\fP\&. The sign of the result is the same as \fBnumber1\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == \-(\-10 >> 1)\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP (= \fB\-(\-10 >> 1)\fP = \fB\-(\-5)\fP). .SS Unsigned right shift operator .sp Its syntax is \fBnumber1 >>> number2\fP\&. .sp The operator shifts bits of \fBnumber1\fP to right by \fBnumber2\fP\&. The leftmost \fBnumber2\fP bits are filled by \fB0\fP\&. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == (2147483648 \- (\-10 >>> 1))\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP (= \fB2147483648 \- (\-10 >>> 1)\fP = \fB2147483648 \- 2147483643\fP). .SS Comparison operators .sp Here are comparison operators. .SS Equal operator .sp Its syntax is \fBobject1 == object2\fP\&. .sp The operator returns true if \fBobject1\fP equals to \fBobject2\fP, false otherwise. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes == 5\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 1, # "The first post!", # "Welcome! This is my first post!", # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is equal to \fB5\fP\&. .SS Not equal operator .sp Its syntax is \fBobject1 != object2\fP\&. .sp The operator returns true if \fBobject1\fP does not equal to \fBobject2\fP, false otherwise. .sp Here is a simple example. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqn_likes != 5\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 4 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "content", # "Text" # ], # [ # "n_likes", # "UInt32" # ] # ], # [ # 4, # "Good\-bye Senna", # "I migrated all Senna system!", # 3 # ], # [ # 5, # "Good\-bye Tritonn", # "I also migrated all Tritonn system!", # 3 # ], # [ # 2, # "Groonga", # "I started to use groonga. It\(aqs very fast!", # 10 # ], # [ # 3, # "Mroonga", # "I also started to use mroonga. It\(aqs also very fast! Really fast!", # 15 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that \fBn_likes\fP column value is not equal to \fB5\fP\&. .SS Less than operator .sp TODO: ... .SS Less than or equal to operator .sp TODO: ... .SS Greater than operator .sp TODO: ... .SS Greater than or equal to operator .sp TODO: ... .SS Assignment operators .SS Addition assignment operator .sp Its syntax is \fBcolumn1 += column2\fP\&. .sp The operator performs addition assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score += n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 4 # ], # [ # "Good\-bye Tritonn", # 3, # 4 # ], # [ # "Groonga", # 10, # 11 # ], # [ # "Mroonga", # 15, # 16 # ], # [ # "The first post!", # 5, # 6 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs addition assignment operation such as \(aq_score = _score + n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 + 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Subtraction assignment operator .sp Its syntax is \fBcolumn1 \-= column2\fP\&. .sp The operator performs subtraction assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score \-= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # \-2 # ], # [ # "Good\-bye Tritonn", # 3, # \-2 # ], # [ # "Groonga", # 10, # \-9 # ], # [ # "Mroonga", # 15, # \-14 # ], # [ # "The first post!", # 5, # \-4 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score \- n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 \- 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Multiplication assignment operator .sp Its syntax is \fBcolumn1 *= column2\fP\&. .sp The operator performs multiplication assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score *= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 3 # ], # [ # "Good\-bye Tritonn", # 3, # 3 # ], # [ # "Groonga", # 10, # 10 # ], # [ # "Mroonga", # 15, # 15 # ], # [ # "The first post!", # 5, # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score * n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 * 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Division assignment operator .sp Its syntax is \fBcolumn1 /= column2\fP\&. .sp The operator performs division assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score /= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 0 # ], # [ # "Good\-bye Tritonn", # 3, # 0 # ], # [ # "Groonga", # 10, # 0 # ], # [ # "Mroonga", # 15, # 0 # ], # [ # "The first post!", # 5, # 0 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score / n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 / 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Modulo assignment operator .sp Its syntax is \fBcolumn1 %= column2\fP\&. .sp The operator performs modulo assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score %= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 1 # ], # [ # "Good\-bye Tritonn", # 3, # 1 # ], # [ # "Groonga", # 10, # 1 # ], # [ # "Mroonga", # 15, # 1 # ], # [ # "The first post!", # 5, # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score % n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 % 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Bitwise left shift assignment operator .sp Its syntax is \fBcolumn1 <<= column2\fP\&. .sp The operator performs left shift assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score <<= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 8 # ], # [ # "Good\-bye Tritonn", # 3, # 8 # ], # [ # "Groonga", # 10, # 1024 # ], # [ # "Mroonga", # 15, # 32768 # ], # [ # "The first post!", # 5, # 32 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score << n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 << 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Bitwise signed right shift assignment operator .sp Its syntax is \fBcolumn2 >>= column2\fP\&. .sp The operator performs signed right shift assginment operation on column1 by column2. .SS Bitwise unsigned right shift assignment operator .sp Its syntax is \fBcolumn1 >>>= column2\fP\&. .sp The operator performs unsigned right shift assginment operation on column1 by column2. .SS Bitwise AND assignment operator .sp Its syntax is \fBcolumn1 &= column2\fP\&. .sp The operator performs bitwise AND assignment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score &= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 1 # ], # [ # "Good\-bye Tritonn", # 3, # 1 # ], # [ # "Groonga", # 10, # 0 # ], # [ # "Mroonga", # 15, # 1 # ], # [ # "The first post!", # 5, # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score & n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Groonga" as the \fB_key\fP is 10. .sp So the expression \fB1 & 10\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Bitwise OR assignment operator .sp Its syntax is \fBcolumn1 |= column2\fP\&. .sp The operator performs bitwise OR assignment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score |= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 3 # ], # [ # "Good\-bye Tritonn", # 3, # 3 # ], # [ # "Groonga", # 10, # 11 # ], # [ # "Mroonga", # 15, # 15 # ], # [ # "The first post!", # 5, # 5 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score | n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Groonga" as the \fB_key\fP is 10. .sp So the expression \fB1 | 10\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Bitwise XOR assignment operator .sp Its syntax is \fBcolumn1 ^= column2\fP\&. .sp The operator performs bitwise XOR assginment operation on column1 by column2. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns _key,n_likes,_score \-\-filter true \-\-scorer \(aq_score ^= n_likes\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "_key", # "ShortText" # ], # [ # "n_likes", # "UInt32" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Good\-bye Senna", # 3, # 2 # ], # [ # "Good\-bye Tritonn", # 3, # 2 # ], # [ # "Groonga", # 10, # 11 # ], # [ # "Mroonga", # 15, # 14 # ], # [ # "The first post!", # 5, # 4 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The value of \fB_score\fP by \fB\-\-filter\fP is always 1 in this case, then performs subtraction assignment operation such as \(aq_score = _score ^ n_likes\(aq for each records. .sp For example, the value of \fB_score\fP about the record which stores "Good\-bye Senna" as the \fB_key\fP is 3. .sp So the expression \fB1 ^ 3\fP is evaluated and stored to \fB_score\fP column as the execution result. .SS Original operators .sp Script syntax adds the original binary opearators to ECMAScript syntax. They operate search specific operations. They are starts with \fB@\fP or \fB*\fP\&. .SS Match operator .sp Its syntax is \fBcolumn @ value\fP\&. .sp The operator searches \fBvalue\fP by inverted index of \fBcolumn\fP\&. Normally, full text search is operated but tag search can be operated. Because tag search is also implemented by inverted index. .sp \fBquery_syntax\fP uses this operator by default. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent @ "fast"\(aq \-\-output_columns content # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "content", # "Text" # ] # ], # [ # "I started to use groonga. It\(aqs very fast!" # ], # [ # "I also started to use mroonga. It\(aqs also very fast! Really fast!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a word \fBfast\fP in \fBcontent\fP column value. .SS Prefix search operator .sp Its syntax is \fBcolumn @^ value\fP\&. .sp The operator does prefix search with \fBvalue\fP\&. Prefix search searches records that contain a word that starts with \fBvalue\fP\&. .sp You can use fast prefix search against a column. The column must be indexed and index table must be patricia trie table (\fBTABLE_PAT_KEY\fP) or double array trie table (\fBTABLE_DAT_KEY\fP). You can also use fast prefix search against \fB_key\fP pseudo column of patricia trie table or double array trie table. You don\(aqt need to index \fB_key\fP\&. .sp Prefix search can be used with other table types but it causes all records scan. It\(aqs not problem for small records but it spends more time for large records. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aq_key @^ "Goo"\(aq \-\-output_columns _key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "Good\-bye Tritonn" # ], # [ # "Good\-bye Senna" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that contain a word that starts with \fBGoo\fP in \fB_key\fP pseudo column value. \fBGood\-bye Senna\fP and \fBGood\-bye Tritonn\fP are matched with the expression. .SS Suffix search operator .sp Its syntax is \fBcolumn @$ value\fP\&. .sp This operator does suffix search with \fBvalue\fP\&. Suffix search searches records that contain a word that ends with \fBvalue\fP\&. .sp You can use fast suffix search against a column. The column must be indexed and index table must be patricia trie table (\fBTABLE_PAT_KEY\fP) with \fBKEY_WITH_SIS\fP flag. You can also use fast suffix search against \fB_key\fP pseudo column of patricia trie table (\fBTABLE_PAT_KEY\fP) with \fBKEY_WITH_SIS\fP flag. You don\(aqt need to index \fB_key\fP\&. We recommended that you use index column based fast suffix search instead of \fB_key\fP based fast suffix search. \fB_key\fP based fast suffix search returns automatically registered substrings. (TODO: write document about suffix search and link to it from here.) .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Fast suffix search can be used only for non\-ASCII characters such as hiragana in Japanese. You cannot use fast suffix search for ASCII character. .UNINDENT .UNINDENT .sp Suffix search can be used with other table types or patricia trie table without \fBKEY_WITH_SIS\fP flag but it causes all records scan. It\(aqs not problem for small records but it spends more time for large records. .sp Here is a simple exmaple. It uses fast suffix search for hiragana in Japanese that is one of non\-ASCII characters. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Titles TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Titles content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create SuffixSearchTerms TABLE_PAT_KEY|KEY_WITH_SIS ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create SuffixSearchTerms index COLUMN_INDEX Titles content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Titles [ {"content": "ぐるんが"}, {"content": "むるんが"}, {"content": "せな"}, {"content": "とりとん"} ] # [[0, 1337566253.89858, 0.000355720520019531], 4] select Titles \-\-query \(aqcontent:$んが\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "content", # "ShortText" # ] # ], # [ # 2, # "むるんが" # ], # [ # 1, # "ぐるんが" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that have value that ends with \fBんが\fP in \fBcontent\fP column value. \fBぐるんが\fP and \fBむるんが\fP are matched with the expression. .SS Near search operator .sp Its syntax is \fBcolumn *N "word1 word2 ..."\fP\&. .sp The operator does near search with words \fBword1 word2 ...\fP\&. Near search searches records that contain the words and the words are appeared in the near distance. Near distance is always \fB10\fP for now. The unit of near distance is the number of characters in N\-gram family tokenizers and the number of words in morphological analysis family tokenizers. .sp (TODO: Add a description about \fBTokenBigram\fP doesn\(aqt split ASCII only word into tokens. So the unit for ASCII words with \fBTokenBigram\fP is the number of words even if \fBTokenBigram\fP is a N\-gram family tokenizer.) .sp Note that an index column for full text search must be defined for \fBcolumn\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent *N "I fast"\(aq \-\-output_columns content # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "content", # "Text" # ] # ], # [ # "I started to use groonga. It\(aqs very fast!" # ] # ] # ] # ] select Entries \-\-filter \(aqcontent *N "I Really"\(aq \-\-output_columns content # [[0, 1337566253.89858, 0.000355720520019531], [[[0], [["content", "Text"]]]]] select Entries \-\-filter \(aqcontent *N "also Really"\(aq \-\-output_columns content # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "content", # "Text" # ] # ], # [ # "I also started to use mroonga. It\(aqs also very fast! Really fast!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The first expression matches records that contain \fBI\fP and \fBfast\fP and the near distance of those words are in 10 words. So the record that its content is \fBI also started to use mroonga. It\(aqs also very fast! ...\fP is matched. The number of words between \fBI\fP and \fBfast\fP is just 10. .sp The second expression matches records that contain \fBI\fP and \fBReally\fP and the near distance of those words are in 10 words. So the record that its content is \fBI also started to use mroonga. It\(aqs also very fast! Really fast!\fP is not matched. The number of words between \fBI\fP and \fBReally\fP is 11. .sp The third expression matches records that contain \fBalso\fP and \fBReally\fP and the near distance of those words are in 10 words. So the record that its content is \fBI also st arted to use mroonga. It\(aqs also very fast! Really fast!\fP is matched. The number of words between \fBalso\fP and \fBReally\fP is 10. .SS Similar search .sp Its syntax is \fBcolumn *S "document"\fP\&. .sp The operator does similar search with document \fBdocument\fP\&. Similar search searches records that have similar content to \fBdocument\fP\&. .sp Note that an index column for full text search must be defined for \fBcolumn\fP\&. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-filter \(aqcontent *S "I migrated all Solr system!"\(aq \-\-output_columns content # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "content", # "Text" # ] # ], # [ # "I migrated all Senna system!" # ], # [ # "I also migrated all Tritonn system!" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression matches records that have similar content to \fBI migrated all Solr system!\fP\&. In this case, records that have \fBI migrated all XXX system!\fP content are matched. .SS Term extract operator .sp Its syntax is \fB_key *T "document"\fP\&. .sp The operator extracts terms from \fBdocument\fP\&. Terms must be registered as keys of the table of \fB_key\fP\&. .sp Note that the table must be patricia trie (\fBTABLE_PAT_KEY\fP) or double array trie (\fBTABLE_DAT_KEY\fP). You can\(aqt use hash table (\fBTABLE_HASH_KEY\fP) and array (\fBTABLE_NO_KEY\fP) because they don\(aqt support longest common prefix search. Longest common prefix search is used to implement the operator. .sp Here is a simple exmaple. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Words TABLE_PAT_KEY|KEY_NORMALIZE ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Words [ {"_key": "groonga"}, {"_key": "mroonga"}, {"_key": "Senna"}, {"_key": "Tritonn"} ] # [[0, 1337566253.89858, 0.000355720520019531], 4] select Words \-\-filter \(aq_key *T "Groonga is the successor project to Senna."\(aq \-\-output_columns _key # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "groonga" # ], # [ # "senna" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The expression extrcts terms that included in document \fBGroonga is the successor project to Senna.\fP\&. In this case, \fBKEY_NORMALIZE\fP flag is specified to \fBWords\fP\&. So \fBGroonga\fP can be extracted even if it is loaded as \fBgroonga\fP into \fBWords\fP\&. All of extracted terms are also normalized. .SS See also .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB/reference/api/grn_expr\fP: grn_expr related APIs .UNINDENT .UNINDENT .UNINDENT .SS Function .sp Function can be used in some commands. For example, you can use function in \fB\-\-filter\fP, \fB\-\-scorer\fP and \fBoutput_columns\fP options of \fBcommands/select\fP\&. .sp This section describes about function and built\-in functions. .sp TODO: Add documentations about function. .SS between .SS Summary .sp \fBbetween\fP is used for checking the specified value exists in the specific range. It is often used for combination with \fIselect\-filter\fP option in \fB/reference/commands/select\fP\&. .SS Syntax .sp \fBbetween\fP has five parameters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C between(column_or_value, min, min_border, max, max_border) .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Users TABLE_HASH_KEY ShortText column_create Users age COLUMN_SCALAR Int32 table_create Ages TABLE_HASH_KEY Int32 column_create Ages user_age COLUMN_INDEX Users age load \-\-table Users [ {"_key": "Alice", "age": 12}, {"_key": "Bob", "age": 13}, {"_key": "Calros", "age": 15}, {"_key": "Dave", "age": 16}, {"_key": "Eric", "age": 20} {"_key": "Frank", "age": 21} ] .ft P .fi .UNINDENT .UNINDENT .sp Here is the query to show the persons to match PG\-13 rating (MPAA). .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Users \-\-filter \(aqbetween(age, 13, "include", 16, "include")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 3 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "age", # "Int32" # ] # ], # [ # 2, # "Bob", # 13 # ], # [ # 3, # "Calros", # 15 # ], # [ # 4, # "Dave", # 16 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp It returns 13, 14, 15 and 16 years old users. .sp \fBbetween\fP function accepts not only a column of table, but also the value. .sp If you specify the value as 1st parameter, it is checked whether the value is included or not. if it matches to the specified range, it returns the all records because \fBbetween\fP function returns true. .sp If it doesn\(aqt match to the specified range, it returns no records because \fBbetween\fP function returns false. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Users \-\-filter \(aqbetween(14, 13, "include", 16, "include")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 6 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "_key", # "ShortText" # ], # [ # "age", # "Int32" # ] # ], # [ # 1, # "Alice", # 12 # ], # [ # 2, # "Bob", # 13 # ], # [ # 3, # "Calros", # 15 # ], # [ # 4, # "Dave", # 16 # ], # [ # 5, # "Eric", # 20 # ], # [ # 6, # "Frank", # 21 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp In the above case, it returns all the records, because 14 exists in between 13 and 16. This behavior is used for checking the specified value exists or not in the table. .SS Parameters .sp There are five required parameters, \fBcolumn_or_value\fP, and \fBmin\fP, \fBmin_border\fP, \fBmax\fP and \fBmax_border\fP\&. .SS \fBcolumn_or_value\fP .sp It specifies a column of the table or the value. .SS \fBmin\fP .sp It specifies the minimal border value of the range. You can control the behavior that the value of \fBmax\fP is included or excluded by \fBmax_border\fP parameter. .SS \fBmin_border\fP .sp It specifies whether the specified range contains the value of \fBmin\fP or not. The value of \fBmin_border\fP are either "include" or "exclude". If it is "include", \fBmin\fP value is included. If it is "exclude", \fBmin\fP value is not included. .SS \fBmax\fP .sp It specifies the maximum border value of the range. You can control the behavior that the value of \fBmax\fP is included or excluded by \fBmax_border\fP parameter. .SS \fBmax_border\fP .sp It specifies whether the specified range contains the value of \fBmax\fP or not. The value of \fBmax_border\fP are either "include" or "exclude". If it is "include", \fBmax\fP value is included. If it is "exclude", \fBmax\fP value is not included. .SS Return value .sp \fBbetween\fP returns whether the value of column exists in specified the value of range or not. If record is matched to specified the value of range, it returns true. Otherwise, it returns false. .SS edit_distance .SS 名前 .sp edit_distance \- 指定した2つの文字列の編集距離を計算する .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C edit_distance(string1, string2) .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groonga組込関数の一つであるedit_distanceについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp edit_distance() 関数は、string1に指定した文字列とstring2に指定した文字列の間の編集距離を求めます。 .SS 引数 .sp \fBstring1\fP .INDENT 0.0 .INDENT 3.5 文字列を指定します .UNINDENT .UNINDENT .sp \fBstring2\fP .INDENT 0.0 .INDENT 3.5 もうひとつの文字列を指定します .UNINDENT .UNINDENT .SS 返値 .sp 指定した2つ文字列の編集距離をUint32型の値として返します。 .SS 例 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C edit_distance(title, "hoge") 1 .ft P .fi .UNINDENT .UNINDENT .SS geo_distance .SS Summary .sp \fBgeo_distance\fP calculates the value of distance between specified two points. .SS Syntax .sp \fBgeo_distance\fP requires two point. The parameter \fBapproximate_type\fP is optional: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C geo_distance(point1, point2) geo_distance(point1, point2, approximate_type) .ft P .fi .UNINDENT .UNINDENT .sp The default value of \fBapproximate_type\fP is \fB"rectangle"\fP\&. If you omit \fBapproximate_type\fP, \fBgeo_distance\fP calculates the value of distance as if \fB"rectangle"\fP was specified. .SS Usage .sp \fBgeo_distance\fP is one of the Groonga builtin functions. .sp You can call a builtin function in \fB/reference/grn_expr\fP .sp \fBgeo_distance\fP function calculates the value of distance (approximate value) between the coordinate of \fBpoint1\fP and the coordinate of \fBpoint2\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Groonga provides three built in functions for calculating the value of distance. There are \fBgeo_distance()\fP, \fBgeo_distance2()\fP and \fBgeo_distance3()\fP\&. The difference of them is the algorithm of calculating distance. \fBgeo_distance2()\fP and \fBgeo_distance3()\fP were deprecated since version 1.2.9. Use \fBgeo_distance(point1, point2, "sphere")\fP instead of \fBgeo_distance2(point1, point2)\fP\&. Use \fBgeo_distance(point1, point2, "ellipsoid")\fP instead of \fBgeo_distance3(point1, point2)\fP\&. .UNINDENT .UNINDENT .sp Lets\(aqs learn about \fBgeo_distance\fP usage with examples. This section shows simple usages. .sp Here are two schema definition and sample data to show the difference according to the usage. Those samples show how to calculate the value of distance between New York City and London. .INDENT 0.0 .IP 1. 3 Using the column value of location for calculating the distance (\fBCities\fP table) .IP 2. 3 Using the explicitly specified coordinates for calculating the distance (\fBGeo\fP table) .UNINDENT .SS Using the column value of location .sp Here are a schema definition of \fBCities\fP table and sample data to show usage. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Cities TABLE_HASH_KEY ShortText column_create Cities location COLUMN_SCALAR WGS84GeoPoint load \-\-table Cities [ { "_key", "location" }, { "New York City", "146566000x\-266422000", }, ] .ft P .fi .UNINDENT .UNINDENT .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Cities TABLE_HASH_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Cities location COLUMN_SCALAR WGS84GeoPoint # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Cities [ { "_key", "location" }, { "New York City", "146566000x\-266422000", }, ] # [[0, 1337566253.89858, 0.000355720520019531], 1] .ft P .fi .UNINDENT .UNINDENT .sp This execution example creates a table named \fBCities\fP which has one column named \fBlocation\fP\&. \fBlocation\fP column stores the value of coordinate. The coordinate of Tokyo is stored as sample data. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Cities \-\-output_columns _score \-\-filter 1 \-\-scorer \(aq_score = geo_distance(location, "185428000x\-461000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_score", # "Int32" # ] # ], # [ # 5715104 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This sample shows that \fBgeo_distance\fP use the value of \fBlocation\fP column and the value of coordinate to calculate distance. .sp The value ("185428000x\-461000") passed to \fBgeo_distance\fP as the second argument is the coordinate of London. .SS Using the explicitly specified value of location .sp Here are a schema definition of \fBGeo\fP table and sample data to show usage. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Geo TABLE_HASH_KEY ShortText column_create Geo distance COLUMN_SCALAR Int32 load \-\-table Geo [ { "_key": "the record for geo_distance() result" } ] .ft P .fi .UNINDENT .UNINDENT .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Geo TABLE_HASH_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Geo distance COLUMN_SCALAR Int32 # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Geo [ { "_key": "the record for geo_distance() result" } ] # [[0, 1337566253.89858, 0.000355720520019531], 1] .ft P .fi .UNINDENT .UNINDENT .sp This execution example creates a table named \fBGeo\fP which has one column named \fBdistance\fP\&. \fBdistance\fP column stores the value of distance. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Geo \-\-output_columns distance \-\-scorer \(aqdistance = geo_distance("146566000x\-266422000", "185428000x\-461000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "distance", # "Int32" # ] # ], # [ # 5807750 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This sample shows that \fBgeo_distance\fP use the coordinate of London and the coordinate of New York to calculate distance. .SS Parameters .SS Required parameter .sp There are two required parameter, \fBpoint1\fP and \fBpoint2\fP\&. .SS \fBpoint1\fP .sp It specifies the start point that you want to calculate the value of distance between two points. .sp You can specify the value of GeoPoint type. [1] .sp See \fB/reference/types\fP about GeoPoint. .SS \fBpoint2\fP .sp It specifies the end point that you want to calculate the value of distance between two points. .sp You can specify the value of GeoPoint type or the string indicating the coordinate. .sp See \fB/reference/types\fP about GeoPoint and the coordinate. .SS Optional parameter .sp There is a optional parameter, \fBapproximate_type\fP\&. .SS \fBapproximate_type\fP .sp It specifies how to approximate the geographical features for calculating the value of distance. .sp You can specify the value of \fBapproximate_type\fP by one of the followings. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBrectangle\fP .IP \(bu 2 \fBsphere\fP .IP \(bu 2 \fBellipsoid\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is a limitation about \fBgeo_distance\fP\&. \fBgeo_distance\fP can not calculate the value of distance between two points across meridian, equator or the date line if you use \fBsphere\fP or \fBellipsoid\fP as approximate type. There is not such a limitation for \fBrectangle\fP\&. This is temporary limitation according to the implementation of Groonga, but it will be fixed in the future release. .UNINDENT .UNINDENT .SS \fBrectangle\fP .sp This parameter require to approximate the geographical features by square approximation for calculating the distance. .sp Since the value of distance is calculated by simple formula, you can calculate the value of distance fast. But, the error of distance increases as it approaches the pole. .sp You can also specify \fBrect\fP as abbrev expression. .sp Here is a sample about calculating the value of distance with column value. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Cities \-\-output_columns _score \-\-filter 1 \-\-scorer \(aq_score = geo_distance(location, "185428000x\-461000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_score", # "Int32" # ] # ], # [ # 5715104 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Here is a sample about calculating the value of distance with explicitly specified point. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Geo \-\-output_columns distance \-\-scorer \(aqdistance = geo_distance("146566000x\-266422000", "185428000x\-461000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "distance", # "Int32" # ] # ], # [ # 5807750 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp Here are samples about calculating the value of distance with explicitly specified point across meridian, equator, the date line. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Geo \-\-output_columns distance \-\-scorer \(aqdistance = geo_distance("175904000x8464000", "145508000x\-13291000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "distance", # "Int32" # ] # ], # [ # 1051293 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This sample shows the value of distance across meridian. The return value of \fBgeo_distance("175904000x8464000", "145508000x\-13291000", "rectangle")\fP is the value of distance from Paris, Flance to Madrid, Spain. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Geo \-\-output_columns distance \-\-scorer \(aqdistance = geo_distance("146566000x\-266422000", "\-56880000x\-172310000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "distance", # "Int32" # ] # ], # [ # 6880439 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This sample shows the value of distance across equator. The return value of \fBgeo_distance("146566000x\-266422000", "\-56880000x\-172310000", "rectangle")\fP is the value of distance from New York, The United Status to Brasillia, Brasil. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Geo \-\-output_columns distance \-\-scorer \(aqdistance = geo_distance("143660000x419009000", "135960000x\-440760000", "rectangle")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "distance", # "Int32" # ] # ], # [ # 10475205 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp This sample shows the value of distance across the date line. The return value of \fBgeo_distance("143660000x419009000", "135960000x\-440760000", "rectangle")\fP is the value of distance from Beijin, China to San Francisco, The United States. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgeo_distance\fP uses square approximation as default. If you omit \fBapproximate_type\fP, \fBgeo_distance\fP behaves like \fBrectangle\fP was specified. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgeo_distance\fP accepts the string indicating the coordinate as the value of \fBpoint1\fP when the value of \fBapproximate_type\fP is \fB"rectangle"\fP\&. If you specified the string indicating the coordinate as the value of \fBpoint1\fP with \fBsphere\fP or \fBellipsoid\fP, \fBgeo_distance\fP returns 0 as the value of distance. .UNINDENT .UNINDENT .SS \fBsphere\fP .sp This parameter require to approximate the geographical features by spherical approximation for calculating the distance. .sp It is slower than \fBrectangle\fP, but the error of distance becomes smaller than \fBrectangle\fP\&. .sp You can also specify \fBsphr\fP as abbrev expression. .sp Here is a sample about calculating the value of distance with column value. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Cities \-\-output_columns _score \-\-filter 1 \-\-scorer \(aq_score = geo_distance(location, "185428000x\-461000", "sphere")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_score", # "Int32" # ] # ], # [ # 5715102 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS \fBellipsoid\fP .sp This parameter require to approximate the geographical features by ellipsoid approximation for calculating the distance. .sp It uses the calculation of distance by the formula of Hubeny. It is slower than \fBsphere\fP, but the error of distance becomes smaller than \fBsphere\fP\&. .sp You can also specify \fBellip\fP as abbrev expression. .sp Here is a sample about calculating the value of distance with column value. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Cities \-\-output_columns _score \-\-filter 1 \-\-scorer \(aq_score = geo_distance(location, "185428000x\-461000", "ellipsoid")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_score", # "Int32" # ] # ], # [ # 5706263 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Return value .sp \fBgeo_distance\fP returns the value of distance in float type. The unit of return value is meter. Footnote .IP [1] 5 You can specify whether TokyoGeoPoint or WGS84GeoPoint. .SS geo_in_circle .SS 名前 .sp geo_in_circle \- 座標が円の範囲内に存在するかどうかを調べます。 .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C geo_in_circle(point, center, radious_or_point[, approximate_type]) .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groonga組込関数の一つであるgeo_in_circleについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp geo_in_circle() 関数は、pointに指定した座標が、centerに指定した座標を中心とする円の範囲内にあるかどうかを調べます。 .SS 引数 .sp \fBpoint\fP .INDENT 0.0 .INDENT 3.5 円の範囲内に存在するかどうかを調べる座標を指定します。Point型の値を指定できます。 [1] .UNINDENT .UNINDENT .sp \fBcenter\fP .INDENT 0.0 .INDENT 3.5 円の中心となる座標を指定します。Point型の値、あるいは座標を示す文字列を指定できます。 .UNINDENT .UNINDENT .sp \fBradious_or_point\fP .INDENT 0.0 .INDENT 3.5 円の半径を指定します。数値を指定した場合には、半径(単位:メートル)が指定されたものとみなします。 Point型の値、あるいは座標を示す文字列を指定した場合は、円周上の点の一つの座標が指定されたものとみなします。 .UNINDENT .UNINDENT .sp \fBapproximate_type\fP .INDENT 0.0 .INDENT 3.5 半径からの距離を求めるために地形をどのように近似するかを指定します。指定できる値は以下の通りです。 .sp \fB"rectangle"\fP .INDENT 0.0 .INDENT 3.5 方形近似で近似します。単純な計算式で距離を求めることができるため高速ですが、極付近では誤差が大きくなります。 .sp \fB"rect"\fP と省略して指定することもできます。 .sp この近似方法がデフォルト値です。 \fBapproximate_type\fP を省略した場合は方形近似になります。 .UNINDENT .UNINDENT .sp \fB"sphere"\fP .INDENT 0.0 .INDENT 3.5 球面近似で近似します。 \fB"rectangle"\fP よりも遅くなりますが、誤差は小さいです。 .sp \fB"sphr"\fP と省略して指定することもできます。 .UNINDENT .UNINDENT .sp \fB"ellipsoid"\fP .INDENT 0.0 .INDENT 3.5 楕円体近似で近似します。距離の計算にはヒュベニの距離計算式を用います。 \fB"sphere"\fP よりも遅くなりますが、誤差は小さくなります。 .sp \fB"ellip"\fP と省略して指定することもできます。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS 返値 .sp pointに指定した座標が円の範囲内にあるかどうかをBool型の値で返します。 .SS 例 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C geo_in_circle(pos, "100x100", 100) true .ft P .fi .UNINDENT .UNINDENT 脚注 .IP [1] 5 TokyoGeoPoint(日本測地系座標)かWGS84GeoPoint(世界測地系座標)のいずれかを指定できます。 .SS geo_in_rectangle .SS 名前 .sp geo_in_rectangle \- 座標が矩形の範囲内に存在するかどうかを調べます。 .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C geo_in_rectangle(point, top_left, bottom_right) .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groonga組込関数の一つであるgeo_in_rectangleについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp geo_in_rectangle() 関数は、pointに指定した座標が、top_leftとbottom_rightがなす矩形の範囲内にあるかどうかを調べます。 .SS 引数 .sp \fBpoint\fP .INDENT 0.0 .INDENT 3.5 矩形の範囲内に存在するかどうかを調べる座標を指定します。Point型の値を指定できます。 [1] .UNINDENT .UNINDENT .sp \fBtop_left\fP .INDENT 0.0 .INDENT 3.5 矩形の左上隅となる座標を指定します。Point型の値、あるいは座標を示す文字列を指定できます。 .UNINDENT .UNINDENT .sp \fBbottom_right\fP .INDENT 0.0 .INDENT 3.5 矩形の右下隅となる座標を指定します。Point型の値、あるいは座標を示す文字列を指定できます。 .UNINDENT .UNINDENT .SS 返値 .sp pointに指定した座標が矩形の範囲内にあるかどうかをBool型の値で返します。 .SS 例 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C geo_in_rectangle(pos, "150x100", "100x150") true .ft P .fi .UNINDENT .UNINDENT 脚注 .IP [1] 5 TokyoGeoPoint(日本測地系座標)かWGS84GeoPoint(世界測地系座標)のいずれかを指定できます。 .SS highlight_full .sp \fBCAUTION:\fP .INDENT 0.0 .INDENT 3.5 This feature is experimental. API will be changed. .UNINDENT .UNINDENT .SS Summary .sp \fBhighlight_full\fP tags target text. It can use to highlight the search keyword. It can specify use/not use HTML escape, the normalizer name and change the tag for each keyword. .SS Syntax .sp \fBhighlight_full\fP has required parameter and optional parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C highlight_full(column, normalizer_name, use_html_escape, keyword1, open_tag1, close_tag1, ... [keywordN, open_tagN, close_tagN]) .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_NO_KEY # [[0,1407692435.35498,0.0364797115325928],true] column_create Entries body COLUMN_SCALAR ShortText # [[0,1407692435.39156,0.0256640911102295],true] table_create Terms TABLE_PAT_KEY ShortText \-\-default_tokenizer TokenBigram \-\-normalizer NormalizerAuto # [[0,1407692435.423,0.0274741649627686],true] column_create Terms document_index COLUMN_INDEX|WITH_POSITION Entries body # [[0,1407692435.45051,0.0534985065460205],true] load \-\-table Entries [ {"body": "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. Rroonga is a Ruby binding of Groonga."} ] # [[0,1407692435.50406,0.378907442092896],1] .ft P .fi .UNINDENT .UNINDENT .sp \fBhighlight_full\fP can be used in only \fB\-\-output_columns\fP in \fB/reference/commands/select\fP\&. .sp \fBhighlight_full\fP requires Groonga 4.0.5 or later. .sp \fBhighlight_full\fP requires \fB/reference/command/command_version\fP 2 or later. .sp The following example uses HTML escape and normalzier is \fBNormalizeAuto\fP\&. It specifies the tags \fB\fP and \fB\fP of the keyword \fBgroonga\fP, and the tags \fB\fP and \fB\fP of the keyword \fBmysql\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \(aqhighlight_full(body, "NormalizerAuto", true, "Groonga", "", "", "mysql", "", "")\(aq \-\-command_version 2 # [ # [ # 0, # 1407695996.52987, # 0.00151872634887695 # ], # [ # [ # [ # 1 # ], # [ # [ # "highlight_full", # "null" # ] # ], # [ # "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The text are scanned by the keywords for tagging after they are normalized by \fBNormalizerAuto\fP normalizer. .sp \fB\-\-query "groonga mysql"\fP matches to the first record\(aqs body. \fBhighight_full\fP surrounds the keywords \fBgroonga\fP contained in the text with \fB\fP and \fB\fP, and the keywords \fBmysql\fP contained in the text with with \fB\fP and \fB\fP\&. .sp Special characters such as \fB<\fP and \fB>\fP are escapsed as \fB<\fP and \fB>\fP\&. .sp You can specify string literal instead of column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \(aqhighlight_full("Groonga is very fast fulltext search engine.", "NormalizerAuto", true, "Groonga", "", "", "mysql", "", "")\(aq \-\-command_version 2 \-\-match_columns body \-\-query "groonga" # [ # [ # 0, # 1407696157.1849, # 0.00164437294006348 # ], # [ # [ # [ # 1 # ], # [ # [ # "highlight_full", # "null" # ] # ], # [ # "Groonga is very fast fulltext search engine." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp There are three required parameters, \fBcolumn\fP, \fBnormalizer_name\fP and \fBuse_html_escape\fP\&. There are three or over optional parameters, \fBkeywordN\fP, \fBopen_tagN\fP and \fBend_tagN\fP\&. .SS \fBcolumn\fP .sp It specifies a column of the table. .SS \fBnormalizer_name\fP .sp It specifies a normalizer name. .SS \fBuse_html_escape\fP .sp It specifies use or not use HTML escape. If it is \fBtrue\fP , use HTML escape. If it is \fBfalse\fP , not use HTML escape. .SS \fBkeywordN\fP .sp It specifies a keyword for tagging. You can specify multiple keywords for each three arguments. .SS \fBopen_tagN\fP .sp It specifies a open tag. You can specify multiple open tags for each three arguments. .SS \fBclose_tagN\fP .sp It specifies a close tag. You can specify multiple close tags for each three arguments. .SS Return value .sp \fBhighlight_full\fP returns a tagged string or \fBnull\fP\&. If \fBhighlight_full\fP can\(aqt find any keywords, it returns \fBnull\fP\&. .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/select\fP .IP \(bu 2 \fB/reference/functions/highlight_html\fP .UNINDENT .SS highlight_html .sp \fBCAUTION:\fP .INDENT 0.0 .INDENT 3.5 This feature is experimental. API will be changed. .UNINDENT .UNINDENT .SS Summary .sp \fBhighlight_html\fP tags target text. It can use to highlight the search keywords. The tagged text are prepared for embedding HTML. Special characters such as \fB<\fP and \fB>\fP are escapsed as \fB<\fP and \fB>\fP\&. Keyword is surrounded with \fB\fP and \fB\fP\&. For example, a tagged text of \fBI am a groonga user. <3\fP for keyword \fBgroonga\fP is \fBI am a groonga user. <3\fP\&. .SS Syntax .sp \fBhighlight_html\fP has only one parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C highlight_html(column) .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_NO_KEY # [[0,1407692435.35498,0.0364797115325928],true] column_create Entries body COLUMN_SCALAR ShortText # [[0,1407692435.39156,0.0256640911102295],true] table_create Terms TABLE_PAT_KEY ShortText \-\-default_tokenizer TokenBigram \-\-normalizer NormalizerAuto # [[0,1407692435.423,0.0274741649627686],true] column_create Terms document_index COLUMN_INDEX|WITH_POSITION Entries body # [[0,1407692435.45051,0.0534985065460205],true] load \-\-table Entries [ {"body": "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. Rroonga is a Ruby binding of Groonga."} ] # [[0,1407692435.50406,0.378907442092896],1] .ft P .fi .UNINDENT .UNINDENT .sp \fBhighlight_html\fP can be used in only \fB\-\-output_columns\fP in \fB/reference/commands/select\fP\&. .sp \fBhighlight_html\fP requires Groonga 4.0.5 or later. .sp \fBhighlight_html\fP requires \fB/reference/command/command_version\fP 2 or later. .sp You also need to specify \fB\-\-query\fP and/or \fB\-\-filter\fP\&. Keywords are extracted from \fB\-\-query\fP and \fB\-\-filter\fP arguments. .sp The following example uses \fB\-\-query "groonga mysql"\fP\&. In this case, \fBgroonga\fP and \fBmysql\fP are used as keywords. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \-\-match_columns body \-\-query \(aqgroonga mysql\(aq \-\-output_columns \(aqhighlight_html(body)\(aq \-\-command_version 2 # [ # [ # 0, # 1407692444.86092, # 0.00188779830932617 # ], # [ # [ # [ # 1 # ], # [ # [ # "highlight_html", # "null" # ] # ], # [ # "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp The text are scanned by the keywords for tagging after they are normalized by \fBNormalizerAuto\fP normalizer. .sp \fB\-\-query "groonga mysql"\fP matches to only the first record\(aqs body. \fBhighlight_html(body)\fP surrounds the keywords \fBgroonga\fP or \fBmysql\fP contained in the text with \fB\fP and \fB\fP\&. .sp You can specify string literal instead of column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Entries \-\-output_columns \(aqhighlight_html("Groonga is very fast fulltext search engine.")\(aq \-\-command_version 2 \-\-match_columns body \-\-query "groonga" # [ # [ # 0, # 1407693081.99183, # 0.000126123428344727 # ], # [ # [ # [ # 1 # ], # [ # [ # "highlight_html", # "null" # ] # ], # [ # "Groonga is very fast fulltext search engine." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Parameters .sp There is only one parameter \fBcolumn\fP . .SS \fBcolumn\fP .sp It specifies a column of the table. .SS Return value .sp \fBhighlight_html\fP returns a tagged string or \fBnull\fP\&. If \fBhighlight_html\fP can\(aqt find any keywords, it returns \fBnull\fP\&. .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/select\fP .IP \(bu 2 \fB/reference/functions/highlight_full\fP .UNINDENT .SS html_untag .SS Summary .sp \fBhtml_untag\fP strips HTML tags from HTML and outputs plain text. .sp \fBhtml_untag\fP is used in \fB\-\-output_columns\fP described at \fIoutput_columns\fP\&. .SS Syntax .sp \fBhtml_untag\fP requires only one argument. It is \fBhtml\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C html_untag(html) .ft P .fi .UNINDENT .UNINDENT .SS Requirements .sp \fBhtml_untag\fP requires Groonga 3.0.5 or later. .sp \fBhtml_untag\fP requires \fB/reference/command/command_version\fP 2 or later. .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Sample schema: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create WebClips TABLE_HASH_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create WebClips content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Sample data: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table WebClips [ {"_key": "http://groonga.org", "content": "groonga is fast"}, {"_key": "http://mroonga.org", "content": "mroonga is fast"}, ] # [[0, 1337566253.89858, 0.000355720520019531], 2] .ft P .fi .UNINDENT .UNINDENT .sp Here is the simple usage of \fBhtml_untag\fP function which strips HTML tags from content of column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select WebClips \-\-output_columns "html_untag(content)" \-\-command_version 2 # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "html_untag", # "null" # ] # ], # [ # "groonga is fast" # ], # [ # "mroonga is fast" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp When executing the above query, you can see "span" tag with "class" attribute is stripped. Note that you must specify \fB\-\-command_version 2\fP to use \fBhtml_untag\fP function. .SS Parameters .sp There is one required parameter, \fBhtml\fP\&. .SS \fBhtml\fP .sp It specifies HTML text to be untagged. .SS Return value .sp \fBhtml_untag\fP returns plain text which is stripped HTML tags from HTML text. .SS now .SS 名前 .sp now \- 現在時刻を返す .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C now() .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groonga組込関数の一つであるnowについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp now() 関数は現在時刻に対応するTime型の値を返します。 .SS 返値 .sp 現在時刻に対応するTime型のオブジェクトを返します。 .SS 例 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C now() 1256791194.55541 .ft P .fi .UNINDENT .UNINDENT .SS query .SS Summary .sp \fBquery\fP provides \fB\-\-match_columns\fP and \fB\-\-query\fP parameters of \fB/reference/commands/select\fP feature as function. You can specify multiple \fBquery\fP functions in \fB\-\-filter\fP parameter in \fB/reference/commands/select\fP\&. .sp Because of such flexibility, you can control full text search behavior by combination of multiple \fBquery\fP functions. .sp \fBquery\fP can be used in only \fB\-\-filter\fP in \fB/reference/commands/select\fP\&. .SS Syntax .sp \fBquery\fP requires two arguments \- \fBmatch_columns\fP and \fBquery_string\fP\&. .sp The parameter \fBquery_expander\fP or \fBsubstitution_table\fP is optional. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C query(match_columns, query_string) query(match_columns, query_string, query_expander) query(match_columns, query_string, substitution_table) .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Sample schema: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Documents TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Documents content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms documents_content_index COLUMN_INDEX|WITH_POSITION Documents content # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Users TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users name COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Users memo COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Lexicon TABLE_HASH_KEY ShortText \e \-\-default_tokenizer TokenBigramSplitSymbolAlphaDigit \e \-\-normalizer NormalizerAuto column_create Lexicon users_name COLUMN_INDEX|WITH_POSITION Users name # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon users_memo COLUMN_INDEX|WITH_POSITION Users memo # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Sample data: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Users [ {"name": "Alice", "memo": "groonga user"}, {"name": "Alisa", "memo": "mroonga user"}, {"name": "Bob", "memo": "rroonga user"}, {"name": "Tom", "memo": "nroonga user"}, {"name": "Tobby", "memo": "groonga and mroonga user. mroonga is ..."}, ] # [[0, 1337566253.89858, 0.000355720520019531], true] # [[0, 1337566253.89858, 0.000355720520019531], 5] .ft P .fi .UNINDENT .UNINDENT .sp Here is the simple usage of \fBquery\fP function which execute full text search by keyword \(aqalice\(aq without using \fB\-\-match_columns\fP and \fB\-\-query\fP arguments in \fB\-\-filter\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Users \-\-output_columns name,_score \-\-filter \(aqquery("name * 10", "alice")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "name", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Alice", # 10 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp When executing above query, the keyword \(aqalice\(aq is weighted to the value \- \(aq10\(aq. .sp Here are the contrasting examples with/without \fBquery\fP\&. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Users \-\-output_columns name,memo,_score \-\-match_columns "memo * 10" \-\-query "memo:@groonga OR memo:@mroonga OR memo:@user" \-\-sortby \-_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "name", # "ShortText" # ], # [ # "memo", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Tobby", # "groonga and mroonga user. mroonga is ...", # 4 # ], # [ # "Alice", # "groonga user", # 2 # ], # [ # "Alisa", # "mroonga user", # 2 # ], # [ # "Bob", # "rroonga user", # 1 # ], # [ # "Tom", # "nroonga user", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp In this case, the keywords \(aqgroonga\(aq and \(aqmroonga\(aq and \(aquser\(aq are given same weight value. You can\(aqt pass different weight value to each keyword in this way. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Users \-\-output_columns name,memo,_score \-\-filter \(aqquery("memo * 10", "groonga") || query("memo * 20", "mroonga") || query("memo * 1", "user")\(aq \-\-sortby \-_score # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 5 # ], # [ # [ # "name", # "ShortText" # ], # [ # "memo", # "ShortText" # ], # [ # "_score", # "Int32" # ] # ], # [ # "Tobby", # "groonga and mroonga user. mroonga is ...", # 51 # ], # [ # "Alisa", # "mroonga user", # 21 # ], # [ # "Alice", # "groonga user", # 11 # ], # [ # "Tom", # "nroonga user", # 1 # ], # [ # "Bob", # "rroonga user", # 1 # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp On the other hand, by specifying multiple \fBquery\fP, the keywords \(aqgroonga\(aq and \(aqmroonga\(aq and \(aquser\(aq are given different value of weight. .sp As a result, you can control full text search result by giving different weight to the keywords on your purpose. .SS Parameters .SS Required parameter .sp There are two required parameter, \fBmatch_columns\fP and \fBquery_string\fP\&. .SS \fBmatch_columns\fP .sp It specifies the default target column for fulltext search by \fBquery_string\fP parameter value. It is the same role as \fIselect\-match\-columns\fP parameter in \fBselect\fP\&. .SS \fBquery_string\fP .sp It specifies the search condition in \fB/reference/grn_expr/query_syntax\fP\&. It is the same role as \fBquery\fP parameter in \fBselect\fP\&. .sp See \fIselect\-match\-columns\fP about \fBquery\fP parameter in \fBselect\fP\&. .SS Optional parameter .sp There are some optional parameters. .SS \fBquery_expander\fP .sp It specifies the plugin name for query expansion. .sp There is one plugin bundled in official release \- \fB/reference/query_expanders/tsv\fP\&. .sp See \fB/reference/query_expanders/tsv\fP about details. .SS \fBsubstitution_table\fP .sp It specifies the substitution table and substitution column name by following format such as \fB${TABLE}.${COLUMN}\fP for query expansion. .sp See \fIquery\-expander\fP about details. .SS Return value .sp \fBquery\fP returns whether any record is matched or not. If one or more records are matched, it returns \fBtrue\fP\&. Otherwise, it returns \fBfalse\fP\&. .SS TODO .INDENT 0.0 .IP \(bu 2 Support query_flags .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/select\fP .UNINDENT .SS rand .SS 名前 .sp rand \- 乱数を生成する .SS 書式 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rand([max]) .ft P .fi .UNINDENT .UNINDENT .SS 説明 .sp Groonga組込関数の一つであるrandについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp rand() 関数は 0 から max の間の疑似乱数整数を返します。 .SS 引数 .sp \fBmax\fP .INDENT 0.0 .INDENT 3.5 返値の最大値を指定します。省略した場合は RAND_MAX が指定されたものとみなされます。 .UNINDENT .UNINDENT .SS 返値 .sp 0 と max の間の数を表すInt32型の値を返します。 .SS 例 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rand(10) 3 .ft P .fi .UNINDENT .UNINDENT .SS snippet_html .sp \fBCAUTION:\fP .INDENT 0.0 .INDENT 3.5 This feature is experimental. API will be changed. .UNINDENT .UNINDENT .SS Summary .sp \fBsnippet_html\fP extracts snippets of target text around search keywords (\fBKWIC\fP\&. \fBKeyWord In Context\fP). The snippets are prepared for embedding HTML. Special characters such as \fB<\fP and \fB>\fP are escapsed as \fB<\fP and \fB>\fP\&. Keyword is surrounded with \fB\fP and \fB\fP\&. For example, a snippet of \fBI am a groonga user. <3\fP for keyword \fBgroonga\fP is \fBI am a groonga user. <3\fP\&. .SS Syntax .sp \fBsnippet_html\fP has only one parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C snippet_html(column) .ft P .fi .UNINDENT .UNINDENT .sp \fBsnippet_html\fP has many parameters internally but they can\(aqt be specified for now. You will be able to custom those parameters soon. .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Documents TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Documents content COLUMN_SCALAR Text # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Terms documents_content_index COLUMN_INDEX|WITH_POSITION Documents content # [[0, 1337566253.89858, 0.000355720520019531], true] load \-\-table Documents [ ["content"], ["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."], ["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."] ] # [[0, 1337566253.89858, 0.000355720520019531], 2] .ft P .fi .UNINDENT .UNINDENT .sp \fBsnippet_html\fP can be used in only \fB\-\-output_columns\fP in \fB/reference/commands/select\fP\&. .sp You need to specify \fB\-\-command_version 2\fP argument explicitly because function call in \fB\-\-output_columns\fP is experimental feature in Groonga 2.0.9. It will be enabled by default soon. .sp You also need to specify \fB\-\-query\fP and/or \fB\-\-filter\fP\&. Keywords are extracted from \fB\-\-query\fP and \fB\-\-filter\fP arguments. .sp The following example uses \fB\-\-query "fast performance"\fP\&. In this case, \fBfast\fP and \fBperformance\fP are used as keywords. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Documents \-\-output_columns "snippet_html(content)" \-\-command_version 2 \-\-match_columns content \-\-query "fast performance" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "snippet_html", # "null" # ] # ], # [ # [ # "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, gro", # "onga allows updates without read locks. These characteristics result in superior performance on real\-time applications." # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp \fB\-\-query "fast performance"\fP matches to only the first record\(aqs content. \fBsnippet_html(content)\fP extracts two text parts that include the keywords \fBfast\fP or \fBperformance\fP and surrounds the keywords with \fB\fP and \fB\fP\&. .sp The max number of text parts is 3. If there are 4 or more text parts that include the keywords, only the leading 3 parts are only used. .sp The max size of a text part is 200byte. The unit is bytes not chracters. The size doesn\(aqt include inserted \fB\fP and \fB\fP\&. .sp Both the max number of text parts and the max size of a text part aren\(aqt customizable. .sp You can specify string literal instead of column. .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Documents \-\-output_columns \(aqsnippet_html("Groonga is very fast fulltext search engine.")\(aq \-\-command_version 2 \-\-match_columns content \-\-query "fast performance" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "snippet_html", # "null" # ] # ], # [ # [ # "Groonga is very fast fulltext search engine." # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Return value .sp \fBsnippet_html\fP returns an array of string or \fBnull\fP\&. If \fBsnippet_html\fP can\(aqt find any snippets, it returns \fBnull\fP\&. .sp An element of array is a snippet: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [SNIPPET1, SNIPPET2, SNIPPET3] .ft P .fi .UNINDENT .UNINDENT .sp A snippet includes one or more keywords. The max byte size of a snippet except \fB\fP and \fB\fP is 200byte. The unit isn\(aqt the number of chracters. .sp The array size is larger than or equal to 0 and less than or equal to 3. The max size 3 will be customizable soon. .SS TODO .INDENT 0.0 .IP \(bu 2 Make the max number of text parts customizable. .IP \(bu 2 Make the max size of a text part customizable. .IP \(bu 2 Make keywords customizable. .IP \(bu 2 Make tag that surrounds a keyword customizable. .IP \(bu 2 Make normalization customizable. .IP \(bu 2 Support options by object literal. .UNINDENT .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/select\fP .UNINDENT .SS sub_filter .SS Summary .sp \fBsub_filter\fP evaluates \fBfilter_string\fP in \fBscope\fP context. .sp \fBsub_filter\fP can be used in only \fB\-\-filter\fP in \fB/reference/commands/select\fP\&. .SS Syntax .sp \fBsub_filter\fP requires two arguments. They are \fBscope\fP and \fBfilter_string\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sub_filter(scope, filter_string) .ft P .fi .UNINDENT .UNINDENT .SS Usage .sp Here are a schema definition and sample data to show usage. .sp Sample schema: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Comment TABLE_PAT_KEY UInt32 # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comment name COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comment content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Blog TABLE_PAT_KEY ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Blog title COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Blog content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Blog comments COLUMN_VECTOR Comment # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Comment blog_comment_index COLUMN_INDEX Blog comments # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Lexicon TABLE_PAT_KEY ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon comment_content COLUMN_INDEX|WITH_POSITION Comment content # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon comment_name COLUMN_INDEX|WITH_POSITION Comment name # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Lexicon blog_content COLUMN_INDEX|WITH_POSITION Blog content # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp Sample data: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Comment [ {"_key": 1, "name": "A", "content": "groonga"}, {"_key": 2, "name": "B", "content": "groonga"}, {"_key": 3, "name": "C", "content": "rroonga"}, {"_key": 4, "name": "A", "content": "mroonga"}, ] # [[0, 1337566253.89858, 0.000355720520019531], 4] load \-\-table Blog [ {"_key": "groonga\(aqs blog", "content": "content of groonga\(aqs blog", comments: [1, 2, 3]}, {"_key": "mroonga\(aqs blog", "content": "content of mroonga\(aqs blog", comments: [2, 3, 4]}, {"_key": "rroonga\(aqs blog", "content": "content of rroonga\(aqs blog", comments: [3]}, ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Here is the simple usage of \fBsub_filter\fP function which extracts the blog entry user \(aqA\(aq commented out. .UNINDENT .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Blog \-\-output_columns _key \-\-filter "comments.name @ \e"A\e" && comments.content @ \e"groonga\e"" # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "groonga\(aqs blog" # ], # [ # "mroonga\(aqs blog" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp When executing the above query, not only "groonga\(aqs blog", but also "mroonga\(aqs blog". This is not what you want because user "A" does not mention "groonga" to "mroonga\(aqs blog". .sp Without sub_filter, it means that following conditions are met. .INDENT 0.0 .IP \(bu 2 There is at least one record that user "A" commented out. .IP \(bu 2 There is at least one record that mentioned about "groonga". .UNINDENT .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Blog \-\-output_columns _key \-\-filter \(aqsub_filter(comments, "name @ \e\e"A\e\e" && content @ \e\e"groonga\e\e"")\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_key", # "ShortText" # ] # ], # [ # "groonga\(aqs blog" # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp On the other hand, executing the above query returns the intended result. Because the arguments of sub_filter is evaluated in comments column\(aqs context. .sp It means that sub_filter requires the following condition is met. .INDENT 0.0 .IP \(bu 2 There are the records that user "A" mentions about "groonga". .UNINDENT .SS Parameters .sp There are two required parameter, \fBscope\fP and \fBfilter_string\fP\&. .SS \fBscope\fP .sp It specifies a column of the table that is specified by \fBtable\fP parameter in \fBselect\fP\&. The column has a limitation. The limitation is described later. \fBfilter_string\fP is evaluated in the column context. It means that \fBfilter_string\fP is evaluated like \fBselect \-\-table TYPE_OF_THE_COLUMN \-\-filter FILTER_STRING\fP\&. .sp The specified column type must be a table. In other words, the column type must be reference type. .sp You can chain columns by \fBCOLUMN_1.COLUMN_2.COLUMN_3...COLUMN_N\fP syntax. For example, \fBuser.group.name\fP\&. .sp See \fIselect\-table\fP about \fBtable\fP parameter in \fBselect\fP\&. .SS \fBfilter_string\fP .sp It specifies a search condition in \fB/reference/grn_expr/script_syntax\fP\&. It is evaluated in \fBscope\fP context. .SS Return value .sp \fBsub_filter\fP returns whether any record is matched or not. If one or more records are matched, it returns \fBtrue\fP\&. Otherwise, it returns \fBfalse\fP\&. .SS See also .INDENT 0.0 .IP \(bu 2 \fB/reference/commands/select\fP .IP \(bu 2 \fB/reference/grn_expr/script_syntax\fP .UNINDENT .SS Indexing .sp Groonga supports both online index construction and offline index construction since 2.0.0. .SS Online index construction .sp In online index construction, registered documents can be searchable quickly while indexing. But indexing requires more cost rather than indexing by offline index construction. .sp Online index construction is suitable for a search system that values freshness. For example, a search system for tweets, news, blog posts and so on will value freshness. Online index construction can make fresh documents searchable and keep searchable while indexing. .SS Offline index construction .sp In offline index construction, indexing cost is less than indexing cost by online index construction. Indexing time will be shorter. Index will be smaller. Resources required for indexing will be smaller. But a registering document cannot be searchable until all registered documents are indexed. .sp Offline index construction is suitable for a search system that values less required resources. If a search system doesn\(aqt value freshness, offline index construction will be suitable. For example, a reference manual search system doesn\(aqt value freshness because a reference manual will be updated only at a release. .SS How to use .sp Groonga uses online index construction by default. We register a document, we can search it quickly. .sp Groonga uses offline index construction by adding an index to a column that already has data. .sp We define a schema: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Tweets TABLE_NO_KEY # [[0, 1337566253.89858, 0.000355720520019531], true] column_create Tweets content COLUMN_SCALAR ShortText # [[0, 1337566253.89858, 0.000355720520019531], true] table_create Lexicon TABLE_HASH_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp We register data: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Tweets [ {"content":"Hello!"}, {"content":"I just start it!"}, {"content":"I\(aqm sleepy... Have a nice day... Good night..."} ] # [[0, 1337566253.89858, 0.000355720520019531], 3] .ft P .fi .UNINDENT .UNINDENT .sp We search without index. We get no result: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 0 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "content", # "ShortText" # ] # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp We create index for \fBTweets.content\fP\&. Already registered data in \fBTweets.content\fP are indexed by offline index construction: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C column_create Lexicon tweet COLUMN_INDEX|WITH_POSITION Tweets content # [[0, 1337566253.89858, 0.000355720520019531], true] .ft P .fi .UNINDENT .UNINDENT .sp We search with index. We get a matched record: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 1 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "content", # "ShortText" # ] # ], # [ # 3, # "I\(aqm sleepy... Have a nice day... Good night..." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .sp We register data again. They are indexed by online index construction: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Tweets [ {"content":"Good morning! Nice day."}, {"content":"Let\(aqs go shopping."} ] # [[0, 1337566253.89858, 0.000355720520019531], 2] .ft P .fi .UNINDENT .UNINDENT .sp We can also get newly registered records by searching: .sp Execution example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq # [ # [ # 0, # 1337566253.89858, # 0.000355720520019531 # ], # [ # [ # [ # 2 # ], # [ # [ # "_id", # "UInt32" # ], # [ # "content", # "ShortText" # ] # ], # [ # 3, # "I\(aqm sleepy... Have a nice day... Good night..." # ], # [ # 4, # "Good morning! Nice day." # ] # ] # ] # ] .ft P .fi .UNINDENT .UNINDENT .SS Log .sp Groonga has two log files. They are process log and query log. Process log is for all of \fBexecutables/groonga\fP works. Query log is just for query processing. .SS Process log .sp Process log is enabled by default. Log path can be customized by \fI\-\-log\-path\fP option. Each log has its log level. If a log is smaller than groonga process\(aq log level, it\(aqs not logged. Log level can be customized by \fI\-l\fP or \fBcommands/log_level\fP\&. .SS Format .sp Process log uses the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #{TIME_STAMP}|#{L}| #{MESSAGE} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B TIME_STAMP It\(aqs time stamp uses the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C YYYY\-MM\-DD hh:mm:ss.SSSSSS .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B YYYY Year with four digits. .TP .B MM Month with two digits. .TP .B DD Day with two digits. .TP .B hh Hour with two digits. .TP .B mm Minute with two digits. .TP .B ss Second with two digits. .TP .B SSSSSS Microsecond with six digits. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 2011\-07\-05 06:25:18.345734 .ft P .fi .UNINDENT .UNINDENT .TP .B L Log level with a character. Here is a character and log level map. .INDENT 7.0 .TP .B E Emergency .TP .B A Alert .TP .B C Critical .TP .B e Error .TP .B w Warning .TP .B n Notification .TP .B i Information .TP .B d Debug .TP .B \- Dump .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C E .ft P .fi .UNINDENT .UNINDENT .TP .B MESSAGE Details about the log with free format. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C log opened. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2011\-07\-05 08:35:09.276421|n| grn_init 2011\-07\-05 08:35:09.276553|n| RLIMIT_NOFILE(4096,4096) .ft P .fi .UNINDENT .UNINDENT .SS Query log .sp Query log is disabled by default. It can be enabled by \fI\-\-query\-log\-path\fP option. .SS Format .sp Query log uses the following formats: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #{TIME_STAMP}|#{MESSAGE} #{TIME_STAMP}|#{ID}|>#{QUERY} #{TIME_STAMP}|#{ID}|:#{ELAPSED_TIME} #{PROGRESS} #{TIME_STAMP}|#{ID}|<#{ELAPSED_TIME} #{RETURN_CODE} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B TIME_STAMP It\(aqs time stamp uses the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C YYYY\-MM\-DD hh:mm:ss.SSSSSS .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B YYYY Year with four digits. .TP .B MM Month with two digits. .TP .B DD Day with two digits. .TP .B hh Hour with two digits. .TP .B mm Minute with two digits. .TP .B ss Second with two digits. .TP .B SSSSSS Microsecond with six digits. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 2011\-07\-05 06:25:18.345734 .ft P .fi .UNINDENT .UNINDENT .TP .B ID ID of a thread. Groonga process creates threads to process requests concurrently. Each thread outputs some logs for a request. This ID can be used to extract a log sequence by a thread. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 45ea3034 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B > A character that indicates query is started. .UNINDENT .INDENT 0.0 .TP .B : A character that indicates query is processing. .UNINDENT .INDENT 0.0 .TP .B < A character that indicates query is finished. .TP .B MESSAGE Details about the log with free format. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C query log opened. .ft P .fi .UNINDENT .UNINDENT .TP .B QUERY A query to be processed. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C select users \-\-match_columns hobby \-\-query music .ft P .fi .UNINDENT .UNINDENT .TP .B ELAPSED_TIME Elapsed time in nanoseconds since query is started. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 000000000075770 (It means 75,770 nanoseconds.) .ft P .fi .UNINDENT .UNINDENT .TP .B PROGRESS A processed work at the time. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C select(313401) (It means that \(aqselect\(aq is processed and 313,401 records are remained.) .ft P .fi .UNINDENT .UNINDENT .TP .B RETURN_CODE A return code for the query. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rc=0 (It means return code is 0. 0 means GRN_SUCCESS.) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2011\-07\-05 06:25:19.458756|45ea3034|>select Properties \-\-limit 0 2011\-07\-05 06:25:19.458829|45ea3034|:000000000072779 select(19) 2011\-07\-05 06:25:19.458856|45ea3034|:000000000099998 output(0) 2011\-07\-05 06:25:19.458875|45ea3034|<000000000119062 rc=0 2011\-07\-05 06:25:19.458986|45ea3034|>quit .ft P .fi .UNINDENT .UNINDENT .SS Tuning .SS Summary .sp There are some tuning parameters for improving Groonga performance or handling a large database. .SS Parameters .sp This section describes parameters. .SS The max number of open files per process .sp This parameter is for handling a large database. .sp Groonga creates one or more files per table and colum. If your database has many tables and columns, groonga process needs to open many files. .sp System limits the max number of open files per process. So you need to relax the limitation. .sp Here is an expression that compute how many files are opened by groonga: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 3 (for DB) + N tables + N columns (except index clumns) + (N index columns * 2) + X (the number of plugins etc.) .ft P .fi .UNINDENT .UNINDENT .sp Here is an example schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Entries TABLE_HASH_KEY ShortText column_create Entries content COLUMN_SCALAR Text column_create Entries n_likes COLUMN_SCALAR UInt32 table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content .ft P .fi .UNINDENT .UNINDENT .sp This example opens at least 11 files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 3 + 2 (Entries and Terms) + 2 (Entries.content and Entries.n_likes) + 4 (Terms.entries_key_index and Terms.entries_content_index) + X = 11 + X .ft P .fi .UNINDENT .UNINDENT .SS Memory usage .sp This parameter is for handling a large database. .sp Groonga maps database files onto memory and accesses to them. Groonga doesn\(aqt maps unnecessary files onto memory until they are nneded. .sp If you access to all data in database, all database files are mapped onto memory. If total size of your database files is 6GiB, your groonga process uses 6GiB memory. .sp Normally, your all database files aren\(aqt mapped onto memry. But is may be occurred. It is an example case that you dump your database. .sp You must have memory and swap that is larger than database. .SS Linux .sp This section describes how to configure parameters on Linux. .SS nofile .sp You can relax the \fItuning\-max\-n\-open\-files\fP parameter by creating a configuration file \fB/etc/security/limits.d/groonga.conf\fP that has the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ${USER} soft nofile ${MAX_VALUE} ${USER} hard nofile ${MAX_VALUE} .ft P .fi .UNINDENT .UNINDENT .sp If you run \fBgroonga\fP process by \fBgroonga\fP user and your groonga process needs to open less than 10000 files, use the following configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C groonga soft nofile 10000 groonga hard nofile 10000 .ft P .fi .UNINDENT .UNINDENT .sp The configuration is applied after your groonga service is restarted or re\-login as your groonga user. .SS vm.overcommit_memory .sp This is \fItuning\-memory\-usage\fP related parameter. You can handle a database that is larger than your memory and swap by setting \fBvm.overcommit_memory\fP kernel parameter to 1. 1 means that Groonga can always map database files onto memory. It is no problem until groonga touch mapped database files that their size is larger than memory and swap. Groonga recommends the configuration. .sp See \fI\%Linux kernel documentation about overcommit\fP about \fBvm.overcommit_memory\fP parameter details. .sp You can set the configuration by putting a configuration file \fB/etc/sysctl.d/groonga.conf\fP that has the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vm.overcommit_memory = 1 .ft P .fi .UNINDENT .UNINDENT .sp The configuration can be applied by restarting your system or run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo sysctl \-p .ft P .fi .UNINDENT .UNINDENT .SS vm.max_map_count .sp This is \fItuning\-memory\-usage\fP related parameter. You can handle a 16GiB or more larger size database by increasing \fBvm.max_map_count\fP kernel parameter. The parameter limits the max number of memory maps. .sp The default value of the kernel parameter may be 65530 or 65536. Groonga maps 256KiB memory chunk at one time. If a database is larger than 16GiB, groonga reaches the limitation. (\fB256KiB * 65536 = 16GiB\fP) .sp You needs to increase the value of the kernel parameter to handle 16GiB or more larger size database. For example, you can handle almost 32GiB size database by \fB65536 * 2 = 131072\fP\&. You can set the configuration by putting a configuration file \fB/etc/sysctl.d/groonga.conf\fP that has the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vm.max_map_count = 131072 .ft P .fi .UNINDENT .UNINDENT .sp Note that your real confiugration file will be the following because you already have \fBvm.overcommit_memory\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vm.overcommit_memory = 1 vm.max_map_count = 131072 .ft P .fi .UNINDENT .UNINDENT .sp The configuration can be applied by restarting your system or run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo sysctl \-p .ft P .fi .UNINDENT .UNINDENT .SS FreeBSD .sp This section describes how to configure parameters on FreeBSD. .SS kern.maxfileperproc .sp TODO .SS API .sp Groonga can be used as a fulltext search library. This section describes APIs that are provided by groonga. .SS Global configurations .SS Summary .sp Groonga has the global configurations. You can access them by API. .SS Reference .INDENT 0.0 .TP .B int grn_get_lock_timeout(void) Returns the lock timeout. .sp \fBgrn_ctx\fP acquires a lock for updating a shared value. If other \fBgrn_ctx\fP is already updating the same value, \fBgrn_ctx\fP that try to acquire a lock can\(aqt acquires a lock. The \fBgrn_ctx\fP that can\(aqt acquires a lock waits 1 millisecond and try to acquire a lock again. The try is done \fBtimeout\fP times. If the \fBgrn_ctx\fP that can\(aqt acquires a lock until \fBtimeout\fP times, the tries are failed. .sp The default lock timeout is \fB10000000\fP\&. It means that Groonga doesn\(aqt report a lock failure until about 3 hours. (1 * 10000000 [msec] = 10000 [sec] = 166.666... [min] = 2.777... [hour]) .INDENT 7.0 .TP .B Returns The lock timeout. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_set_lock_timeout(int\fI\ timeout\fP) Sets the lock timeout. .sp See \fBgrn_get_lock_timeout()\fP about lock timeout. .sp There are some special values for \fBtimeout\fP\&. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB0\fP: It means that Groonga doesn\(aqt retry acquiring a lock. Groonga reports a failure after one lock acquirement failure. .IP \(bu 2 negative value: It means that Groonga retries acquiring a lock until Groonga can acquire a lock. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeuot\fP \-\- The new lock timeout. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP\&. It doesn\(aqt fail. .UNINDENT .UNINDENT .SS \fBgrn_cache\fP .SS Summary .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This API is experimental. .UNINDENT .UNINDENT .sp \fBgrn_cache\fP is a data store that keeps responses of \fB/reference/commands/select\fP command. It is not general use cache object. It is only for \fB/reference/commands/select\fP command. .sp You can just change the current cache object by \fBgrn_cache_current_set()\fP\&. \fB/reference/commands/select\fP command response cache is done internally. .sp \fB/reference/commands/select\fP command uses one global cache object. If you open multiple databases, the one cache is shared. It is an important problem. .sp If you open multiple databases and use \fB/reference/commands/select\fP command, you need to use \fBgrn_cache\fP object. It is \fB/reference/executables/groonga\-httpd\fP case. If you open only one database or don\(aqt use \fB/reference/commands/select\fP command, you don\(aqt need to use \fBgrn_cache\fP object. It is \fI\%rroonga\fP case. .SS Example .sp Here is an example that change the current cache object. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grn_cache *cache; grn_cache *cache_previous; cache = grn_cache_open(ctx); cache_previous = grn_cache_current_get(ctx); grn_cache_current_set(ctx, cache); /* grn_ctx_send(ctx, ...); */ grn_cache_current_set(ctx, cache_previous); .ft P .fi .UNINDENT .UNINDENT .SS Reference .INDENT 0.0 .TP .B grn_cache It is an opaque cache object. You can create a \fBgrn_cache\fP by \fBgrn_cache_open()\fP and free the created object by \fBgrn_cache_close()\fP\&. .UNINDENT .INDENT 0.0 .TP .B grn_cache *grn_cache_open(grn_ctx\fI\ *ctx\fP) Creates a new cache object. .sp If memory allocation for the new cache object is failed, \fBNULL\fP is returned. Error information is stored into the \fBctx\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .UNINDENT .TP .B Returns A newly allocated cache object on success, \fBNULL\fP otherwise. The returned cache object must be freed by \fBgrn_cache_close()\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_cache_close(grn_ctx\fI\ *ctx\fP, grn_cache\fI\ *cache\fP) Frees resourses of the \fBcache\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .IP \(bu 2 \fBcache\fP \-\- The cache object to be freed. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_cache_current_set(grn_ctx\fI\ *ctx\fP, grn_cache\fI\ *cache\fP) Sets the cache object that is used in \fB/reference/commands/select\fP command. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .IP \(bu 2 \fBcache\fP \-\- The cache object that is used in \fB/reference/commands/select\fP command. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_cache *grn_cache_current_get(grn_ctx\fI\ *ctx\fP) Gets the cache object that is used in \fB/reference/commands/select\fP command. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .UNINDENT .TP .B Returns The cache object that is used in \fB/reference/commands/select\fP command. It may be \fBNULL\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_cache_set_max_n_entries(grn_ctx\fI\ *ctx\fP, grn_cache\fI\ *cache\fP, unsigned int\fI\ n\fP) Sets the max number of entries of the cache object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .IP \(bu 2 \fBcache\fP \-\- The cache object to be changed. .IP \(bu 2 \fBn\fP \-\- The new max number of entries of the cache object. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B unsigned int grn_cache_get_max_n_entries(grn_ctx\fI\ *ctx\fP, grn_cache\fI\ *cache\fP) Gets the max number of entries of the cache object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- The context. .IP \(bu 2 \fBcache\fP \-\- The target cache object. .UNINDENT .TP .B Returns The max number of entries of the cache object. .UNINDENT .UNINDENT .SS \fBgrn_column\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B GRN_COLUMN_NAME_ID It returns the name of \fB/reference/columns/pseudo\fP \fB_id\fP\&. .sp It is useful to use with \fBGRN_COLUMN_NAME_ID_LEN\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grn_obj *id_column; id_column = grn_ctx_get(ctx, GRN_COLUMN_NAME_ID, GRN_COLUMN_NAME_ID_LEN); .ft P .fi .UNINDENT .UNINDENT .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_ID_LEN It returns the byte size of \fBGRN_COLUMN_NAME_ID\fP\&. .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_KEY It returns the name of \fB/reference/columns/pseudo\fP \fB_key\fP\&. .sp It is useful to use with \fBGRN_COLUMN_NAME_KEY_LEN\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grn_obj *key_column; key_column = grn_ctx_get(ctx, GRN_COLUMN_NAME_KEY, GRN_COLUMN_NAME_KEY_LEN); .ft P .fi .UNINDENT .UNINDENT .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_KEY_LEN It returns the byte size of \fBGRN_COLUMN_NAME_KEY\fP\&. .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_VALUE It returns the name of \fB/reference/columns/pseudo\fP \fB_value\fP\&. .sp It is useful to use with \fBGRN_COLUMN_NAME_VALUE_LEN\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grn_obj *value_column; value_column = grn_ctx_get(ctx, GRN_COLUMN_NAME_VALUE, GRN_COLUMN_NAME_VALUE_LEN); .ft P .fi .UNINDENT .UNINDENT .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_VALUE_LEN It returns the byte size of \fBGRN_COLUMN_NAME_VALUE\fP\&. .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_SCORE It returns the name of \fB/reference/columns/pseudo\fP \fB_score\fP\&. .sp It is useful to use with \fBGRN_COLUMN_NAME_SCORE_LEN\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grn_obj *score_column; score_column = grn_ctx_get(ctx, GRN_COLUMN_NAME_SCORE, GRN_COLUMN_NAME_SCORE_LEN); .ft P .fi .UNINDENT .UNINDENT .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_SCORE_LEN It returns the byte size of \fBGRN_COLUMN_NAME_SCORE\fP\&. .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_NSUBRECS It returns the name of \fB/reference/columns/pseudo\fP \fB_nsubrecs\fP\&. .sp It is useful to use with \fBGRN_COLUMN_NAME_NSUBRECS_LEN\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grn_obj *nsubrecs_column; nsubrecs_column = grn_ctx_get(ctx, GRN_COLUMN_NAME_NSUBRECS, GRN_COLUMN_NAME_NSUBRECS_LEN); .ft P .fi .UNINDENT .UNINDENT .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B GRN_COLUMN_NAME_NSUBRECS_LEN It returns the byte size of \fBGRN_COLUMN_NAME_NSUBRECS\fP\&. .sp Since 3.1.1. .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_column_create(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP, const char\fI\ *path\fP, grn_obj_flags\fI\ flags\fP, grn_obj\fI\ *type\fP) tableに新たなカラムを定義します。nameは省略できません。一つのtableに同一のnameのcolumnを複数定義することはできません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBname\fP \-\- カラム名を指定します。 .IP \(bu 2 \fBname_size\fP \-\- nameパラメータのsize(byte)を指定します。 .IP \(bu 2 \fBpath\fP \-\- カラムを格納するファイルパスを指定します。 flagsに \fBGRN_OBJ_PERSISTENT\fP が指定されている場合のみ有効です。 NULLなら自動的にファイルパスが付与されます。 .IP \(bu 2 \fBflags\fP \-\- .sp \fBGRN_OBJ_PERSISTENT\fP を指定すると永続columnとなります。 .sp \fBGRN_OBJ_COLUMN_INDEX\fP を指定すると転置インデックスとなります。 .sp \fBGRN_OBJ_COLUMN_SCALAR\fP を指定するとスカラ値(単独の値)を格納します。 .sp \fBGRN_OBJ_COLUMN_VECTOR\fP を指定すると値の配列を格納します。 .sp \fBGRN_OBJ_COMPRESS_ZLIB\fP を指定すると値をzlib圧縮して格納します。 .sp \fBGRN_OBJ_COMPRESS_LZO\fP を指定すると値をlzo圧縮して格納します。 .sp \fBGRN_OBJ_COLUMN_INDEX\fP と共に \fBGRN_OBJ_WITH_SECTION\fP を指定すると、転置索引にsection(段落情報)を合わせて格納します。 .sp \fBGRN_OBJ_COLUMN_INDEX\fP と共に \fBGRN_OBJ_WITH_WEIGHT\fP を指定すると、転置索引にweight情報を合わせて格納します。 .sp \fBGRN_OBJ_COLUMN_INDEX\fP と共に \fBGRN_OBJ_WITH_POSITION\fP を指定すると、転置索引に出現位置情報を合わせて格納します。 .IP \(bu 2 \fBtype\fP \-\- カラム値の型を指定します。定義済みのtypeあるいはtableを指定できます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_column_index_update(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *column\fP, grn_id\fI\ id\fP, unsigned int\fI\ section\fP, grn_obj\fI\ *oldvalue\fP, grn_obj\fI\ *newvalue\fP) oldvalue, newvalueの値から得られるキーに対応するcolumnの値の中の、id, sectionに対応するエントリを更新します。columnは \fBGRN_OBJ_COLUMN_INDEX\fP 型のカラムでなければなりません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcolumn\fP \-\- 対象columnを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象レコードのIDを指定します。 .IP \(bu 2 \fBsection\fP \-\- 対象レコードのセクション番号を指定します。 .IP \(bu 2 \fBoldvalue\fP \-\- 更新前の値を指定します。 .IP \(bu 2 \fBnewvalue\fP \-\- 更新後の値を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_column_table(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *column\fP) columnが属するtableを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcolumn\fP \-\- 対象columnを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_column_rename(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *column\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) ctxが使用するdbにおいてcolumnに対応する名前をnameに更新します。columnは永続オブジェクトでなければいけません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcolumn\fP \-\- 対象columnを指定します。 .IP \(bu 2 \fBname\fP \-\- 新しい名前を指定します。 .IP \(bu 2 \fBname_size\fP \-\- nameパラメータのsize（byte）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_column_name(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, char\fI\ *namebuf\fP, int\fI\ buf_size\fP) カラムobjの名前の長さを返します。buf_sizeの長さが名前の長さ以上であった場合は、namebufに該当する名前をコピーします。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBnamebuf\fP \-\- 名前を格納するバッファ（呼出側で準備する）を指定します。 .IP \(bu 2 \fBbuf_size\fP \-\- namebufのサイズ（byte長）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_column_index(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *column\fP, grn_operator\fI\ op\fP, grn_obj\fI\ **indexbuf\fP, int\fI\ buf_size\fP, int\fI\ *section\fP) columnに張られているindexのうち、opの操作を実行可能なものの数を返します。またそれらのidを、buf_sizeに指定された個数を上限としてindexbufに返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcolumn\fP \-\- 対象のcolumnを指定します。 .IP \(bu 2 \fBop\fP \-\- indexで実行したい操作を指定します。 .IP \(bu 2 \fBindexbuf\fP \-\- indexを格納するバッファ（呼出側で準備する）を指定します。 .IP \(bu 2 \fBbuf_size\fP \-\- indexbufのサイズ（byte長）を指定します。 .IP \(bu 2 \fBsection\fP \-\- section番号を格納するint長バッファ（呼出側で準備する）を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_command_version\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_command_version .UNINDENT .INDENT 0.0 .TP .B GRN_COMMAND_VERSION_MIN .UNINDENT .INDENT 0.0 .TP .B GRN_COMMAND_VERSION_STABLE .UNINDENT .INDENT 0.0 .TP .B GRN_COMMAND_VERSION_MAX .UNINDENT .INDENT 0.0 .TP .B grn_command_version grn_get_default_command_version(void) デフォルトのcommand_versionを返します。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_set_default_command_version(grn_command_version\fI\ version\fP) デフォルトのcommand_versionを変更します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversion\fP \-\- 変更後のデフォルトのcommand_versionを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_ctx\fP .SS Summary .sp \fBgrn_ctx\fP is the most important object. \fBgrn_ctx\fP keeps the current infomation such as: .INDENT 0.0 .IP \(bu 2 The last occurred error. .IP \(bu 2 The current encoding. .IP \(bu 2 The default thresholds. (e.g. \fImatch\-escalation\-threshold\fP) .IP \(bu 2 The default command version. (See \fB/reference/command/command_version\fP) .UNINDENT .sp \fBgrn_ctx\fP provides platform features such as: .INDENT 0.0 .IP \(bu 2 Memory management. .IP \(bu 2 Logging. .UNINDENT .sp Most APIs receive \fBgrn_ctx\fP as the first argument. .sp You can\(aqt use the same \fBgrn_ctx\fP from two or more threads. You need to create a \fBgrn_ctx\fP for a thread. You can use two or more \fBgrn_ctx\fP in a thread but it is not needed for usual use\-case. .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_ctx TODO... .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_init(grn_ctx\fI\ *ctx\fP, int\fI\ flags\fP) ctxを初期化します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- 初期化するctx構造体へのポインタを指定します。 .IP \(bu 2 \fBflags\fP \-\- 初期化する \fBctx\fP のオプションを指定します。 .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_fin(grn_ctx\fI\ *ctx\fP) ctxの管理するメモリを解放し、使用を終了します。 .sp If \fBctx\fP is initialized by \fBgrn_ctx_open()\fP not \fBgrn_ctx_init()\fP\&. You need also to call \fBgrn_ctx_close()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- 解放するctx構造体へのポインタを指定します。 .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_ctx *grn_ctx_open(int\fI\ flags\fP) 初期化された \fBgrn_ctx\fP オブジェクトを返します。 .sp \fBgrn_ctx_init()\fP で初期化された \fBgrn_ctx\fP オブジェクトは構造体の実体をAPIの呼び元で確保するのに対して、 \fBgrn_ctx_open()\fP ではGroongaライブラリの内部で、実体を確保します。 どちらで初期化された \fBgrn_ctx\fP も、 \fBgrn_ctx_fin()\fP で解放できます。 \fBgrn_ctx_open()\fP で確保した \fBgrn_ctx\fP 構造体に関しては、\fBgrn_ctx_fin()\fP で解放した後に、その \fBgrn_ctx\fP で作成した \fBgrn_obj\fP を \fBgrn_obj_close()\fP によって解放しても問題ありません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBflags\fP \-\- 初期化する \fBctx\fP のオプションを指定します。 .UNINDENT .TP .B Returns 初期化された \fBgrn_ctx\fP オブジェクトを返します。 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_close(grn_ctx\fI\ *ctx\fP) It calls \fBgrn_ctx_fin()\fP and frees allocated memory for \fBctx\fP by \fBgrn_ctx_open()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- no longer needed \fBgrn_ctx\fP\&. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_set_finalizer(grn_ctx\fI\ *ctx\fP, grn_proc_func\fI\ *func\fP) ctxを破棄するときに呼ばれる関数を設定します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- 対象ctxを指定します。 .IP \(bu 2 \fBfunc\fP \-\- \fBctx\fP を破棄するときに呼ばれる関数を指定します。 .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_command_version grn_ctx_get_command_version(grn_ctx\fI\ *ctx\fP) command_versionを返します。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_set_command_version(grn_ctx\fI\ *ctx\fP, grn_command_version\fI\ version\fP) command_versionを変更します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversion\fP \-\- 変更後のcommand_versionを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_use(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *db\fP) ctxが操作対象とするdbを指定します。NULLを指定した場合は、dbを操作しない状態(init直後の状態)になります。 .sp Don\(aqt use it with \fBgrn_ctx\fP that has \fBGRN_CTX_PER_DB\fP flag. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdb\fP \-\- ctxが使用するdbを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_ctx_db(grn_ctx\fI\ *ctx\fP) ctxが現在操作対象としているdbを返します。dbを使用していない場合はNULLを返します。 .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_ctx_get(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, int\fI\ name_size\fP) ctxが使用するdbからnameに対応するオブジェクトを検索して返す。nameに一致するオブジェクトが存在しなければNULLを返す。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- 検索しようとするオブジェクトの名前。 .IP \(bu 2 \fBname_size\fP \-\- The number of bytes of name. If negative value is specified, name is assumed that NULL\-terminated string. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_ctx_at(grn_ctx\fI\ *ctx\fP, grn_id\fI\ id\fP) ctx、またはctxが使用するdbからidに対応するオブジェクトを検索して返す。idに一致するオブジェクトが存在しなければNULLを返す。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBid\fP \-\- 検索しようとするオブジェクトのidを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_db\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .sp TODO... .INDENT 0.0 .TP .B grn_db TODO... .UNINDENT .INDENT 0.0 .TP .B grn_db_create_optarg It is used for specifying options for \fBgrn_db_create()\fP\&. .UNINDENT .INDENT 0.0 .TP .B char **grn_db_create_optarg.builtin_type_names 組み込み型の名前となるnul終端文字列の配列を指定する。 .UNINDENT .INDENT 0.0 .TP .B int grn_db_create_optarg.n_builtin_type_names n_builtin_type_namesには、optarg.builtin_type_namesで指定する文字列の数を 指定する。配列のoffsetはenum型grn_builtin_typeの値に対応する。 .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_db_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *path\fP, grn_db_create_optarg\fI\ *optarg\fP) 新たなdbを作成します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- 初期化済みの \fBgrn_ctx\fP を指定します。 .IP \(bu 2 \fBpath\fP \-\- 作成するdbを格納するファイルパスを指定します。NULLならtemporary dbとなります。NULL以外のパスを指定した場合はpersistent dbとなります。 .IP \(bu 2 \fBoptarg\fP \-\- .sp Currently, it is not used. It is just ignored. .sp 作成するdbの組み込み型の名前を変更する時に指定します。 .sp optarg.builtin_type_namesには、組み込み型の名前となるnull終端文字列の配列を指定します。optarg.n_builtin_type_namesには、optarg.builtin_type_namesで指定する文字列の数を指定します。配列のoffsetはenum型grn_builtin_typeの値に対応します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_db_open(grn_ctx\fI\ *ctx\fP, const char\fI\ *path\fP) 既存のdbを開きます。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- 開こうとするdbを格納するファイルパスを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B void grn_db_touch(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *db\fP) dbの内容の最終更新時刻を現在時刻にします。 .sp 最終更新時刻はキャッシュが有効かどうかの判断などに利用されます。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdb\fP \-\- 内容が変更されたdbを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_db(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objの属するdbを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_encoding\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_encoding TODO... .UNINDENT .INDENT 0.0 .TP .B grn_encoding grn_get_default_encoding(void) デフォルトのencodingを返します。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_set_default_encoding(grn_encoding\fI\ encoding\fP) デフォルトのencodingを変更します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBencoding\fP \-\- 変更後のデフォルトのencodingを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B const char *grn_encoding_to_string(grn_encoding\fI\ encoding\fP) Returns string representation for the encoding. For example, \(aqgrn_encoding_to_string(\fBGRN_ENC_UTF8\fP)\(aq returns \(aq"utf8"\(aq. .sp "unknown" is returned for invalid encoding. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBencoding\fP \-\- The encoding. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_encoding grn_encoding_parse(const char\fI\ *name\fP) Parses encoding name and returns grn_encoding. For example, \(aqgrn_encoding_parse("UTF8")\(aq returns \(aq\fBGRN_ENC_UTF8\fP\(aq. .sp \fBGRN_ENC_UTF8\fP is returned for invalid encoding name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The encoding name. .UNINDENT .UNINDENT .UNINDENT .SS grn_expr .sp \fIgrn_expr\fP is an \fBgrn_obj\fP that represents an expression. Here is a list of what expression can do: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Expression can apply some operations to a record by \fBgrn_expr_exec()\fP\&. .IP \(bu 2 Expression can represents search condition. \fBgrn_table_select()\fP can select records that match against the search condition represented by expression. .UNINDENT .UNINDENT .UNINDENT .sp There are two string representations of expression: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB/reference/grn_expr/query_syntax\fP .IP \(bu 2 \fB/reference/grn_expr/script_syntax\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBgrn_expr_parse()\fP parses string represented expression and appends the parsed expression to another expression. .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_rc grn_expr_close(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_add_var(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_get_var_by_offset(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, unsigned int\fI\ offset\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_append_obj(grn_ctx *ctx, grn_obj *expr, grn_obj *obj, grn_operator op, int nargs); .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_append_const(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, grn_obj\fI\ *obj\fP, grn_operator\fI\ op\fP, int\fI\ nargs\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_append_const_str(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, const char\fI\ *str\fP, unsigned int\fI\ str_size\fP, grn_operator\fI\ op\fP, int\fI\ nargs\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_append_const_int(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, int\fI\ i\fP, grn_operator\fI\ op\fP, int\fI\ nargs\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_rc grn_expr_append_op(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, grn_operator\fI\ op\fP, int\fI\ nargs\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_expr_syntax_escape(grn_ctx\fI\ *ctx\fP, const char\fI\ *string\fP, int\fI\ string_size\fP, const char\fI\ *target_characters\fP, char\fI\ escape_character\fP, grn_obj\fI\ *escaped_string\fP) Escapes \fBtarget_characters\fP in \fBstring\fP by \fBescape_character\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- Its encoding must be the same encoding of \fBstring\fP\&. It is used for allocating buffer for \fBescaped_string\fP\&. .IP \(bu 2 \fBstring\fP \-\- String expression representation. .IP \(bu 2 \fBstring_size\fP \-\- The byte size of \fBstring\fP\&. \fB\-1\fP means \fBstring\fP is NULL terminated string. .IP \(bu 2 \fBtarget_characters\fP \-\- NULL terminated escape target characters. For example, \fB"+\-><~*()\e"\e\e:"\fP is \fBtarget_characters\fP for \fB/reference/grn_expr/query_syntax\fP\&. .IP \(bu 2 \fBescape_character\fP \-\- The character to use escape a character in \fBtarget_characters\fP\&. For example, \fB\e\e\fP (backslash) is \fBescaped_character\fP for \fB/reference/grn_expr/query_syntax\fP\&. .IP \(bu 2 \fBescaped_string\fP \-\- The output of escaped \fBstring\fP\&. It should be text typed bulk. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_expr_syntax_escape_query(grn_ctx\fI\ *ctx\fP, const char\fI\ *query\fP, int\fI\ query_size\fP, grn_obj\fI\ *escaped_query\fP) Escapes special characters in \fB/reference/grn_expr/query_syntax\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- Its encoding must be the same encoding of \fBquery\fP\&. It is used for allocating buffer for \fBescaped_query\fP\&. .IP \(bu 2 \fBquery\fP \-\- String expression representation in \fB/reference/grn_expr/query_syntax\fP\&. .IP \(bu 2 \fBquery_size\fP \-\- The byte size of \fBquery\fP\&. \fB\-1\fP means \fBquery\fP is NULL terminated string. .IP \(bu 2 \fBescaped_query\fP \-\- The output of escaped \fBquery\fP\&. It should be text typed bulk. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP on success, not \fBGRN_SUCCESS\fP on error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_rc grn_expr_compile(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_exec(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, int\fI\ nargs\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_API grn_obj *grn_expr_alloc(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *expr\fP, grn_id\fI\ domain\fP, grn_obj_flags\fI\ flags\fP) .UNINDENT .SS \fBgrn_geo\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_geo_point .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_geo_select_in_rectangle(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *index\fP, grn_obj\fI\ *top_left_point\fP, grn_obj\fI\ *bottom_right_point\fP, grn_obj\fI\ *res\fP, grn_operator\fI\ op\fP) It selects records that are in the rectangle specified by top_left_point parameter and bottom_right_point parameter. Records are searched by index parameter. Found records are added to res parameter table with op parameter operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBindex\fP \-\- the index column for TokyoGeoPoint or WGS84GeoPpoint type. .IP \(bu 2 \fBtop_left_point\fP \-\- the top left point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .IP \(bu 2 \fBbottom_right_point\fP \-\- the bottom right point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .IP \(bu 2 \fBres\fP \-\- the table to store found record IDs. It must be \fBGRN_TABLE_HASH_KEY\fP type table. .IP \(bu 2 \fBop\fP \-\- the operator for matched records. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_geo_estimate_in_rectangle(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *index\fP, grn_obj\fI\ *top_left_point\fP, grn_obj\fI\ *bottom_right_point\fP) It estimates number of records in the rectangle specified by top_left_point parameter and bottom_right_point parameter. Number of records is estimated by index parameter. If an error is occurred, \-1 is returned. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBindex\fP \-\- the index column for TokyoGeoPoint or WGS84GeoPpoint type. .IP \(bu 2 \fBtop_left_point\fP \-\- the top left point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .IP \(bu 2 \fBbottom_right_point\fP \-\- the bottom right point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_geo_cursor_open_in_rectangle(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *index\fP, grn_obj\fI\ *top_left_point\fP, grn_obj\fI\ *bottom_right_point\fP, int\fI\ offset\fP, int\fI\ limit\fP) It opens a cursor to get records in the rectangle specfied by top_left_point parameter and bottom_right_point parameter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBindex\fP \-\- the index column for TokyoGeoPoint or WGS84GeoPpoint type. .IP \(bu 2 \fBtop_left_point\fP \-\- the top left point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .IP \(bu 2 \fBbottom_right_point\fP \-\- the bottom right point of the target rectangle. (ShortText, Text, LongText, TokyoGeoPoint or WGS84GeoPoint) .IP \(bu 2 \fBoffset\fP \-\- the cursor returns records from offset parameter position. offset parameter is based on 0. .IP \(bu 2 \fBlimit\fP \-\- the cursor returns at most limit parameter records. \-1 means no limit. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_posting *grn_geo_cursor_next(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *cursor\fP) It returns the next posting that has record ID. It returns NULL after all records are returned. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcursor\fP \-\- the geo cursor. .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_hook\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_hook_entry TODO... .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_add_hook(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_hook_entry\fI\ entry\fP, int\fI\ offset\fP, grn_obj\fI\ *proc\fP, grn_obj\fI\ *data\fP) objに対してhookを追加します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBentry\fP \-\- .sp \fBGRN_HOOK_GET\fP は、objectの参照時に呼び出されるhookを定義します。 .sp \fBGRN_HOOK_SET\fP は、objectの更新時に呼び出されるhookを定義します。 .sp \fBGRN_HOOK_SELECT\fP は、検索処理の実行中に適時呼び出され、処理の実行状況を調べたり、実行の中断を指示することができます。 .IP \(bu 2 \fBoffset\fP \-\- .sp hookの実行順位。offsetに対応するhookの直前に新たなhookを挿入します。 .sp 0を指定した場合は先頭に挿入されます。\-1を指定した場合は末尾に挿入されます。 .sp objectに複数のhookが定義されている場合は順位の順に呼び出されます。 .IP \(bu 2 \fBproc\fP \-\- 手続きを指定します。 .IP \(bu 2 \fBdata\fP \-\- hook固有情報を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_get_nhooks(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_hook_entry\fI\ entry\fP) objに定義されているhookの数を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBentry\fP \-\- hookタイプを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_get_hook(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_hook_entry\fI\ entry\fP, int\fI\ offset\fP, grn_obj\fI\ *data\fP) objに定義されているhookの手続き（proc）を返します。hook固有情報が定義されている場合は、その内容をdataにコピーして返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBentry\fP \-\- hookタイプを指定します。 .IP \(bu 2 \fBoffset\fP \-\- 実行順位を指定します。 .IP \(bu 2 \fBdata\fP \-\- hook固有情報格納バッファを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_delete_hook(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_hook_entry\fI\ entry\fP, int\fI\ offset\fP) objに定義されているhookを削除します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBentry\fP \-\- hookタイプを指定します。 .IP \(bu 2 \fBoffset\fP \-\- 実行順位を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_ii\fP .SS Summary .sp buffered index builder .sp 特定のアプリケーション用に準備した内部APIです。 .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_ii .UNINDENT .INDENT 0.0 .TP .B grn_ii_buffer .UNINDENT .INDENT 0.0 .TP .B grn_ii_buffer *grn_ii_buffer_open(grn_ctx\fI\ *ctx\fP, grn_ii\fI\ *ii\fP, long long unsigned int\fI\ update_buffer_size\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ii_buffer_append(grn_ctx\fI\ *ctx\fP, grn_ii_buffer\fI\ *ii_buffer\fP, grn_id\fI\ rid\fP, unsigned int\fI\ section\fP, grn_obj\fI\ *value\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ii_buffer_commit(grn_ctx\fI\ *ctx\fP, grn_ii_buffer\fI\ *ii_buffer\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ii_buffer_close(grn_ctx\fI\ *ctx\fP, grn_ii_buffer\fI\ *ii_buffer\fP) .UNINDENT .SS \fBgrn_index_cursor\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_obj *grn_index_cursor_open(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP, grn_obj\fI\ *index\fP, grn_id\fI\ rid_min\fP, grn_id\fI\ rid_max\fP, int\fI\ flags\fP) \fBgrn_table_cursor\fP から取得できるそれぞれのレコードについて、 \fBGRN_OBJ_COLUMN_INDEX\fP 型のカラムの値を順番に取り出すためのカーソルを生成して返します。 .sp rid_min, rid_maxを指定して取得するレコードidの値を制限することができます。 .sp 戻り値であるgrn_index_cursorは \fBgrn_obj_close()\fP を使って解放します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .IP \(bu 2 \fBindex\fP \-\- 対象インデックスカラムを指定します。 .IP \(bu 2 \fBrid_min\fP \-\- 出力するレコードidの下限を指定します。 .IP \(bu 2 \fBrid_max\fP \-\- 出力するレコードidの上限を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_posting *grn_index_cursor_next(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *ic\fP, grn_id\fI\ *tid\fP) cursorの範囲内のインデックスの値を順番に取り出します。 .sp tidにNULL以外を指定した場合は、index_cursorを作成するときに指定したtable_cursorの現在の対象レコードのidを返します。 .sp 戻り値である \fBgrn_posting\fP 構造体は解放する必要はありません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBic\fP \-\- 対象cursorを指定します。 .IP \(bu 2 \fBtid\fP \-\- テーブルレコードIDを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_info\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_info_type TODO... .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_get_info(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_info_type\fI\ type\fP, grn_obj\fI\ *valuebuf\fP) objのtypeに対応する情報をvaluebufに格納します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objを指定します。 .IP \(bu 2 \fBtype\fP \-\- 取得する情報の種類を指定します。 .IP \(bu 2 \fBvaluebuf\fP \-\- 値を格納するバッファ（呼出側で準備）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_set_info(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_info_type\fI\ type\fP, grn_obj\fI\ *value\fP) objのtypeに対応する情報をvalueの内容に更新します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objを指定します。 .IP \(bu 2 \fBtype\fP \-\- 設定する情報の種類を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_get_element_info(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP, grn_info_type\fI\ type\fP, grn_obj\fI\ *value\fP) objのidに対応するレコードの、typeに対応する情報をvaluebufに格納します。呼出側ではtypeに応じて十分なサイズのバッファを確保しなければいけません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象IDを指定します。 .IP \(bu 2 \fBtype\fP \-\- 取得する情報の種類を指定します。 .IP \(bu 2 \fBvalue\fP \-\- 値を格納するバッファ（呼出側で準備）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_set_element_info(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP, grn_info_type\fI\ type\fP, grn_obj\fI\ *value\fP) objのidに対応するレコードのtypeに対応する情報をvalueの内容に更新します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象IDを指定します。 .IP \(bu 2 \fBtype\fP \-\- 設定する情報の種類を指定します。 .IP \(bu 2 \fBvalue\fP \-\- 設定しようとする値を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_match_escalation\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B long long int grn_ctx_get_match_escalation_threshold(grn_ctx\fI\ *ctx\fP) 検索の挙動をエスカレーションする閾値を返します。エスカレーションの詳細は検索の仕様に関するドキュメントを参照してください。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_ctx_set_match_escalation_threshold(grn_ctx\fI\ *ctx\fP, long long int\fI\ threshold\fP) 検索の挙動をエスカレーションする閾値を変更します。エスカレーションの詳細は検索の仕様に関するドキュメントを参照してください。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBthreshold\fP \-\- 変更後の検索の挙動をエスカレーションする閾値を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B long long int grn_get_default_match_escalation_threshold(void) デフォルトの検索の挙動をエスカレーションする閾値を返します。エスカレーションの詳細は検索の仕様に関するドキュメントを参照してください。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_set_default_match_escalation_threshold(long long int\fI\ threshold\fP) デフォルトの検索の挙動をエスカレーションする閾値を変更します。エスカレーションの詳細は詳細は検索の仕様に関するドキュメントを参照してください。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBthreshold\fP \-\- 変更後のデフォルトの検索の挙動をエスカレーションする閾値を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_obj\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_obj TODO... .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_column(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) nameがカラム名の場合、それに対応するtableのカラムを返します。対応するカラムが存在しなければNULLを返します。 .sp nameはアクセサ文字列の場合、それに対応するaccessorを返します。アクセサ文字列とは、カラム名等を\(aq.\(aqで連結した文字列です。\(aq_id\(aq, \(aq_key\(aqは特殊なアクセサで、それぞれレコードID/keyを返します。例) \(aqcol1\(aq / \(aqcol2.col3\(aq / \(aqcol2._id\(aq .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBname\fP \-\- カラム名を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_bool grn_obj_is_builtin(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) Check whether Groonga built\-in object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBctx\fP \-\- context .IP \(bu 2 \fBobj\fP \-\- target object .UNINDENT .TP .B Returns \fBGRN_TRUE\fP for built\-in groonga object, \fBGRN_FALSE\fP otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_obj_get_value(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP, grn_obj\fI\ *value\fP) objのIDに対応するレコードのvalueを取得します。valueを戻り値として返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象レコードのIDを指定します。 .IP \(bu 2 \fBvalue\fP \-\- 値を格納するバッファ（呼出側で準備する）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_get_values(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ offset\fP, void\fI\ **values\fP) objに指定されたカラムについて、offsetに指定されたレコードIDを開始位置として、IDが連続するレコードに対応するカラム値が昇順に格納された配列へのポインタをvaluesにセットします。 .sp 取得できた件数が戻り値として返されます。エラーが発生した場合は \-1 が返されます。 .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 値が固定長であるカラムのみがobjに指定できます。範囲内のIDに対応するレコードが有効であるとは限りません。delete操作を実行したことのあるテーブルに対しては、\fBgrn_table_at()\fP などによって各レコードの存否を別途確認しなければなりません。 .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBoffset\fP \-\- 値を取得する範囲の開始位置となるレコードIDを指定します。 .IP \(bu 2 \fBvalues\fP \-\- 値の配列がセットされます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_set_value(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP, grn_obj\fI\ *value\fP, int\fI\ flags\fP) objのIDに対応するレコードの値を更新します。対応するレコードが存在しない場合は \fBGRN_INVALID_ARGUMENT\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象レコードのIDを指定します。 .IP \(bu 2 \fBvalue\fP \-\- 格納する値を指定します。 .IP \(bu 2 \fBflags\fP \-\- .sp 以下の値を指定できます。 .INDENT 2.0 .INDENT 2.0 .IP \(bu 2 \fBGRN_OBJ_SET\fP .IP \(bu 2 \fBGRN_OBJ_INCR\fP .IP \(bu 2 \fBGRN_OBJ_DECR\fP .UNINDENT .INDENT 2.0 .IP \(bu 2 \fBGRN_OBJ_APPEND\fP .IP \(bu 2 \fBGRN_OBJ_PREPEND\fP .IP \(bu 2 \fBGRN_OBJ_GET\fP .UNINDENT .INDENT 2.0 .IP \(bu 2 \fBGRN_OBJ_COMPARE\fP .IP \(bu 2 \fBGRN_OBJ_LOCK\fP .IP \(bu 2 \fBGRN_OBJ_UNLOCK\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_SET_MASK .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_SET レコードの値をvalueと置き換えます。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_INCR レコードの値にvalueを加算します。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_DECR レコードの値にvalueを減算します。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_APPEND レコードの値の末尾にvalueを追加します。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_PREPEND レコードの値の先頭にvalueを追加します。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_GET 新しいレコードの値をvalueにセットします。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_COMPARE レコードの値とvalueが等しいか調べます。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_LOCK 当該レコードをロックします。\fBGRN_OBJ_COMPARE\fP と共に指定された場合は、レコードの値とvalueが等しい場合に限ってロックします。 .UNINDENT .INDENT 0.0 .TP .B GRN_OBJ_UNLOCK 当該レコードのロックを解除します。 .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_remove(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objをメモリから解放し、それが永続オブジェクトであった場合は、該当するファイル一式を削除します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_rename(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) ctxが使用するdbにおいてobjに対応する名前をnameに更新します。objは永続オブジェクトでなければいけません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBname\fP \-\- 新しい名前を指定します。 .IP \(bu 2 \fBname_size\fP \-\- nameパラメータのsize（byte）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_close(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) 一時的なobjectであるobjをメモリから解放します。objに属するobjectも再帰的にメモリから解放されます。 .sp 永続的な、table, column, exprなどは解放してはいけません。一般的には、一時的か永続的かを気にしなくてよい \fBgrn_obj_unlink()\fP を用いるべきです。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_reinit(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ domain\fP, unsigned char\fI\ flags\fP) objの型を変更します。 .sp objは \fBGRN_OBJ_INIT()\fP マクロなどで初期化済みでなければいけません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBdomain\fP \-\- 変更後のobjの型を指定します。 .IP \(bu 2 \fBflags\fP \-\- \fBGRN_OBJ_VECTOR\fP を指定するとdomain型の値のベクタを格納するオブジェクトになります。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B void grn_obj_unlink(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objをメモリから解放します。objに属するobjectも再帰的にメモリから解放されます。 .UNINDENT .INDENT 0.0 .TP .B const char *grn_obj_path(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objに対応するファイルパスを返します。一時objectならNULLを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_name(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, char\fI\ *namebuf\fP, int\fI\ buf_size\fP) objの名前の長さを返します。無名objectなら0を返します。 .sp 名前付きのobjectであり、buf_sizeの長さが名前の長以上であった場合は、namebufに該当する名前をコピーします。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBnamebuf\fP \-\- 名前を格納するバッファ（呼出側で準備する）を指定します。 .IP \(bu 2 \fBbuf_size\fP \-\- namebufのサイズ（byte長）を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_obj_get_range(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objパラメータのとる値の範囲を表わしているオブジェクトのIDを返します。例えば、\fBgrn_builtin_type\fP にある \fBGRN_DB_INT\fP などを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_expire(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, int\fI\ threshold\fP) objの占有するメモリのうち、可能な領域をthresholdを指標として解放します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_check(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objに対応するファイルの整合性を検査します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_lock(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP, int\fI\ timeout\fP) objをlockします。timeout（秒）経過してもlockを取得できない場合は \fBGRN_RESOURCE_DEADLOCK_AVOIDED\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_unlock(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_id\fI\ id\fP) objをunlockします。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_clear_lock(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) 強制的にロックをクリアします。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B unsigned int grn_obj_is_locked(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objが現在lockされていれば0以外の値を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_obj_defrag(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, int\fI\ threshold\fP) objの占有するDBファイル領域のうち、可能な領域をthresholdを指標としてフラグメントの解消を行います。 .sp フラグメント解消が実行されたセグメントの数を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_obj_id(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objのidを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_delete_by_id(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *db\fP, grn_id\fI\ id\fP, grn_bool\fI\ removep\fP) dbからidに対応するテーブルやカラムなどを削除します。mroonga向けに用意した内部APIです。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdb\fP \-\- The target database. .IP \(bu 2 \fBid\fP \-\- The object (table, column and so on) ID to be deleted. .IP \(bu 2 \fBremovep\fP \-\- If \fBGRN_TRUE\fP, clear object cache and remove relation between ID and key in database. Otherwise, just clear object cache. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_path_by_id(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *db\fP, grn_id\fI\ id\fP, char\fI\ *buffer\fP) dbのidに対応するpathを返します。mroonga向けに用意した内部APIです。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdb\fP \-\- The target database. .IP \(bu 2 \fBid\fP \-\- The object (table, column and so on) ID to be deleted. .IP \(bu 2 \fBbuffer\fP \-\- path string corresponding to the id will be set in this buffer. .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_proc\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_proc_type TODO... .UNINDENT .INDENT 0.0 .TP .B grn_proc_func TODO... .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_proc_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, int\fI\ name_size\fP, grn_proc_type\fI\ type\fP, grn_proc_func\fI\ *init\fP, grn_proc_func\fI\ *next\fP, grn_proc_func\fI\ *fin\fP, unsigned int\fI\ nvars\fP, grn_expr_var\fI\ *vars\fP) nameに対応する新たなproc(手続き)をctxが使用するdbに定義します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- 作成するprocの名前を指定します。 .IP \(bu 2 \fBname_size\fP \-\- The number of bytes of name parameter. If negative value is specified, name parameter is assumed that NULL\-terminated string. .IP \(bu 2 \fBtype\fP \-\- procの種類を指定します。 .IP \(bu 2 \fBinit\fP \-\- 初期化関数のポインタを指定します。 .IP \(bu 2 \fBnext\fP \-\- 実処理関数のポインタを指定します。 .IP \(bu 2 \fBfin\fP \-\- 終了関数のポインタを指定します。 .IP \(bu 2 \fBnvars\fP \-\- procで使用する変数の数を指定します。 .IP \(bu 2 \fBvars\fP \-\- procで使用する変数の定義を指定します。( \fBgrn_expr_var\fP 構造体の配列) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_proc_get_info(grn_ctx\fI\ *ctx\fP, grn_user_data\fI\ *user_data\fP, grn_expr_var\fI\ **vars\fP, unsigned int\fI\ *nvars\fP, grn_obj\fI\ **caller\fP) user_dataをキーとして、現在実行中の \fBgrn_proc_func\fP 関数および定義されている変数( \fBgrn_expr_var\fP )の配列とその数を取得します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuser_data\fP \-\- \fBgrn_proc_func\fP に渡されたuser_dataを指定します。 .IP \(bu 2 \fBnvars\fP \-\- 変数の数を取得します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_set_finalizer(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_proc_func\fI\ *func\fP) objectを破棄するときに呼ばれる関数を設定します。 .sp table, column, proc, exprのみ設定可能です。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .IP \(bu 2 \fBfunc\fP \-\- objectを破棄するときに呼ばれる関数を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_search\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_search_optarg .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_obj_search(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP, grn_obj\fI\ *query\fP, grn_obj\fI\ *res\fP, grn_operator\fI\ op\fP, grn_search_optarg\fI\ *optarg\fP) objを対象としてqueryにマッチするレコードを検索し、opの指定に従ってresにレコードを追加あるいは削除します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 検索対象のobjectを指定します。 .IP \(bu 2 \fBquery\fP \-\- 検索クエリを指定します。 .IP \(bu 2 \fBres\fP \-\- 検索結果を格納するテーブルを指定します。 .IP \(bu 2 \fBop\fP \-\- \fBGRN_OP_OR\fP, \fBGRN_OP_AND\fP, \fBGRN_OP_AND_NOT\fP, \fBGRN_OP_ADJUST\fP のいずれかを指定します。 .IP \(bu 2 \fBoptarg\fP \-\- 詳細検索条件を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_table\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_obj *grn_table_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP, const char\fI\ *path\fP, grn_obj_flags\fI\ flags\fP, grn_obj\fI\ *key_type\fP, grn_obj\fI\ *value_type\fP) nameパラメータに対応する新たなtableをctxが使用するdbに定義します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- .sp 作成するtableの名前を指定します。NULLなら無名tableとなります。 .sp persistent dbに対して名前をありのtableを作成するときには、flagsに \fBGRN_OBJ_PERSISTENT\fP が指定されていなけれなりません。 .IP \(bu 2 \fBpath\fP \-\- 作成するtableのファイルパスを指定します。 flagsに \fBGRN_OBJ_PERSISTENT\fP が指定されている場合のみ有効です。 NULLなら自動的にファイルパスが付与されます。 .IP \(bu 2 \fBflags\fP \-\- .sp \fBGRN_OBJ_PERSISTENT\fP を指定すると永続tableとなります。 .sp \fBGRN_OBJ_TABLE_PAT_KEY\fP, \fBGRN_OBJ_TABLE_HASH_KEY\fP, \fBGRN_OBJ_TABLE_NO_KEY\fP のいずれかを指定します。 .sp \fBGRN_OBJ_KEY_NORMALIZE\fP を指定すると正規化された文字列がkeyとなります。 .sp \fBGRN_OBJ_KEY_WITH_SIS\fP を指定するとkey文字列の全suffixが自動的に登録されます。 .IP \(bu 2 \fBkey_type\fP \-\- .sp keyの型を指定します。\fBGRN_OBJ_TABLE_NO_KEY\fP が指定された場合は無効です。 既存のtypeあるいはtableを指定できます。 .sp key_typeにtable Aを指定してtable Bを作成した場合、Bは必ずAのサブセットとなります。 .IP \(bu 2 \fBvalue_type\fP \-\- keyに対応する値を格納する領域の型を指定します。 tableはcolumnとは別に、keyに対応する値を格納する領域を一つだけ持つことができます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_table_add(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *key\fP, unsigned int\fI\ key_size\fP, int\fI\ *added\fP) keyに対応する新しいrecordをtableに追加し、そのIDを返します。keyに対応するrecordがすでにtableに存在するならば、そのrecordのIDを返します。 .sp \fBGRN_OBJ_TABLE_NO_KEY\fP が指定されたtableでは、key, key_size は無視されます。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBkey\fP \-\- 検索keyを指定します。 .IP \(bu 2 \fBadded\fP \-\- NULL以外の値が指定された場合、新たにrecordが追加された時には1が、既存recordだった時には0がセットされます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_table_get(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *key\fP, unsigned int\fI\ key_size\fP) It finds a record that has key parameter and returns ID of the found record. If table parameter is a database, it finds an object (table, column and so on) that has key parameter and returns ID of the found object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- The table or database. .IP \(bu 2 \fBkey\fP \-\- The record or object key to be found. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_table_at(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, grn_id\fI\ id\fP) tableにidに対応するrecordが存在するか確認し、存在すれば指定されたIDを、存在しなければ \fBGRN_ID_NIL\fP を返します。 .sp 注意: 実行には相応のコストがかかるのであまり頻繁に呼ばないようにして下さい。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBid\fP \-\- 検索idを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_table_lcp_search(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *key\fP, unsigned int\fI\ key_size\fP) tableが \fBGRN_TABLE_PAT_KEY\fP もしくは \fBGRN_TABLE_DAT_KEY\fP を指定して作ったtableなら、longest common prefix searchを行い、対応するIDを返します。 .sp tableが \fBGRN_TABLE_HASH_KEY\fP を指定して作ったtableなら、完全に一致するキーを検索し、対応するIDを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBkey\fP \-\- 検索keyを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_table_get_key(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, grn_id\fI\ id\fP, void\fI\ *keybuf\fP, int\fI\ buf_size\fP) tableのIDに対応するレコードのkeyを取得します。 .sp 対応するレコードが存在する場合はkey長を返します。見つからない場合は0を返します。対応するキーの検索に成功し、またbuf_sizeの長さがkey長以上であった場合は、keybufに該当するkeyをコピーします。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBid\fP \-\- 対象レコードのIDを指定します。 .IP \(bu 2 \fBkeybuf\fP \-\- keyを格納するバッファ(呼出側で準備する)を指定します。 .IP \(bu 2 \fBbuf_size\fP \-\- keybufのサイズ(byte長)を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_delete(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *key\fP, unsigned int\fI\ key_size\fP) tableのkeyに対応するレコードを削除します。対応するレコードが存在しない場合は \fBGRN_INVALID_ARGUMENT\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBkey\fP \-\- 検索keyを指定します。 .IP \(bu 2 \fBkey_size\fP \-\- 検索keyのサイズを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_delete_by_id(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, grn_id\fI\ id\fP) tableのidに対応するレコードを削除します。対応するレコードが存在しない場合は \fBGRN_INVALID_ARGUMENT\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBid\fP \-\- レコードIDを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_update_by_id(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, grn_id\fI\ id\fP, const void\fI\ *dest_key\fP, unsigned int\fI\ dest_key_size\fP) tableのidに対応するレコードのkeyを変更します。新しいkeyとそのbyte長をdest_keyとdest_key_sizeに指定します。 .sp この操作は、\fBGRN_TABLE_DAT_KEY\fP 型のテーブルのみ使用できます。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBid\fP \-\- レコードIDを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_update(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *src_key\fP, unsigned int\fI\ src_key_size\fP, const void\fI\ *dest_key\fP, unsigned int\fI\ dest_key_size\fP) tableのsrc_keyに対応するレコードのkeyを変更します。新しいkeyとそのbyte長をdest_keyとdest_key_sizeに指定します。 .sp この操作は、\fBGRN_TABLE_DAT_KEY\fP 型のテーブルのみ使用できます。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBsrc_key\fP \-\- 対象レコードのkeyを指定します。 .IP \(bu 2 \fBsrc_key_size\fP \-\- 対象レコードのkeyの長さ(byte)を指定します。 .IP \(bu 2 \fBdest_key\fP \-\- 変更後のkeyを指定します。 .IP \(bu 2 \fBdest_key_size\fP \-\- 変更後のkeyの長さ(byte)を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_truncate(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP) tableの全レコードを一括して削除します。 .sp 注意: multithread環境では他のthreadのアクセスによって、存在しないアドレスへアクセスし、SIGSEGVが発生する可能性があります。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_table_sort_key TODO... .UNINDENT .INDENT 0.0 .TP .B grn_table_sort_flags TODO... .UNINDENT .INDENT 0.0 .TP .B int grn_table_sort(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, int\fI\ offset\fP, int\fI\ limit\fP, grn_obj\fI\ *result\fP, grn_table_sort_key\fI\ *keys\fP, int\fI\ n_keys\fP) table内のレコードをソートし、上位limit個の要素をresultに格納します。 .sp keys.keyには、tableのcolumn,accessor,procのいずれかが指定できます。keys.flagsには、\fBGRN_TABLE_SORT_ASC\fP / \fBGRN_TABLE_SORT_DESC\fP のいずれかを指定できます。\fBGRN_TABLE_SORT_ASC\fP では昇順、\fBGRN_TABLE_SORT_DESC\fP では降順でソートされます。keys.offsetは、内部利用のためのメンバです。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBoffset\fP \-\- sortされたレコードのうち、(0ベースで)offset番目から順にresにレコードを格納します。 .IP \(bu 2 \fBlimit\fP \-\- resに格納するレコードの上限を指定します。 .IP \(bu 2 \fBresult\fP \-\- 結果を格納するtableを指定します。 .IP \(bu 2 \fBkeys\fP \-\- ソートキー配列へのポインタを指定します。 .IP \(bu 2 \fBn_keys\fP \-\- ソートキー配列のサイズを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_table_group_result TODO... .UNINDENT .INDENT 0.0 .TP .B grn_table_group_flags TODO... .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_group(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, grn_table_sort_key\fI\ *keys\fP, int\fI\ n_keys\fP, grn_table_group_result\fI\ *results\fP, int\fI\ n_results\fP) tableのレコードを特定の条件でグループ化します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBkeys\fP \-\- group化キー構造体の配列へのポインタを指定します。 .IP \(bu 2 \fBn_keys\fP \-\- group化キー構造体の配列のサイズを指定します。 .IP \(bu 2 \fBresults\fP \-\- group化の結果を格納する構造体の配列へのポインタを指定します。 .IP \(bu 2 \fBn_results\fP \-\- group化の結果を格納する構造体の配列のサイズを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_setoperation(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table1\fP, grn_obj\fI\ *table2\fP, grn_obj\fI\ *res\fP, grn_operator\fI\ op\fP) table1とtable2をopの指定に従って集合演算した結果をresに格納します。 .sp resにtable1あるいはtable2そのものを指定した場合を除けば、table1, table2は破壊されません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable1\fP \-\- 対象table1を指定します。 .IP \(bu 2 \fBtable2\fP \-\- 対象table2を指定します。 .IP \(bu 2 \fBres\fP \-\- 結果を格納するtableを指定します。 .IP \(bu 2 \fBop\fP \-\- 実行する演算の種類を指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_difference(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table1\fP, grn_obj\fI\ *table2\fP, grn_obj\fI\ *res1\fP, grn_obj\fI\ *res2\fP) table1とtable2から重複するレコードを取り除いた結果をそれぞれres1, res2に格納します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable1\fP \-\- 対象table1を指定します。 .IP \(bu 2 \fBtable2\fP \-\- 対象table2を指定します。 .IP \(bu 2 \fBres1\fP \-\- 結果を格納するtableを指定します。 .IP \(bu 2 \fBres2\fP \-\- 結果を格納するtableを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_table_columns(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP, grn_obj\fI\ *res\fP) nameパラメータから始まるtableのカラムIDをresパラメータに格納します。name_sizeパラメータが0の場合はすべてのカラムIDを格納します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBname\fP \-\- 取得したいカラム名のprefixを指定します。 .IP \(bu 2 \fBname_size\fP \-\- nameパラメータの長さを指定します。 .IP \(bu 2 \fBres\fP \-\- 結果を格納する \fBGRN_TABLE_HASH_KEY\fP のtableを指定します。 .UNINDENT .TP .B Returns 格納したカラムIDの数を返します。 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B unsigned int grn_table_size(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP) tableに登録されているレコードの件数を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_rename(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP) ctxが使用するdbにおいてtableに対応する名前をnameに更新します。tableの全てのcolumnも同時に名前が変更されます。tableは永続オブジェクトでなければいけません。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname_size\fP \-\- nameパラメータのsize(byte)を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_table_cursor\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_table_cursor TODO... .UNINDENT .INDENT 0.0 .TP .B grn_table_cursor *grn_table_cursor_open(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *table\fP, const void\fI\ *min\fP, unsigned int\fI\ min_size\fP, const void\fI\ *max\fP, unsigned int\fI\ max_size\fP, int\fI\ offset\fP, int\fI\ limit\fP, int\fI\ flags\fP) tableに登録されているレコードを順番に取り出すためのカーソルを生成して返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- 対象tableを指定します。 .IP \(bu 2 \fBmin\fP \-\- keyの下限を指定します。（NULLは下限なしと見なします。） \fBGRN_CURSOR_PREFIX\fP については後述。 .IP \(bu 2 \fBmin_size\fP \-\- minのsizeを指定します。\fBGRN_CURSOR_PREFIX\fP については後述。 .IP \(bu 2 \fBmax\fP \-\- keyの上限を指定します。（NULLは上限なしと見なします。） \fBGRN_CURSOR_PREFIX\fP については後述。 .IP \(bu 2 \fBmax_size\fP \-\- maxのsizeを指定します。\fBGRN_CURSOR_PREFIX\fP については無視される場合があります。 .IP \(bu 2 \fBflags\fP \-\- .sp \fBGRN_CURSOR_ASCENDING\fP を指定すると昇順にレコードを取り出します。 .sp \fBGRN_CURSOR_DESCENDING\fP を指定すると降順にレコードを取り出します。(下記 \fBGRN_CURSOR_PREFIX\fP を指定し、keyが近いレコードを取得する場合、もしくは、common prefix searchを行う場合には、\fBGRN_CURSOR_ASCENDING\fP / \fBGRN_CURSOR_DESCENDING\fP は無視されます。) .sp \fBGRN_CURSOR_GT\fP を指定するとminに一致したkeyをcursorの範囲に含みません。(minがNULLの場合もしくは、下記 \fBGRN_CURSOR_PREFIX\fP を指定し、keyが近いレコードを取得する場合、もしくは、common prefix searchを行う場合には、\fBGRN_CURSOR_GT\fP は無視されます。) .sp \fBGRN_CURSOR_LT\fP を指定するとmaxに一致したkeyをcursorの範囲に含みません。(maxがNULLの場合もしくは、下記 \fBGRN_CURSOR_PREFIX\fP を指定した場合には、\fBGRN_CURSOR_LT\fP は無視されます。) .sp \fBGRN_CURSOR_BY_ID\fP を指定するとID順にレコードを取り出します。(下記 \fBGRN_CURSOR_PREFIX\fP を指定した場合には、\fBGRN_CURSOR_BY_ID\fP は無視されます。) \fBGRN_OBJ_TABLE_PAT_KEY\fP を指定したtableについては、\fBGRN_CURSOR_BY_KEY\fP を指定するとkey順にレコードを取り出します。( \fBGRN_OBJ_TABLE_HASH_KEY\fP , \fBGRN_OBJ_TABLE_NO_KEY\fP を指定したテーブルでは \fBGRN_CURSOR_BY_KEY\fP は無視されます。) .sp \fBGRN_CURSOR_PREFIX\fP を指定すると、 \fBGRN_OBJ_TABLE_PAT_KEY\fP を指定したテーブルに関する下記のレコードを取り出すカーソルが作成されます。maxがNULLの場合には、keyがminと前方一致するレコードを取り出します。max_sizeパラメータは無視されます。 .sp maxとmax_sizeが指定され、かつ、テーブルのkeyがShortText型である場合、maxとcommon prefix searchを行い、common prefixがmin_sizeバイト以上のレコードを取り出します。minは無視されます。 .sp maxとmax_sizeが指定され、かつ、テーブルのkeyが固定長型の場合、maxとPAT木上で近い位置にあるノードから順番にレコードを取り出します。ただし、keyのパトリシア木で、min_sizeバイト未満のビットに対するノードで、maxと異なった方向にあるノードに対応するレコードについては取り出しません。PAT木上で位置が近いこととkeyの値が近いことは同一ではありません。この場合、maxで与えられるポインタが指す値は、対象テーブルのkeyサイズと同じか超える幅である必要があります。minは無視されます。 .sp \fBGRN_CURSOR_BY_ID\fP / \fBGRN_CURSOR_BY_KEY\fP / \fBGRN_CURSOR_PREFIX\fP の3フラグは、同時に指定することができません。 .sp \fBGRN_OBJ_TABLE_PAT_KEY\fP を指定して作ったテーブルで、\fBGRN_CURSOR_PREFIX\fP と \fBGRN_CURSOR_RK\fP を指定すると、半角小文字のアルファベット文字列から、それを旧JIS X 4063:2000規格に従って全角カタカナに変換した文字列に前方一致する値をkeyとするレコードを取り出します。\fBGRN_ENC_UTF8\fP のみをサポートしています。\fBGRN_CURSOR_ASCENDING\fP / \fBGRN_CURSOR_DESCENDING\fP は無効であり、レコードをkey値の昇降順で取り出すことはできません。 .IP \(bu 2 \fBoffset\fP \-\- .sp 該当する範囲のレコードのうち、(0ベースで)offset番目からレコードを取り出します。 .sp \fBGRN_CURSOR_PREFIX\fP を指定したときは負の数を指定することはできません。 .IP \(bu 2 \fBlimit\fP \-\- .sp 該当する範囲のレコードのうち、limit件のみを取り出します。\-1が指定された場合は、全件が指定されたものとみなします。 .sp \fBGRN_CURSOR_PREFIX\fP を指定したときは\-1より小さい負の数を指定することはできません。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_cursor_close(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP) \fBgrn_table_cursor_open()\fP で生成したcursorを解放します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_id grn_table_cursor_next(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP) cursorのカレントレコードを一件進めてそのIDを返します。cursorの対象範囲の末尾に達すると \fBGRN_ID_NIL\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_table_cursor_get_key(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP, void\fI\ **key\fP) cursorのカレントレコードのkeyをkeyパラメータにセットし、その長さを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .IP \(bu 2 \fBkey\fP \-\- カレントレコードのkeyへのポインタがセットされます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B int grn_table_cursor_get_value(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP, void\fI\ **value\fP) cursorパラメータのカレントレコードのvalueをvalueパラメータにセットし、その長さを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .IP \(bu 2 \fBvalue\fP \-\- カレントレコードのvalueへのポインタがセットされます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_cursor_set_value(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP, const void\fI\ *value\fP, int\fI\ flags\fP) cursorのカレントレコードのvalueを引数の内容に置き換えます。cursorのカレントレコードが存在しない場合は \fBGRN_INVALID_ARGUMENT\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .IP \(bu 2 \fBvalue\fP \-\- 新しいvalueの値を指定します。 .IP \(bu 2 \fBflags\fP \-\- \fBgrn_obj_set_value()\fP のflagsと同様の値を指定できます。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_table_cursor_delete(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP) cursorのカレントレコードを削除します。cursorのカレントレコードが存在しない場合は \fBGRN_INVALID_ARGUMENT\fP を返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_table_cursor_table(grn_ctx\fI\ *ctx\fP, grn_table_cursor\fI\ *tc\fP) cursorが属するtableを返します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtc\fP \-\- 対象cursorを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_type\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_builtin_type TODO... .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_type_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, unsigned int\fI\ name_size\fP, grn_obj_flags\fI\ flags\fP, unsigned int\fI\ size\fP) nameに対応する新たなtype（型）をdbに定義します。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- 作成するtypeの名前を指定します。 .IP \(bu 2 \fBflags\fP \-\- \fBGRN_OBJ_KEY_VAR_SIZE\fP, \fBGRN_OBJ_KEY_FLOAT\fP, \fBGRN_OBJ_KEY_INT\fP, \fBGRN_OBJ_KEY_UINT\fP のいずれかを指定します。 .IP \(bu 2 \fBsize\fP \-\- \fBGRN_OBJ_KEY_VAR_SIZE\fP の場合は最大長、それ以外の場合は長さ（単位:byte）を指定します。 .UNINDENT .UNINDENT .UNINDENT .SS \fBgrn_user_data\fP .SS Summary .sp TODO... .SS Example .sp TODO... .SS Reference .INDENT 0.0 .TP .B grn_user_data TODO... .UNINDENT .INDENT 0.0 .TP .B grn_user_data *grn_obj_user_data(grn_ctx\fI\ *ctx\fP, grn_obj\fI\ *obj\fP) objectに登録できるユーザデータへのポインタを返します。table, column, proc, exprのみ使用可能です。 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- 対象objectを指定します。 .UNINDENT .UNINDENT .UNINDENT .SS Plugin .SS Summary .sp Groonga supports plugin. You can create a new plugin with the following API. .sp TOOD: Describe about how to create the minimum plugin here or create a tutorial about it. .SS Reference .INDENT 0.0 .TP .B grn_rc GRN_PLUGIN_INIT(grn_ctx\fI\ *ctx\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc GRN_PLUGIN_REGISTER(grn_ctx\fI\ *ctx\fP) .UNINDENT .INDENT 0.0 .TP .B grn_rc GRN_PLUGIN_FIN(grn_ctx\fI\ *ctx\fP) .UNINDENT .INDENT 0.0 .TP .B GRN_PLUGIN_MALLOC(ctx, size) GRN_PLUGIN_MALLOC() allocates \fIsize\fP bytes and returns a pointer to the allocated memory space. Note that the memory space is associated with \fIctx\fP\&. .UNINDENT .INDENT 0.0 .TP .B GRN_PLUGIN_REALLOC(ctx, ptr, size) GRN_PLUGIN_REALLOC() resizes the memory space pointed to by \fIptr\fP or allocates a new memory space of \fIsize\fP bytes. GRN_PLUGIN_REALLOC() returns a pointer to the memory space. The contents is unchanged or copied from the old memory space to the new memory space. .UNINDENT .INDENT 0.0 .TP .B GRN_PLUGIN_FREE(ctx, ptr) GRN_PLUGIN_FREE() frees a memory space allocated by GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC(). This means that \fIptr\fP must be a pointer returned by GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC(). .UNINDENT .INDENT 0.0 .TP .B GRN_PLUGIN_LOG(ctx, level, \&...) GRN_PLUGIN_LOG() reports a log of \fIlevel\fP\&. Its error message is generated from the varying number of arguments, in which the first one is the format string and the rest are its arguments. See grn_log_level in "groonga.h" for more details of \fIlevel\fP\&. .UNINDENT .INDENT 0.0 .TP .B GRN_PLUGIN_ERROR(ctx, error_code, \&...) GRN_PLUGIN_ERROR() reports an error of \fIerror_code\fP\&. Its error message is generated from the varying number of arguments, in which the first one is the format string and the rest are its arguments. See grn_rc in "groonga.h" for more details of \fIerror_code\fP\&. .UNINDENT .INDENT 0.0 .TP .B grn_plugin_mutex grn_plugin_mutex is available to make a critical section. See the following functions. .UNINDENT .INDENT 0.0 .TP .B grn_plugin_mutex *grn_plugin_mutex_open(grn_ctx\fI\ *ctx\fP) grn_plugin_mutex_open() returns a pointer to a new object of grn_plugin_mutex. Memory for the new object is obtained with GRN_PLUGIN_MALLOC(). grn_plugin_mutex_open() returns NULL if sufficient memory is not available. .UNINDENT .INDENT 0.0 .TP .B void grn_plugin_mutex_close(grn_ctx\fI\ *ctx\fP, grn_plugin_mutex\fI\ *mutex\fP) grn_plugin_mutex_close() finalizes an object of grn_plugin_mutex and then frees memory allocated for that object. .UNINDENT .INDENT 0.0 .TP .B void grn_plugin_mutex_lock(grn_ctx\fI\ *ctx\fP, grn_plugin_mutex\fI\ *mutex\fP) grn_plugin_mutex_lock() locks a mutex object. If the object is already locked, the calling thread waits until the object will be unlocked. .UNINDENT .INDENT 0.0 .TP .B void grn_plugin_mutex_unlock(grn_ctx\fI\ *ctx\fP, grn_plugin_mutex\fI\ *mutex\fP) grn_plugin_mutex_unlock() unlocks a mutex object. grn_plugin_mutex_unlock() should not be called for an unlocked object. .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_plugin_proc_alloc(grn_ctx\fI\ *ctx\fP, grn_user_data\fI\ *user_data\fP, grn_id\fI\ domain\fP, grn_obj_flags\fI\ flags\fP) grn_plugin_proc_alloc() allocates a \fIgrn_obj\fP object. You can use it in function that is registered as GRN_PROC_FUNCTION. .UNINDENT .INDENT 0.0 .TP .B grn_obj grn_plugin_proc_get_var(grn_ctx\fI\ *ctx\fP, grn_user_data\fI\ *user_data\fP, const char\fI\ *name\fP, int\fI\ name_size\fP) It gets a variable value from \fIgrn_user_data\fP by specifying the variable name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The variable name. .IP \(bu 2 \fBname_size\fP \-\- The number of bytes of name. If \fIname_size\fP is negative, \fIname\fP must be NUL\-terminated. \fIname_size\fP is computed by \fIstrlen(name)\fP for the case. .UNINDENT .TP .B Returns A variable value on success, NULL otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj *grn_plugin_proc_get_var_by_offset(grn_ctx\fI\ *ctx\fP, grn_user_data\fI\ *user_data\fP, unsigned int\fI\ offset\fP) It gets a variable value from \fIgrn_user_data\fP by specifying the offset position of the variable. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBoffset\fP \-\- The offset position of the variable. .UNINDENT .TP .B Returns A variable value on success, NULL otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B const char *grn_plugin_win32_base_dir(void) grn_plugin_win32_base_dir() returns the groonga install directory. The install directory is computed from the directory that has \fIgroonga.dll\fP\&. You can use the directory to generate install directory aware path. It only works on Windows. It returns \fINULL\fP on other platforms. .UNINDENT .INDENT 0.0 .TP .B int grn_plugin_charlen(grn_ctx\fI\ *ctx\fP, const char\fI\ *str_ptr\fP, unsigned int\fI\ str_length\fP, grn_encoding\fI\ encoding\fP) grn_plugin_charlen() returns the length (#bytes) of the first character in the string specified by \fIstr_ptr\fP and \fIstr_length\fP\&. If the starting bytes are invalid as a character, grn_plugin_charlen() returns 0. See grn_encoding in "groonga.h" for more details of \fIencoding\fP\&. .UNINDENT .INDENT 0.0 .TP .B int grn_plugin_isspace(grn_ctx\fI\ *ctx\fP, const char\fI\ *str_ptr\fP, unsigned int\fI\ str_length\fP, grn_encoding\fI\ encoding\fP) grn_plugin_isspace() returns the length (#bytes) of the first character in the string specified by \fIstr_ptr\fP and \fIstr_length\fP if it is a space character. Otherwise, grn_plugin_isspace() returns 0. .UNINDENT .INDENT 0.0 .TP .B grn_rc grn_plugin_expr_var_init(grn_ctx\fI\ *ctx\fP, grn_expr_var\fI\ *var\fP, const char\fI\ *name\fP, int\fI\ name_size\fP) It initializes a \fIgrn_expr_var\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvar\fP \-\- The pointer of \fIgrn_expr_var\fP object to be initialized. .IP \(bu 2 \fBname\fP \-\- The name of \fIgrn_expr_var\fP object to be initialized. .IP \(bu 2 \fBname_size\fP \-\- The number of bytes of name. If \fIname_size\fP is negative, \fIname\fP must be NUL\-terminated. \fIname_size\fP is computed by \fIstrlen(name)\fP for the case. .UNINDENT .TP .B Returns \fBGRN_SUCCESS\fP\&. It doesn\(aqt fail. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B grn_obj * grn_plugin_command_create(grn_ctx\fI\ *ctx\fP, const char\fI\ *name\fP, int\fI\ name_size\fP, grn_proc_func\fI\ func\fP, unsigned int\fI\ n_vars\fP, grn_expr_var\fI\ *vars\fP) It creates a command. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The \fIproc\fP name of the command to be created. .IP \(bu 2 \fBname_size\fP \-\- The number of bytes of name. If \fIname_size\fP is negative, \fIname\fP must be NUL\-terminated. \fIname_size\fP is computed by \fIstrlen(name)\fP for the case. .IP \(bu 2 \fBfunc\fP \-\- The function name to be called by the created command. .IP \(bu 2 \fBn_vars\fP \-\- The number of the variables of the command to create. .IP \(bu 2 \fBvars\fP \-\- The pointer of initialized \fIgrn_expr_var\fP object. .UNINDENT .TP .B Returns The created command object if it creates a command successfully, \fINULL\fP otherwise. See \fIctx\fP for error details. .UNINDENT .UNINDENT .SH SPECIFICATION .SS GQTP .sp GQTP is the acronym of Groonga Query Transfer Protocol. GQTP is the original protocol for groonga. .SS Protocol .sp GQTP is stateful client server model protocol. The following sequence is one processing unit: .INDENT 0.0 .IP \(bu 2 Client sends a request .IP \(bu 2 Server receives the request .IP \(bu 2 Server processes the request .IP \(bu 2 Server sends a response .IP \(bu 2 Client receives the response .UNINDENT .sp You can do zero or more processing units in a session. .sp Both request and response consist of GQTP header and body. GQTP header is fixed size data. Body is variable size data and its size is stored in GQTP header. The content of body isn\(aqt defined in GQTP. .SS GQTP header .sp GQTP header consists of the following unsigned integer values: .TS center; |l|l|l|. _ T{ Name T} T{ Size T} T{ Description T} _ T{ \fBprotocol\fP T} T{ 1byte T} T{ Protocol type. T} _ T{ \fBquery_type\fP T} T{ 1byte T} T{ Content type of body. T} _ T{ \fBkey_length\fP T} T{ 2byte T} T{ Not used. T} _ T{ \fBlevel\fP T} T{ 1byte T} T{ Not used. T} _ T{ \fBflags\fP T} T{ 1byte T} T{ Flags. T} _ T{ \fBstatus\fP T} T{ 2byte T} T{ Return code. T} _ T{ \fBsize\fP T} T{ 4byte T} T{ Body size. T} _ T{ \fBopaque\fP T} T{ 4byte T} T{ Not used. T} _ T{ \fBcas\fP T} T{ 8byte T} T{ Not used. T} _ .TE .sp All header values are encoded by network byte order. .sp The following sections describes available values of each header value. .sp The total size of GQTP header is 24byte. .SS \fBprotocol\fP .sp The value is always \fB0xc7\fP in both request and response GQTP header. .SS \fBquery_type\fP .sp The value is one of the following values: .TS center; |l|l|l|. _ T{ Name T} T{ Value T} T{ Description T} _ T{ \fBNONE\fP T} T{ 0 T} T{ Free format. T} _ T{ \fBTSV\fP T} T{ 1 T} T{ Tab Separated Values. T} _ T{ \fBJSON\fP T} T{ 2 T} T{ JSON. T} _ T{ \fBXML\fP T} T{ 3 T} T{ XML. T} _ T{ \fBMSGPACK\fP T} T{ 4 T} T{ MessagePack. T} _ .TE .sp This is not used in request GQTP header. .sp This is used in response GQTP header. Body is formatted as specified type. .SS \fBflags\fP .sp The value is bitwise OR of the following values: .TS center; |l|l|l|. _ T{ Name T} T{ Value T} T{ Description T} _ T{ \fBMORE\fP T} T{ 0x01 T} T{ There are more data. T} _ T{ \fBTAIL\fP T} T{ 0x02 T} T{ There are no more data. T} _ T{ \fBHEAD\fP T} T{ 0x04 T} T{ Not used. T} _ T{ \fBQUIET\fP T} T{ 0x08 T} T{ Be quiet. T} _ T{ \fBQUIT\fP T} T{ 0x10 T} T{ Quit. T} _ .TE .sp You must specify \fBMORE\fP or \fBTAIL\fP flag. .sp If you use \fBMORE\fP flag, you should also use \fBQUIET\fP flag. Because you don\(aqt need to show a response for your partial request. .sp Use \fBQUIT\fP flag to quit this session. .SS \fBstatus\fP .sp Here are available values. The new statuses will be added in the future. .INDENT 0.0 .IP \(bu 2 0: \fBSUCCESS\fP .IP \(bu 2 1: \fBEND_OF_DATA\fP .IP \(bu 2 65535: \fBUNKNOWN_ERROR\fP .IP \(bu 2 65534: \fBOPERATION_NOT_PERMITTED\fP .IP \(bu 2 65533: \fBNO_SUCH_FILE_OR_DIRECTORY\fP .IP \(bu 2 65532: \fBNO_SUCH_PROCESS\fP .IP \(bu 2 65531: \fBINTERRUPTED_FUNCTION_CALL\fP .IP \(bu 2 65530: \fBINPUT_OUTPUT_ERROR\fP .IP \(bu 2 65529: \fBNO_SUCH_DEVICE_OR_ADDRESS\fP .IP \(bu 2 65528: \fBARG_LIST_TOO_LONG\fP .IP \(bu 2 65527: \fBEXEC_FORMAT_ERROR\fP .IP \(bu 2 65526: \fBBAD_FILE_DESCRIPTOR\fP .IP \(bu 2 65525: \fBNO_CHILD_PROCESSES\fP .IP \(bu 2 65524: \fBRESOURCE_TEMPORARILY_UNAVAILABLE\fP .IP \(bu 2 65523: \fBNOT_ENOUGH_SPACE\fP .IP \(bu 2 65522: \fBPERMISSION_DENIED\fP .IP \(bu 2 65521: \fBBAD_ADDRESS\fP .IP \(bu 2 65520: \fBRESOURCE_BUSY\fP .IP \(bu 2 65519: \fBFILE_EXISTS\fP .IP \(bu 2 65518: \fBIMPROPER_LINK\fP .IP \(bu 2 65517: \fBNO_SUCH_DEVICE\fP .IP \(bu 2 65516: \fBNOT_A_DIRECTORY\fP .IP \(bu 2 65515: \fBIS_A_DIRECTORY\fP .IP \(bu 2 65514: \fBINVALID_ARGUMENT\fP .IP \(bu 2 65513: \fBTOO_MANY_OPEN_FILES_IN_SYSTEM\fP .IP \(bu 2 65512: \fBTOO_MANY_OPEN_FILES\fP .IP \(bu 2 65511: \fBINAPPROPRIATE_I_O_CONTROL_OPERATION\fP .IP \(bu 2 65510: \fBFILE_TOO_LARGE\fP .IP \(bu 2 65509: \fBNO_SPACE_LEFT_ON_DEVICE\fP .IP \(bu 2 65508: \fBINVALID_SEEK\fP .IP \(bu 2 65507: \fBREAD_ONLY_FILE_SYSTEM\fP .IP \(bu 2 65506: \fBTOO_MANY_LINKS\fP .IP \(bu 2 65505: \fBBROKEN_PIPE\fP .IP \(bu 2 65504: \fBDOMAIN_ERROR\fP .IP \(bu 2 65503: \fBRESULT_TOO_LARGE\fP .IP \(bu 2 65502: \fBRESOURCE_DEADLOCK_AVOIDED\fP .IP \(bu 2 65501: \fBNO_MEMORY_AVAILABLE\fP .IP \(bu 2 65500: \fBFILENAME_TOO_LONG\fP .IP \(bu 2 65499: \fBNO_LOCKS_AVAILABLE\fP .IP \(bu 2 65498: \fBFUNCTION_NOT_IMPLEMENTED\fP .IP \(bu 2 65497: \fBDIRECTORY_NOT_EMPTY\fP .IP \(bu 2 65496: \fBILLEGAL_BYTE_SEQUENCE\fP .IP \(bu 2 65495: \fBSOCKET_NOT_INITIALIZED\fP .IP \(bu 2 65494: \fBOPERATION_WOULD_BLOCK\fP .IP \(bu 2 65493: \fBADDRESS_IS_NOT_AVAILABLE\fP .IP \(bu 2 65492: \fBNETWORK_IS_DOWN\fP .IP \(bu 2 65491: \fBNO_BUFFER\fP .IP \(bu 2 65490: \fBSOCKET_IS_ALREADY_CONNECTED\fP .IP \(bu 2 65489: \fBSOCKET_IS_NOT_CONNECTED\fP .IP \(bu 2 65488: \fBSOCKET_IS_ALREADY_SHUTDOWNED\fP .IP \(bu 2 65487: \fBOPERATION_TIMEOUT\fP .IP \(bu 2 65486: \fBCONNECTION_REFUSED\fP .IP \(bu 2 65485: \fBRANGE_ERROR\fP .IP \(bu 2 65484: \fBTOKENIZER_ERROR\fP .IP \(bu 2 65483: \fBFILE_CORRUPT\fP .IP \(bu 2 65482: \fBINVALID_FORMAT\fP .IP \(bu 2 65481: \fBOBJECT_CORRUPT\fP .IP \(bu 2 65480: \fBTOO_MANY_SYMBOLIC_LINKS\fP .IP \(bu 2 65479: \fBNOT_SOCKET\fP .IP \(bu 2 65478: \fBOPERATION_NOT_SUPPORTED\fP .IP \(bu 2 65477: \fBADDRESS_IS_IN_USE\fP .IP \(bu 2 65476: \fBZLIB_ERROR\fP .IP \(bu 2 65475: \fBLZO_ERROR\fP .IP \(bu 2 65474: \fBSTACK_OVER_FLOW\fP .IP \(bu 2 65473: \fBSYNTAX_ERROR\fP .IP \(bu 2 65472: \fBRETRY_MAX\fP .IP \(bu 2 65471: \fBINCOMPATIBLE_FILE_FORMAT\fP .IP \(bu 2 65470: \fBUPDATE_NOT_ALLOWED\fP .IP \(bu 2 65469: \fBTOO_SMALL_OFFSET\fP .IP \(bu 2 65468: \fBTOO_LARGE_OFFSET\fP .IP \(bu 2 65467: \fBTOO_SMALL_LIMIT\fP .IP \(bu 2 65466: \fBCAS_ERROR\fP .IP \(bu 2 65465: \fBUNSUPPORTED_COMMAND_VERSION\fP .UNINDENT .SS \fBsize\fP .sp The size of body. The maximum body size is 4GiB because \fBsize\fP is 4byte unsigned integer. If you want to send 4GiB or more larger data, use \fBMORE\fP flag. .SS Example .sp TODO .SS See also .sp TODO .SS 検索 .sp \fB/reference/commands/select\fP コマンドがqueryパラメータを使ってどのように検索するのかを説明します。 .SS 検索の挙動 .sp 検索の挙動には以下の3種類あり、検索結果によって動的に使い分けています。 .INDENT 0.0 .IP 1. 3 完全一致検索 .IP 2. 3 非わかち書き検索 .IP 3. 3 部分一致検索 .UNINDENT .sp どのように検索の挙動を使い分けているかを説明する前に、まず、それぞれの検索の挙動を説明します。 .SS 完全一致検索 .sp 検索対象文書は複数の語彙にトークナイズ(分割)され、それぞれを単位とした語彙表に索引を管理します。 検索キーワードも同一の方法でトークナイズされます。 .sp このとき、検索キーワードをトークナイズした結果得られる語彙の配列と同一の配列を含む文書を検索する処理を完全一致検索と呼んでいます。 .sp たとえば、TokenMecabトークナイザを使用した索引では「東京都民」という文字列は .INDENT 0.0 .INDENT 3.5 東京 / 都民 .UNINDENT .UNINDENT .sp という二つの語彙の配列として格納されます。この索引に対して「東京都」というキーワードで検索した時、このキーワードは、 .INDENT 0.0 .INDENT 3.5 東京 / 都 .UNINDENT .UNINDENT .sp という二つの語彙の配列として処理されます。この語彙の並びは、「東京 / 都民」という語彙の並びには一致しませんので、完全一致検索ではヒットしません。 .sp これに対して、TokenBigramトークナイザを使用した索引では「東京都民」という文字列は .INDENT 0.0 .INDENT 3.5 東京 / 京都 / 都民 / 民 .UNINDENT .UNINDENT .sp という四つの語彙の配列として格納されます。この索引に対して「東京都」というキーワードで検索した時、このキーワードは、 .INDENT 0.0 .INDENT 3.5 東京 / 京都 .UNINDENT .UNINDENT .sp という二つの語彙の配列として処理されます。この語彙の並びは、「東京 / 京都 / 都民」という語彙の並びに含まれますので、完全一致検索でヒットします。 .sp なお、TokenBigramトークナイザでは、アルファベット・数値・記号文字列についてはbigramを生成せず、一つの連続したトークンとして扱います。たとえば、「楽しいbilliard」という文字列は、 .INDENT 0.0 .INDENT 3.5 楽し / しい / billiard .UNINDENT .UNINDENT .sp という三つの語彙の配列として格納されます。これに対して「bill」というキーワードで検索した時、このキーワードは、 .INDENT 0.0 .INDENT 3.5 bill .UNINDENT .UNINDENT .sp という一つの語彙として処理されます。この語彙の並びは「楽し / しい / billiard」という語彙の並びには含まれないので、完全一致でヒットしません。 .sp これに対して、TokenBigramSplitSymbolAlphaトークナイザではアルファベット文字列についてもbigramを生成し、「楽しいbilliard」という文字列は、 .INDENT 0.0 .INDENT 3.5 楽し / しい / いb / bi / il / ll / li / ia / ar / rd / d .UNINDENT .UNINDENT .sp という十一の語彙の配列として格納されます。これに対して「bill」というキーワードで検索した時、このキーワードは、 .INDENT 0.0 .INDENT 3.5 bi / il / ll .UNINDENT .UNINDENT .sp という三つの語彙として処理されます。この語彙の並びは「楽し / しい / いb / bi / il / ll / li / ia / ar / rd / d」という語彙の並びに含まれるので、完全一致でヒットします。 .SS 非わかち書き検索 .sp 非わかち書き検索はパトリシア木で語彙表を構築している場合のみ利用可能です。 .sp 非わかち書き検索の挙動はTokenBigramなどN\-gram系のトークナイザーを利用している場合とTokenMecabトークナイザーを利用している場合で挙動が変わります。 .sp N\-gram系のトークナイザーを利用している場合はキーワードで前方一致検索をします。 .sp 例えば、「bill」というキーワードで検索した場合、「bill」も「billiard」もヒットします。 .sp TokenMeCabトークナイザーの場合はわかち書き前のキーワードで前方一致検索をします。 .sp 例えば、「スープカレー」というキーワードで検索した場合、「スープカレーバー」（1単語扱い）にヒットしますが、「スープカレー」（"スープ"と"カレー"の2単語扱い）や「スープカレーライス」（"スープ"と"カレーライス"の2単語扱い）にはヒットしません。 .SS 部分一致検索 .sp 部分一致検索はパトリシア木で語彙表を構築していて、かつ、KEY_WITH_SISオプションを指定している場合のみ利用可能です。KEY_WITH_SISオプションが指定されていない場合は非わかち書き検索と同等です。 .sp 部分一致検索の挙動はTokenBigramなどN\-gram系のトークナイザーを利用している場合とTokenMecabトークナイザーを利用している場合で挙動が変わります。 .sp Bigramの場合は前方一致検索と中間一致検索と後方一致検索を行います。 .sp 例えば、「ill」というキーワードで検索した場合、「bill」も「billiard」もヒットします。 .sp TokenMeCabトークナイザーの場合はわかち書き後のキーワードで前方一致検索と中間一致検索と後方一致検索をします。 .sp 例えば、「スープカレー」というキーワードで検索した場合、「スープカレー」（"スープ"と"カレー"の2単語扱い）や「スープカレーライス」（"スープ"と"カレーライス"の2単語扱い）、「スープカレーバー」（1単語扱い）にもヒットします。 .SS 検索の使い分け .sp groongaは基本的に完全一致検索のみを行います。完全一致検索でのヒット件数が所定の閾値以下の場合に限り、非わかち書き検索を行い、それでもヒット件数が閾値以下の場合は部分一致検索を行います。（閾値のデフォルト値は0です。） .sp ただし、すでに検索結果セットが存在する場合はたとえヒット件数が閾値以下でも完全一致検索のみを行います。 .sp 例えば、以下のようなクエリの場合は、それぞれの検索でヒット件数が閾値以下の場合は完全一致検索、非わかち書き検索、部分一致検索を順に行います。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Shops \-\-match_column description \-\-query スープカレー .ft P .fi .UNINDENT .UNINDENT .sp しかし、以下のように全文検索を行う前に検索結果セットが存在する場合は完全一致検索のみを行います。（point > 3で閾値の件数よりヒットしている場合）: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Shops \-\-filter \(aq"point > 3 && description @ \e"スープカレー\e""\(aq .ft P .fi .UNINDENT .UNINDENT .sp そのため、descriptionに「スープカレーライス」が含まれていても、「スープカレーライス」は「スープカレー」に完全一致しないのでヒットしません。 .SH LIMITATIONS .sp Groonga has some limitations. .SS Limitations of table .sp A table has the following limitations. .INDENT 0.0 .IP \(bu 2 The maximum one key size: 4096Bytes .IP \(bu 2 The maximum total size of keys: 4GBytes .UNINDENT .sp Keep in mind that these limitations may vary depending on conditions. .SS Limitations of indexing .sp A full\-text index has the following limitations. .INDENT 0.0 .IP \(bu 2 The maximum number of records: 268,435,455 (more than 268 million) .IP \(bu 2 The maximum number of distinct terms: 268,435,455 (more than 268 million) .IP \(bu 2 The maximum index size: 256GBytes .UNINDENT .sp Keep in mind that these limitations may vary depending on conditions. .SS Limitations of column .sp A column has the following limitation. .INDENT 0.0 .IP \(bu 2 The maximum stored data size of each column: 256GiB .UNINDENT .SH トラブルシューティング .SS 同じ検索キーワードなのに全文検索結果が異なる .sp 同じ検索キーワードでも一緒に指定するクエリによっては全文検索の結果が異なることがあります。ここでは、その原因と対策方法を説明します。 .SS 例 .sp まず、実際に検索結果が異なる例を説明します。 .sp DDLは以下の通りです。BlogsテーブルのbodyカラムをTokenMecabトークナイザーを使ってトークナイズしてからインデックスを作成しています。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Blogs TABLE_NO_KEY column_create Blogs body COLUMN_SCALAR ShortText column_create Blogs updated_at COLUMN_SCALAR Time table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenMecab column_create Terms blog_body COLUMN_INDEX|WITH_POSITION Blogs body .ft P .fi .UNINDENT .UNINDENT .sp テスト用のデータは1件だけ投入します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load \-\-table Blogs [ ["body", "updated_at"], ["東京都民に深刻なダメージを与えました。", "2010/9/21 10:18:34"], ] .ft P .fi .UNINDENT .UNINDENT .sp まず、全文検索のみで検索します。この場合ヒットします。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > select Blogs \-\-filter \(aqbody @ "東京都"\(aq [[0,4102.268052438,0.000743783],[[[1],[["_id","UInt32"],["updated_at","Time"],["body","ShortText"]],[1,1285031914.0,"東京都民に深刻なダメージを与えました。"]]]] .ft P .fi .UNINDENT .UNINDENT .sp 続いて、範囲指定と全文検索を組み合わせて検索します（1285858800は2010/10/1 0:0:0の秒表記）。この場合もヒットします。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > select Blogs \-\-filter \(aqbody @ "東京都" && updated_at < 1285858800\(aq [[0,4387.524084839,0.001525487],[[[1],[["_id","UInt32"],["updated_at","Time"],["body","ShortText"]],[1,1285031914.0,"東京都民に深刻なダメージを与えました。"]]]] .ft P .fi .UNINDENT .UNINDENT .sp 最後に、範囲指定と全文検索の順番を入れ替えて検索します。個々の条件は同じですが、この場合はヒットしません。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > select Blogs \-\-filter \(aqupdated_at < 1285858800 && body @ "東京都"\(aq [[0,4400.292570838,0.000647716],[[[0],[["_id","UInt32"],["updated_at","Time"],["body","ShortText"]]]]] .ft P .fi .UNINDENT .UNINDENT .sp どうしてこのような挙動になるかを説明します。 .SS 原因 .sp このような挙動になるのは全文検索時に複数の検索の挙動を使い分けているからです。ここでは簡単に説明するので、詳細は \fB/spec/search\fP を参照してください。 .sp 検索の挙動には以下の3種類があります。 .INDENT 0.0 .IP 1. 3 完全一致検索 .IP 2. 3 非わかち書き検索 .IP 3. 3 部分一致検索 .UNINDENT .sp groongaは基本的に完全一致検索のみを行います。上記の例では「東京都民に深刻なダメージを与えました。」を「東京都」というクエリで検索していますが、TokenMecabトークナイザーを使っている場合はこのクエリはマッチしません。 .sp 検索対象の「東京都民に深刻なダメージを与えました。」は .INDENT 0.0 .INDENT 3.5 東京 / 都民 / に / 深刻 / な / ダメージ / を / 与え / まし / た / 。 .UNINDENT .UNINDENT .sp とトークナイズされますが、クエリの「東京都」は .INDENT 0.0 .INDENT 3.5 東京 / 都 .UNINDENT .UNINDENT .sp とトークナイズされるため、完全一致しません。 .sp groongaは完全一致検索した結果のヒット件数が所定の閾値を超えない場合に限り、非わかち書き検索を行い、それでもヒット件数が閾値を超えない場合は部分一致検索を行います（閾値は1がデフォルト値となっています）。このケースのデータは部分一致検索ではヒットするので、「東京都」クエリのみを指定するとヒットします。 .sp しかし、以下のように全文検索前にすでに閾値が越えている場合（「updated_at < 1285858800」で1件ヒットし、閾値を越える）は、たとえ完全一致検索で1件もヒットしない場合でも部分一致検索などを行いません。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C select Blogs \-\-filter \(aqupdated_at < 1285858800 && body @ "東京都"\(aq .ft P .fi .UNINDENT .UNINDENT .sp そのため、条件の順序を変えると検索結果が変わるという状況が発生します。以下で、この情報を回避する方法を2種類紹介しますが、それぞれトレードオフとなる条件があるので採用するかどうかを十分検討してください。 .SS 対策方法1: トークナイザーを変更する .sp TokenMecabトークナイザーは事前に準備した辞書を用いてトークナイズするため、再現率よりも適合率を重視したトークナイザーと言えます。一方、TokenBigramなど、N\-gram系のトークナイザーは適合率を重視したトークナイザーと言えます。例えば、TokenMecabの場合「東京都」で「京都」に完全一致することはありませんが、TokenBigramでは完全一致します。一方、TokenMecabでは「東京都民」に完全一致しませんが、TokenBigramでは完全一致します。 .sp このようにN\-gram系のトークナイザーを指定することにより再現率をあげることができますが、適合率が下がり検索ノイズが含まれる可能性が高くなります。この度合いを調整するためには \fB/reference/commands/select\fP のmatch_columnsで使用する索引毎に重み付けを指定します。 .sp ここでも、前述の例を使って具体例を示します。まず、TokenBigramを用いた索引を追加します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C table_create Bigram TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram column_create Bigram blog_body COLUMN_INDEX|WITH_POSITION Blogs body .ft P .fi .UNINDENT .UNINDENT .sp この状態でも以前はマッチしなかったレコードがヒットするようになります。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > select Blogs \-\-filter \(aqupdated_at < 1285858800 && body @ "東京都"\(aq [[0,7163.448064902,0.000418127],[[[1],[["_id","UInt32"],["updated_at","Time"],["body","ShortText"]],[1,1285031914.0,"東京都民に深刻なダメージを与えました。"]]]] .ft P .fi .UNINDENT .UNINDENT .sp しかし、N\-gram系のトークナイザーの方がTokenMecabトークナイザーよりも語のヒット数が多いため、N\-gram系のヒットスコアの方が重く扱われてしまいます。N\-gram系のトークナイザーの方がTokenMecabトークナイザーよりも適合率の低い場合が多いので、このままでは検索ノイズが上位に表示される可能性が高くなります。 .sp そこで、TokenMecabトークナイザーを使って作った索引の方をTokenBigramトークナイザーを使って作った索引よりも重視するように重み付けを指定します。これは、match_columnsオプションで指定できます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C > select Blogs \-\-match_columns \(aqTerms.blog_body * 10 || Bigram.blog_body * 3\(aq \-\-query \(aq東京都\(aq \-\-output_columns \(aq_score, body\(aq [[0,8167.364602632,0.000647003],[[[1],[["_score","Int32"],["body","ShortText"]],[13,"東京都民に深刻なダメージを与えました。"]]]] .ft P .fi .UNINDENT .UNINDENT .sp この場合はスコアが11になっています。内訳は、Terms.blog_body索引（TokenMecabトークナイザーを使用）でマッチしたので10、Bigram.blog_body索引（TokenBigramトークナイザーを使用）でマッチしたので3、これらを合計して13になっています。このようにTokenMecabトークナイザーの重みを高くすることにより、検索ノイズが上位にくることを抑えつつ再現率を上げることができます。 .sp この例は日本語だったのでTokenBigramトークナイザーでよかったのですが、アルファベットの場合はTokenBigramSplitSymbolAlphaトークナイザーなども利用する必要があります。例えば、「楽しいbilliard」はTokenBigramトークナイザーでは .INDENT 0.0 .INDENT 3.5 楽し / しい / billiard .UNINDENT .UNINDENT .sp となり、「bill」では完全一致しません。一方、TokenBigramSplitSymbolAlphaトークナイザーを使うと .INDENT 0.0 .INDENT 3.5 楽し / しい / いb / bi / il / ll / li / ia / ar / rd / d .UNINDENT .UNINDENT .sp となり、「bill」でも完全一致します。 .sp TokenBigramSplitSymbolAlphaトークナイザーを使う場合も重み付けを考慮する必要があることはかわりありません。 .sp 利用できるバイグラム系のトークナイザーの一覧は以下の通りです。 .INDENT 0.0 .IP \(bu 2 TokenBigram: バイグラムでトークナイズする。連続する記号・アルファベット・数字は一語として扱う。 .IP \(bu 2 TokenBigramSplitSymbol: 記号もバイグラムでトークナイズする。連続するアルファベット・数字は一語として扱う。 .IP \(bu 2 TokenBigramSplitSymbolAlpha: 記号とアルファベットもバイグラムでトークナイズする。連続する数字は一語として扱う。 .IP \(bu 2 TokenBigramSplitSymbolAlphaDigit: 記号・アルファベット・数字もバイグラムでトークナイズする。 .IP \(bu 2 TokenBigramIgnoreBlank: バイグラムでトークナイズする。連続する記号・アルファベット・数字は一語として扱う。空白は無視する。 .IP \(bu 2 TokenBigramIgnoreBlankSplitSymbol: 記号もバイグラムでトークナイズする。連続するアルファベット・数字は一語として扱う。空白は無視する。 .IP \(bu 2 TokenBigramIgnoreBlankSplitSymbolAlpha: 記号とアルファベットもバイグラムでトークナイズする。連続する数字は一語として扱う。空白は無視する。 .IP \(bu 2 TokenBigramIgnoreBlankSplitSymbolAlphaDigit: 記号・アルファベット・数字もバイグラムでトークナイズする。空白は無視する。 .UNINDENT .SS 対策方法2: 閾値をあげる .sp 非わかち書き検索・部分一致検索を利用するかどうかの閾値は\-\-with\-match\-escalation\-threshold configureオプションで変更することができます。以下のように指定すると、100件以下のヒット数であれば、たとえ完全一致検索でヒットしても、非わかち書き検索・部分一致検索を行います。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-with\-match\-escalation\-threashold=100 .ft P .fi .UNINDENT .UNINDENT .sp この場合も対策方法1同様、検索ノイズが上位に現れる可能性が高くなることに注意してください。検索ノイズが多くなった場合は指定する値を低くする必要があります。 .SS How to avoid mmap Cannot allocate memory error .SS Example .sp There is a case following mmap error in log file: .INDENT 0.0 .INDENT 3.5 2013\-06\-04 08:19:34.835218|A|4e86e700|mmap(4194304,551,432017408)=Cannot allocate memory <13036498944> .UNINDENT .UNINDENT .sp Note that <13036498944> means total size of mmap (almost 12GB) in this case. .SS Solution .sp So you need to confirm following point of views. .INDENT 0.0 .IP \(bu 2 Are there enough free memory? .IP \(bu 2 Are maximum number of mappings exceeded? .UNINDENT .sp To check there are enough free memory, you can use vmstat command. .sp To check whether maximum number of mappings are exceeded, you can investigate the value of vm.max_map_count. .sp If this issue is fixed by modifying the value of vm.max_map_count, it\(aqs exactly the reason. .sp As groonga allocates memory chunks each 256KB, you can estimate the size of database you can handle by following formula: .INDENT 0.0 .INDENT 3.5 (database size) = vm.max_map_count * (memory chunks) .UNINDENT .UNINDENT .sp If you want to handle over 16GB groonga database, you must specify at least 65536 as the value of vm.max_map_count: .INDENT 0.0 .INDENT 3.5 database size (16GB) = vm.max_map_count (65536) * memory chunks (256KB) .UNINDENT .UNINDENT .sp You can modify vm.max_map_count temporary by sudo sysctl \-w vm.max_map_count=65536. .sp Then save the configuration value to \fB/etc/sysctl.conf\fP or \fB/etc/sysctl.d/*.conf\fP\&. .sp See \fB/reference/tuning\fP documentation about tuning related parameters. .SH DEVELOPMENT .sp This section describes about developing with Groonga. You may develop an application that uses Groonga as its database, a library that uses libgroonga, language bindings of libgroonga and so on. .SS Travis CI .sp This section describes about using Groonga on \fI\%Travis CI\fP\&. Travis CI is a hosted continuous integration service for the open source community. .sp You can use Travis CI for your open source software. This section only describes about Groonga related configuration. See \fI\%Travis CI: Documentation\fP about general Travis CI. .SS Configuration .sp Travis CI is running on 64\-bit Ubuntu 12.04 LTS Server Edition. (See \fI\%Travis CI: About Travis CI Environment\fP\&.) You can use apt\-line for Ubuntu 12.04 LTS provided by Groonga project to install Groonga on Travis CI. .sp You can custom build lifecycle by \fB\&.travis.yml\fP\&. (See \fI\%Travis CI: Conifugration your Travis CI build with .travis.yml\fP\&.) You can use \fBbefore_install\fP hook or \fBinstall\fP hook. You should use \fBbefore_install\fP if your software uses a language that is supported by Travis CI such as Ruby. You should use \fBinstall\fP otherwise. .sp Add the following \fBbefore_install\fP configuration to \fB\&.travis.yml\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C before_install: \- curl \-\-silent \-\-location https://github.com/groonga/groonga/raw/master/data/travis/setup.sh | sh .ft P .fi .UNINDENT .UNINDENT .sp If you need to use \fBinstall\fP hook instead of \fBbefore_install\fP, you just substitute \fBbefore_install:\fP with \fBinstall:\fP\&. .sp With the above configuration, you can use Groonga for your build. .SS Examples .sp Here are open source softwares that use Groonga on Travis CI: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%rroonga\fP (Ruby bindings) .INDENT 2.0 .IP \(bu 2 \fI\%rroonga on Travis CI\fP .IP \(bu 2 \fI\%\&.travis.yml for rroonga\fP .UNINDENT .IP \(bu 2 \fI\%nroonga\fP (node.js bindings) .INDENT 2.0 .IP \(bu 2 \fI\%nroonga on Travis CI\fP .IP \(bu 2 \fI\%\&.travis.yml for nroonga\fP .UNINDENT .IP \(bu 2 \fI\%logaling\-command\fP (A glossary management command line tool) .INDENT 2.0 .IP \(bu 2 \fI\%logaling\-command on Travis CI\fP .IP \(bu 2 \fI\%\&.travis.yml for logaling\-command\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SH HOW TO CONTRIBUTE TO GROONGA .sp We welcome your contributions to the groonga project. There are many ways to contribute, such as using groonga, introduction to others, etc. For example, if you find a bug when using groonga, you are welcome to report the bug. Coding and documentation are also welcome for groonga and its related projects. .INDENT 0.0 .TP .B As a user: If you are interested in groonga, please read this document and try it. .TP .B As a spokesman: Please introduce groonga to your friends and colleagues. .TP .B As a developer: Bug report, development and documentation This section describes the details. .UNINDENT .SS How to report a bug .sp There are two ways to report a bug: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Submit a bug to the issue tracker .IP \(bu 2 Report a bug to the mailing list .UNINDENT .UNINDENT .UNINDENT .sp You can use either way It makes no difference to us. .SS Submit a bug to the issue tracker .sp Groonga project uses \fI\%GitHub issue tracker\fP\&. .sp You can use English or Japanese to report a bug. .SS Report a bug to the mailing list .sp Groonga project has \fB/community\fP for discussing about groonga. Please send a mail that describes a bug. .SS How to contribute in documentation topics .sp We use \fI\%Sphinx\fP for documentation tool. .SS Introduction .sp This documentation describes about how to write, generate and manage Groonga documentation. .SS Install depended softwares .sp Groonga uses \fI\%Sphinx\fP as documentation tool. Groonga requires newer Sphinx. So Groonga clones the latest Sphinx from Sphinx repository automatically. You need only \fI\%Mercurial\fP, \fI\%Docutils\fP and \fI\%Jinja\fP\&. .sp Here are command lines to install needed softwares. .sp Debian GNU/Linux, Ubuntu: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-V \-y mercurial python\-docutils python\-jinja2 .ft P .fi .UNINDENT .UNINDENT .sp CentOS, Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo yum install \-y mercurial python\-docutils python\-jinja2 .ft P .fi .UNINDENT .UNINDENT .sp OS X: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % brew install mercurial % pip install docutils % pip install jinja .ft P .fi .UNINDENT .UNINDENT .SS Run \fBconfigure\fP with \fB\-\-enable\-document\fP .sp Groonga disables documentation generation by default. You need to enable it explicitly by adding \fB\-\-enable\-document\fP option to \fBconfigure\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure \-\-enable\-document .ft P .fi .UNINDENT .UNINDENT .sp Now, your Groonga build is documentation ready. .SS Generate HTML .sp You can generate HTML by the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-C doc html .ft P .fi .UNINDENT .UNINDENT .sp You can find generated HTML documentation at \fBdoc/locale/en/html/\fP\&. .SS Update .sp You can find sources of documentation at \fBdoc/source/\fP\&. The sources should be written in English. See \fBi18n\fP about how to translate documentation. .sp You can update the target file when you update the existing documentation file. .sp You need to update file list after you add a new file, change file path and delete existing file. You can update file list by the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-C doc update\-files .ft P .fi .UNINDENT .UNINDENT .sp The command updates \fBdoc/files.am\fP\&. .SS I18N .sp We only had documentation in Japanese. We start to support I18N documentation by gettext based \fI\%Sphinx I18N feature\fP\&. We\(aqll use English as base language and translate English into other languages such as Japanese. We\(aqll put all documentations into doc/source/ and process them by Sphinx. .sp But we still use Japanese in doc/source/ for now. We need to translate Japanese documentation in doc/source/ into English. We welcome to you help us by translating documentation. .SS Translation flow .sp After doc/source/*.txt are updated, we can start translation. .sp Here is a translation flow: .INDENT 0.0 .IP 1. 3 Clone groonga repository. .IP 2. 3 Update .po files. .IP 3. 3 Edit .po files. .IP 4. 3 Generate HTML files. .IP 5. 3 Confirm HTML output. .IP 6. 3 Repeat 2.\-4. until you get good result. .IP 7. 3 Send your works to us! .UNINDENT .sp Here are command lines to do the above flow. Following sections describes details. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Please fork https://github.com/groonga/groonga on GitHub % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git % ./autogen.sh % ./configure % cd doc/locale/${LANGUAGE}/LC_MESSAGES # ${LANGUAGE} is language code such as \(aqja\(aq. % make update # *.po are updated % editor *.po # translate *.po # you can use your favorite editor % cd .. % make html % browser html/index.html # confirm translation % git add LC_MESSAGES/*.po % git commit % git push .ft P .fi .UNINDENT .UNINDENT .SS How to clone groonga repository .sp First, please fork groonga repository on GitHub. You just access \fI\%https://github.com/groonga/groonga\fP and press \fIFork\fP button. Now you can clone your groonga repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git .ft P .fi .UNINDENT .UNINDENT .sp Then you need to configure your cloned repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd groonga % ./autogen.sh % ./configure .ft P .fi .UNINDENT .UNINDENT .sp The above steps are just needed at the first setup. .sp If you have troubles on the above steps, you can use source files available on \fI\%http://packages.groonga.org/source/groonga/\fP . .SS How to update .po files .sp You can update .po files by running \fImake update\fP on doc/locale/${LANGUAGE}/LC_MESSAGES. (Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq.): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd doc/locale/ja/LC_MESSAGES % make update .ft P .fi .UNINDENT .UNINDENT .SS How to edit .po .sp There are some tools to edit .po files. .po files are just text. So you can use your favorite editor. Here is a specialized editor for .po file edit list. .INDENT 0.0 .TP .B Emacs\(aqs \fI\%po\-mode\fP It is bundled in gettext. .TP .B \fI\%Poedit\fP It is a .po editor and works on many platform. .TP .B gted It is also a .po editor and is implemented as Eclipse plugin. .UNINDENT .SS How to generate HTML files .sp You can generate HTML files with updated .po files by running \fImake html\fP on doc/locale/${LANGUAGE}. (Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq.): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd doc/locale/ja/ % make html .ft P .fi .UNINDENT .UNINDENT .sp You can also generate HTML files for all languages by running \fImake html\fP on doc/locale: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd doc/locale % make html .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \&.mo files are updated automatically by \fImake html\fP\&. So you don\(aqt care about .mo files. .UNINDENT .UNINDENT .SS How to confirm HTML output .sp HTML files are generated in doc/locale/${LANGUAGE}/html/. (Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq.) You can confirm HTML output by your favorite browser: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % firefox doc/locale/ja/html/index.html .ft P .fi .UNINDENT .UNINDENT .SS How to send your works .sp We can receive your works via pull request on GitHub or E\-mail attachment patch or .po files themselves. .SS How to send pull request .sp Here are command lines to send pull request: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git add doc/locale/ja/LC_MESSAGES/*.po % git commit % git push .ft P .fi .UNINDENT .UNINDENT .sp Now you can send pull request on GitHub. You just access your repository page on GitHub and press \fIPull Request\fP button. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Help.GitHub \- Sending pull requests\fP\&. .UNINDENT .UNINDENT .SS How to send patch .sp Here are command lines to create patch: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git add doc/locale/ja/LC_MESSAGES/*.po % git commit % git format\-patch origin/master .ft P .fi .UNINDENT .UNINDENT .sp You can find 000X\-YYY.patch files in the current directory. Please send those files to us! .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fB/community\fP describes our contact information. .UNINDENT .UNINDENT .SS How to send .po files .sp Please archive doc/locale/${LANGUAGE}/LC_MESSAGES/ (Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq.) and send it to us! We extract and merge them to the groonga repository. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fB/community\fP describes our contact information. .UNINDENT .UNINDENT .SS How to add new language .sp Here are command lines to add new translation language: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd doc/locale % make add LOCALE=${LANGUAGE} # specify your language code such as \(aqde\(aq. .ft P .fi .UNINDENT .UNINDENT .sp Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Codes for the Representation of Names of Languages\fP\&. .UNINDENT .UNINDENT .SS C API .sp We still have C API documentation in include/groonga.h. But we want to move them into doc/source/c\-api/*.txt. We welcome to you help us by moving C API documentation. .sp We will use \fI\%the C domain markup\fP of Sphinx. .SS Groonga開発者向け情報 .SS Repository .sp There is \fI\%the repository of groonga on GitHub\fP\&. If you want to check\-out groonga, type the below command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git clone git://github.com/groonga/groonga.git .ft P .fi .UNINDENT .UNINDENT .sp There is \fI\%the list of related projects of groonga\fP (grntest, fluent\-plugin\-groonga and so on). .SS Groonga 通信アーキテクチャ .SS GQTPでのアーキテクチャ .INDENT 0.0 .IP \(bu 2 comが外部からの接続を受け付ける。 .IP \(bu 2 comは1スレッド。 .IP \(bu 2 comがedgeを作る。 .IP \(bu 2 edgeは接続と１対１対応。 .IP \(bu 2 edgeはctxを含む。 .IP \(bu 2 workerはthreadと１対１対応。 .IP \(bu 2 workerは上限が個定数。 .IP \(bu 2 workerは、１つのedgeと結びつくことができる。 .IP \(bu 2 edgeごとにqueueを持つ。 .IP \(bu 2 msgはcomによって、edgeのqueueにenqueueされる。 edgeがworkerに結びついていないときは、同時に、ctx_newというqueueに、msgをenqueueした対象のedgeをenqueueする。 .UNINDENT .SS ユーザーと協力して開発をうまく進めていくための指針 .sp Groongaを使ってくれているユーザーと協力して 開発をうまく進めていくためにこうするといい、という事柄をまとめました。 まとめておくと、新しく開発に加わる人とも共有することができます。 .SS twitter編 .sp Groongaを使ってもらえるようにtwitterのアカウントGroongaを取得して 日々、リリースの案内をしたり、ユーザーサポートをしたりしています。 .sp リリースの案内に利用する場合には、やりとりを考えなくて良いですが、 複数人によるサポートをGroongaで行う場合に、どうサポートするのが 良いのか/どうしてそうするのかという共通認識を持っていないと一貫性のないサポートとなってしま います。 .sp twitterでサポートされている安心感からGroongaユーザーの拡大に繋げる ことができるようにサポートの際に気をつけることをまとめます。 .SS 過去のツイートはおさらいしておく .SS 理由 .sp 自分がツイートした内容を把握していない返信をされたら普通いい気はしません。 .SS 対応 .sp 過去のツイートをおさらいし、こうすれば良いという提案をできるのが望ましいです。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 良い例: ○○だと原因は□□ですね。××すると大丈夫です。 .ft P .fi .UNINDENT .UNINDENT .SS こちらから情報を提供する .SS 理由 .sp 困っているユーザーが複数回ツイートして限られたなかで情報を提供してくれていることがあります。 その限られたツイートから解決方法が見つかればユーザーにとって余計な手間が少なくて済みます。 あれこれ情報提供を要求すると、ユーザーはそのぶん確認する作業が必要になります。 .SS 対応 .sp 最初に声をかけるときに解決策を1つか2つ提案できると望ましいです。ユーザーにあまり負担を感じさせないようにすると良いです。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 良い例: ○○の場合は□□の可能性があるので、××を試してもらえますか？ .ft P .fi .UNINDENT .UNINDENT .SS twitterでのやりとりはできるだけ他の場所(例えばredmine)へと誘導しない .SS 理由 .sp twitterは気軽につぶやけることが重要なので、気軽にできないことを相手に要求すると萎縮されてしまう可能性があります。 .sp いきなりredmineでバグ報告をお願いすると、しりごみしてしまうかも知れません。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 駄目な例: 再現手順をMLかredmineに報告してもらえますか? .ft P .fi .UNINDENT .UNINDENT .sp Groonga関連で気軽につぶやけないとなると開発者は困っている人を見つけられないし、利用者は困ったままとなるので、双方にとって嬉しくない状態になっ てしまいます。 .SS 対応 .sp twitterでやりとりを完結できるようにします。 .SS クエリの実現 .sp Groongaのデータベースには大量のデータを格納し、その中から必要な部分を高速に取り出すことができます。必要な部分をGroongaのデータベースに問い合わせるためのクエリの表現と実行に関して、Groongaは複数の手段を用意しています。 .SS クエリ実行のためのインタフェース .sp Groongaは低機能で単純なライブラリインタフェースから、高機能で複雑なコマンドインタフェースまでいくつかの階層的なインタフェースをユーザプログラムに提供しています。 .sp クエリ実行のためのインタフェースも階層的なインタフェースのそれぞれに対応する形で用意されています。以下に低レイヤなインタフェースから順に説明します。 .SS DB_API .sp DB_APIは、Groongaデータベースを操作するための一群のC言語向けAPI関数を提供します。DB_APIはデータベースを構成する個々の部分に対する単純な操作関数を提供します。DB_APIの機能を組み合わせることによって複雑なクエリを実行することができます。後述のすべてのクエリインタフェースはDB_APIの機能を組み合わせることによって実現されています。 .SS grn_expr .sp grn_exprは、Groongaデータベースに対する検索処理や更新処理のための条件を表現するためのデータ構造で、複数の条件を再帰的に組み合わせてより複雑な条件を表現することができます。grn_exprによって表現されたクエリを実行するためには、grn_table_select()関数を使用します。 .SS Groonga実行ファイル .sp Groongaデータベースを操作するためのコマンドインタープリタです。渡されたコマンドを解釈し、実行結果を返します。コマンドの実処理はC言語で記述されます。ユーザがC言語で定義した関数を新たなコマンドとしてGroonga実行ファイルに組み込むことができます。各コマンドはいくつかの文字列引数を受け取り、これをクエリとして解釈して実行します。引数をgrn_exprとして解釈するか、別の形式として解釈してDB_APIを使ってデータベースを操作するかはコマンド毎に自由に決めることができます。 .SS grn_exprで表現できるクエリ .sp grn_exprは代入や関数呼び出しのような様々な操作を表現できますが、この中で検索クエリを表現するgrn_exprのことを特に条件式とよびます。条件式を構成する個々の要素を関係式と呼びます。条件式は一個以上の関係式か、あるいは条件式を論理演算子で結合したものです。 .sp 論理演算子は、以下の3種類があります。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C && (論理積) || (論理和) ! (否定) .ft P .fi .UNINDENT .UNINDENT .sp 関係式は、下記の11種類が用意されています。また、ユーザが定義した関数を新たな関係式として使うこともできます。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C equal(==) not_equal(!=) less(<) greater(>) less_equal(<=) greater_equal(>=) contain() near() similar() prefix() suffix() .ft P .fi .UNINDENT .UNINDENT .SS grn_table_select() .sp grn_table_select()関数は、grn_exprで表現された検索クエリを実行するときに使います。引数として、検索対象となるテーブル、クエリを表すgrn_expr、検索結果を格納するテーブル、それに検索にマッチしたレコードを検索結果にどのように反映するかを指定する演算子を渡します。演算子と指定できるのは下記の4種類です。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GRN_OP_OR GRN_OP_AND GRN_OP_BUT GRN_OP_ADJUST .ft P .fi .UNINDENT .UNINDENT .sp GRN_OP_ORは、検索対象テーブルの中からクエリにマッチするレコードを検索結果テーブルに加えます。GRN_OP_OR以外の演算子は、検索結果テーブルが空でない場合にだけ意味を持ちます。GRN_OP_ANDは、検索結果テーブルの中からクエリにマッチしないレコードを取り除きます。GRN_OP_BUTは、検索結果テーブルの中からクエリにマッチするレコードを取り除きます。GRN_OP_ADJUSTは、検索結果テーブルの中でクエリにマッチするレコードに対してスコア値の更新のみを行います。 .sp grn_table_select()は、データベース上に定義されたテーブルや索引などを組み合わせて可能な限り高速に指定されたクエリを実行しようとします。 .SS 関係式 .sp 関係式は、検索しようとしているデータが満たすべき条件を、指定した値の間の関係として表現します。いずれの関係式も、その関係が成り立ったときに評価されるcallback、コールバック関数に渡されるargとを引数として指定することができます。callbackが与えられず、argのみが数値で与えられた場合はスコア値の係数とみなされます。主な関係式について説明します。 .SS equal(v1, v2, arg, callback) .sp v1の値とv2の値が等しいことを表します。 .SS not_equal(v1, v2, arg, callback) .sp v1の値とv2の値が等しくないことを表します。 .SS less(v1, v2, arg, callback) .sp v1の値がv2の値よりも小さいことを表します。 .SS greater(v1, v2, arg, callback) .sp v1の値がv2の値よりも大きいことを表します。 .SS less_equal(v1, v2, arg, callback) .sp v1の値がv2の値と等しいか小さいことを表します。 .SS greater_equal(v1, v2, arg, callback) .sp v1の値がv2の値と等しいか大きいことを表します。 .SS contain(v1, v2, mode, arg, callback) .sp v1の値がv2の値を含んでいることを表します。また、v1の値が要素に分解されるとき、それぞれの要素に対して二つ目の要素が一致するためのmodeとして下記のいずれかを指定することができます。 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C EXACT: v2の値もv1の値と同様に要素に分解したとき、それぞれの要素が完全に一致する(デフォルト) UNSPLIT: v2の値は要素に分解しない PREFIX: v1の値の要素がv2の値に前方一致する SUFFIX: v1の値の要素がv2の値に後方一致する PARTIAL: v1の値の要素がv2の値に中間一致する .ft P .fi .UNINDENT .UNINDENT .SS near(v1, v2, arg, callback) .sp v1の値の中に、v2の値の要素が接近して含まれていることを表します。(v2には値の配列を渡します) .SS similar(v1, v2, arg, callback) .sp v1の値とv2の値が類似していることを表します。 .SS prefix(v1, v2, arg, callback) .sp v1の値がv2の値に対して前方一致することを表します。 .SS suffix(v1, v2, arg, callback) .sp v1の値がv2の値に対して後方一致することを表します。 .SS クエリの実例 .sp grn_exprを使って様々な検索クエリを表現することができます。 .SS 検索例1 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 3); result = grn_table_select(ctx, table, query, NULL, GRN_OP_OR); .ft P .fi .UNINDENT .UNINDENT .sp tableのcolumnの値がstringを含むレコードをresultに返します。columnの値が\(aqneedle in haystack\(aqであるレコードr1と、columnの値が\(aqhaystack\(aqであるレコードr2がtableに登録されていたとき、stringに\(aqneedle\(aqを指定したなら、レコードr1のみがヒットします。 .SS 検索例2 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column1, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, exact, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, score1, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 5); result = grn_table_select(ctx, table, query, NULL, GRN_OP_OR); grn_obj_close(ctx, query); GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column2, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, exact, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, score2, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 5); grn_table_select(ctx, table, query, result, GRN_OP_ADJUST); grn_obj_close(ctx, query); .ft P .fi .UNINDENT .UNINDENT .sp tableのcolumn1の値がstringにexactモードでヒットするレコードについて得られるスコア値にscore1を積算してresultにセットします。次に、resultにセットされたレコードのうち、column2の値がstringにexactモードでヒットするレコードについては、得られたスコア値にscore2を積算したものを、元のスコア値に加えます。 .SS 検索例3 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column1, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, exact, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, score1, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 5); result = grn_table_select(ctx, table, query, NULL, GRN_OP_OR); grn_obj_close(ctx, query); if (grn_table_size(ctx, result) < t1) { GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column1, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, partial, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, score2, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 3); grn_table_select(ctx, table, query, result, GRN_OP_OR); grn_obj_close(ctx, query); } .ft P .fi .UNINDENT .UNINDENT .sp tableのcolumn1の値がstringにexactモードでヒットするレコードについて得られるスコア値にscore1を積算してresultにセットします。得られた検索結果数がt1よりも小さい場合は、partialモードで再度検索し、ヒットしたレコードについて得られるスコア値にscore2を積算してresultに追加します。 .SS 検索例4 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GRN_EXPR_CREATE_FOR_QUERY(ctx, table, query, var); grn_expr_append_obj(ctx, query, contain, GRN_OP_PUSH, 1); grn_expr_append_const(ctx, query, string, GRN_OP_PUSH, 1); grn_expr_append_obj(ctx, query, column, GRN_OP_PUSH, 1); grn_expr_append_op(ctx, query, GRN_OP_CALL, 3); result = grn_table_select(ctx, table, query, NULL, GRN_OP_OR); .ft P .fi .UNINDENT .UNINDENT .sp tableのcolumnの値がstringに含まれるレコードをresultに返します。 columnの値が\(aqneedle\(aqであるレコードr1と、columnの値が\(aqhaystack\(aqであるレコードr2がtableに登録されていたとき、stringに\(aqhay in haystack\(aqを指定したなら、レコードr2のみがヒットします。 .SS リリース手順 .SS 前提条件 .sp リリース手順の前提条件は以下の通りです。 .INDENT 0.0 .IP \(bu 2 ビルド環境は Ubuntu 12.04 LTS(Precise Pangolin) .IP \(bu 2 コマンドラインの実行例はzsh .UNINDENT .sp 作業ディレクトリ例は以下を使用します。 .INDENT 0.0 .IP \(bu 2 GROONGA_DIR=$HOME/work/groonga .IP \(bu 2 GROONGA_CLONE_DIR=$HOME/work/groonga/groonga.clean .IP \(bu 2 GROONGA_GITHUB_COM_PATH=$HOME/work/groonga/groonga.github.com .IP \(bu 2 CUTTER_DIR=$HOME/work/cutter .IP \(bu 2 CUTTER_SOURCE_PATH=$HOME/work/cutter/cutter .UNINDENT .SS ビルド環境の準備 .sp 以下にGroongaのリリース作業を行うために事前にインストール しておくべきパッケージを示します。 .sp なお、ビルド環境としては Ubuntu 12.04 LTS(Precise Pangolin)を前提として説明しているため、その他の環境では適宜読み替えて下さい。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo apt\-get install \-V debootstrap rinse createrepo rpm mercurial python\-docutils python\-jinja2 ruby1.9.1\-full mingw\-w64 g++\-mingw\-w64 mecab libmecab\-dev nsis gnupg2 .ft P .fi .UNINDENT .UNINDENT .sp rinseのバージョンが古いとCentOS 5/6パッケージのビルドを行うことができません。 別途debパッケージを以下のコマンドを実行して最新版をインストールします。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo dpkg \-i rinse_1.9.2\-1_all.deb .ft P .fi .UNINDENT .UNINDENT .sp また、rubyのrakeパッケージを以下のコマンドによりインストールします。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo gem1.9.1 install rake .ft P .fi .UNINDENT .UNINDENT .SS パッケージ署名用秘密鍵のインポート .sp リリース作業ではRPMパッケージに対する署名を行います。 その際、パッケージ署名用の鍵が必要です。 .sp Groongaプロジェクトでは署名用の鍵をリリース担当者の公開鍵で暗号化してリポジトリのpackages/ディレクトリ以下へと登録しています。 .sp リリース担当者はリポジトリに登録された秘密鍵を復号した後に鍵のインポートを以下のコマンドにて行います。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages % gpg \-\-decrypt release\-key\-secret.asc.gpg.(担当者) > (復号した鍵 ファイル) % gpg \-\-import (復号した鍵ファイル) .ft P .fi .UNINDENT .UNINDENT .sp 鍵のインポートが正常終了すると gpg \-\-list\-keys でGroongaの署名用の鍵を確認することができます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pub 1024R/F10399C0 2012\-04\-24 uid groonga Key (groonga Official Signing Key) sub 1024R/BC009774 2012\-04\-24 .ft P .fi .UNINDENT .UNINDENT .sp 鍵をインポートしただけでは使用することができないため、インポートした鍵に対してtrust,signを行う必要があります。 .sp 以下のコマンドを実行して署名を行います。(途中の選択肢は省略): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % gpg \-\-edit\-key packages@groonga.org gpg> trust gpg> sign gpg> save gpg> quit .ft P .fi .UNINDENT .UNINDENT .sp この作業は、新規にリリースを行うことになった担当者やパッケージに署名する鍵に変更があった場合などに行います。 .SS リリース作業用ディレクトリの作成 .sp Groongaのリリース作業ではリリース専用の環境下(コンパイルフラグ)でビルドする必要があります。 .sp リリース時と開発時でディレクトリを分けずに作業することもできますが、誤ったコンパイルフラグでリリースしてしまう危険があります。 .sp そのため、以降の説明では$GROONGA_DIR以下のディレクトリにリリース用の作業ディレクトリ(groonga.clean)としてソースコードをcloneしたものとして説明します。 .sp リリース用のクリーンな状態でソースコードを取得するために$GROONGA_DIRにて以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git clone git@github.com:groonga/groonga.git groonga.clean .ft P .fi .UNINDENT .UNINDENT .sp この作業はリリース作業ごとに行います。 .SS 変更点のまとめ .sp 前回リリース時からの変更点を$GROONGA_CLONE_DIR/doc/source/news.txtにまとめます。 ここでまとめた内容についてはリリースアナウンスにも使用します。 .sp 前回リリースからの変更履歴を参照するには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git log \-p \-\-reverse $(git tag | tail \-1).. .ft P .fi .UNINDENT .UNINDENT .sp ログを^commitで検索しながら、以下の基準を目安として変更点を追記していきます。 .sp 含めるもの .INDENT 0.0 .IP \(bu 2 ユーザへ影響するような変更 .IP \(bu 2 互換性がなくなるような変更 .UNINDENT .sp 含めないもの .INDENT 0.0 .IP \(bu 2 内部的な変更(変数名の変更やらリファクタリング) .UNINDENT .SS Groongaのウェブサイトの取得 .sp GroongaのウェブサイトのソースはGroonga同様にgithubにリポジトリを置いています。 .sp リリース作業では後述するコマンド(make update\-latest\-release)にてトップページのバージョンを置き換えることができるようになっています。 .sp Groongaのウェブサイトのソースコードを$GROONGA_GITHUB_COM_PATHとして取得するためには、$GROONGA_DIRにて以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git clone git@github.com:groonga/groonga.github.com.git .ft P .fi .UNINDENT .UNINDENT .sp これで、$GROONGA_GITHUB_COM_PATHにgroonga.github.comのソースを取得できます。 .SS cutterのソースコード取得 .sp Groongaのリリース作業では、cutterに含まれるスクリプトを使用しています。 .sp そこであらかじめ用意しておいた$HOME/work/cutterディレクトリにてcutterのソースコードを以下のコマンドにて取得します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % git clone git@github.com:clear\-code/cutter.git .ft P .fi .UNINDENT .UNINDENT .sp これで、$CUTTER_SOURCE_PATHディレクトリにcutterのソースを取得できます。 .SS configureスクリプトの生成 .sp Groongaのソースコードをcloneした時点ではconfigureスクリプトが含まれておらず、そのままmakeコマンドにてビルドすることができません。 .sp $GROONGA_CLONE_DIRにてautogen.shを以下のように実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sh autogen.sh .ft P .fi .UNINDENT .UNINDENT .sp このコマンドの実行により、configureスクリプトが生成されます。 .SS configureスクリプトの実行 .sp Makefileを生成するためにconfigureスクリプトを実行します。 .sp リリース用にビルドするためには以下のオプションを指定してconfigureを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure CFLAGS="\-O0 \-ggdb3" CXXFLAGS="\-O0 \-ggdb3" \-\-prefix=/tmp/local \-\-with\-rsync\-path="packages@packages.groonga.org:public" \-\-with\-groonga\-github\-com\-path=$HOME/work/groonga/groonga.github.com \-\-enable\-document \-\-with\-ruby19 \-\-with\-cutter\-source\-path=$HOME/work/cutter/cutter .ft P .fi .UNINDENT .UNINDENT .sp configureオプションである\-\-with\-groonga\-github\-com\-pathにはGroongaのウェブサイトのリポジトリをcloneした場所を指定します。 .sp configureオプションである\-\-with\-cutter\-source\-pathにはcutterのソースをcloneした場所を指定します。 .sp 以下のようにGroongaのソースコードをcloneした先からの相対パスを指定することもできます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./configure CFLAGS="\-O0 \-ggdb3" CXXFLAGS="\-O0 \-ggdb3" \-\-prefix=/tmp/local \-\-with\-rsync\-path="packages@packages.groonga.org:public" \-\-with\-groonga\-github\-com\-path=../groonga.github.com \-\-enable\-document \-\-with\-ruby19 \-\-with\-cutter\-source\-path=../../cutter/cutter .ft P .fi .UNINDENT .UNINDENT .sp あらかじめpackagesユーザでpackages.groonga.orgにsshログインできることを確認しておいてください。 .sp ログイン可能であるかの確認は以下のようにコマンドを実行して行います。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ssh packages@packages.groonga.org .ft P .fi .UNINDENT .UNINDENT .SS make update\-latest\-releaseの実行 .sp make update\-latest\-releaseコマンドでは、OLD_RELEASE_DATEに前回のリリースの日付を、NEW_RELEASE_DATEに次回リリースの日付を指定します。 .sp 2.0.2のリリースを行った際は以下のコマンドを実行しました。:: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-latest\-release OLD_RELEASE=2.0.1 OLD_RELEASE_DATE=2012\-03\-29 NEW_RELEASE_DATE=2012\-04\-29 .ft P .fi .UNINDENT .UNINDENT .sp これにより、clone済みのGroongaのWebサイトのトップページのソース(index.html,ja/index.html)やRPMパッケージのspecファイルのバージョン表記などが更新されます。 .SS make update\-filesの実行 .sp ロケールメッセージの更新や変更されたファイルのリスト等を更新するために以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-files .ft P .fi .UNINDENT .UNINDENT .sp make update\-filesを実行すると新規に追加されたファイルなどが各種.amファイルへとリストアップされます。 .sp リリースに必要なファイルですので漏れなくコミットします。 .SS make update\-poの実行 .sp ドキュメントの最新版と各国語版の内容を同期するために、poファイルの更新を以下のコマンドにて実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-po .ft P .fi .UNINDENT .UNINDENT .sp make update\-poを実行すると、doc/locale/ja/LC_MESSAGES以下の各種.poファイルが更新されます。 .SS poファイルの翻訳 .sp make update\-poコマンドの実行により更新した各種.poファイルを翻訳します。 .sp 翻訳結果をHTMLで確認するために、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make \-C doc/locale/ja html % make \-C doc/locale/en html .ft P .fi .UNINDENT .UNINDENT .sp 確認が完了したら、翻訳済みpoファイルをコミットします。 .SS リリースタグの設定 .sp リリース用のタグを打つには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make tag .ft P .fi .UNINDENT .UNINDENT .SS リリース用アーカイブファイルの作成 .sp リリース用のソースアーカイブファイルを作成するために以下のコマンドを$GROONGA_CLONE_DIRにて実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make dist .ft P .fi .UNINDENT .UNINDENT .sp これにより$GROONGA_CLONE_DIR/groonga\-(バージョン).tar.gzが作成されます。 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 タグを打つ前にmake distを行うとversionが古いままになることがあります。 するとgroonga \-\-versionで表示されるバージョン表記が更新されないので注意が必要です。 make distで生成したtar.gzのversionおよびversion.shがタグと一致することを確認するのが望ましいです。 .UNINDENT .UNINDENT .SS パッケージのビルド .sp リリース用のアーカイブファイルができたので、パッケージ化する作業を行います。 .sp パッケージ化作業は以下の3種類を対象に行います。 .INDENT 0.0 .IP \(bu 2 Debian系(.deb) .IP \(bu 2 Red Hat系(.rpm) .IP \(bu 2 Windows系(.exe,.zip) .UNINDENT .sp パッケージのビルドではいくつかのサブタスクから構成されています。 .SS ビルド用パッケージのダウンロード .sp debパッケージのビルドに必要なパッケージをダウンロードするには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/apt % make download .ft P .fi .UNINDENT .UNINDENT .sp これにより、lucid以降の関連する.debパッケージやソースアーカイブなどがカレントディレクトリ以下へとダウンロードされます。 .sp rpmパッケージのビルドに必要なパッケージをダウンロードするには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/yum % make download .ft P .fi .UNINDENT .UNINDENT .sp これにより、GroongaやMySQLのRPM/SRPMパッケージなどがカレントディレクトリ以下へとダウンロードされます。 .sp windowsパッケージのビルドに必要なパッケージをダウンロードするには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/windows % make download .ft P .fi .UNINDENT .UNINDENT .sp これにより、Groongaのインストーラやzipアーカイブがカレントディレクトリ以下へとダウンロードされます。 .sp sourceパッケージに必要なものをダウンロードするには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/source % make download .ft P .fi .UNINDENT .UNINDENT .sp これにより過去にリリースしたソースアーカイブ(.tar.gz)が packages/source/filesディレクトリ以下へとダウンロードされます。 .SS Debian系パッケージのビルド .sp Groongaのpackages/aptサブディレクトリに移動して、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/apt % make build PALALLEL=yes .ft P .fi .UNINDENT .UNINDENT .sp make build PALALLEL=yesコマンドを実行すると、ディストリビューションのリリースとアーキテクチャの組み合わせでビルドを平行して行うことができます。 .sp 現在サポートされているのは以下の通りです。 .INDENT 0.0 .IP \(bu 2 squeeze i386/amd64 .IP \(bu 2 wheezy i386/amd64 .IP \(bu 2 unstable i386/amd64 .IP \(bu 2 lucid i386/amd64 .IP \(bu 2 natty i386/amd64 .IP \(bu 2 oneiric i386/amd64 .IP \(bu 2 precise i386/amd64 .IP \(bu 2 quantal i386/amd64 .UNINDENT .sp 正常にビルドが終了すると$GROONGA_CLONE_DIR/packages/apt/repositories配下に.debパッケージが生成されます。 .sp make build ではまとめてビルドできないこともあります。 その場合にはディストリビューションごとやアーキテクチャごとなど、個別にビルドすることで問題が発生している箇所を切り分ける必要があります。 .sp 生成したパッケージへの署名を行うには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make sign\-packages .ft P .fi .UNINDENT .UNINDENT .sp リリース対象のファイルをリポジトリに反映するには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-repository .ft P .fi .UNINDENT .UNINDENT .sp リポジトリにGnuPGで署名を行うために以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make sign\-repository .ft P .fi .UNINDENT .UNINDENT .SS Red Hat系パッケージのビルド .sp Groongaのpackages/yumサブディレクトリに移動して、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/yum % make build PALALLES=yes .ft P .fi .UNINDENT .UNINDENT .sp make build PALALLEL=yesコマンドを実行すると、ディストリビューションのリリースとアーキテクチャの組み合わせでビルドを平行して行うことができます。 .sp 現在サポートされているのは以下の通りです。 .INDENT 0.0 .IP \(bu 2 centos\-5 i386/x86_64 .IP \(bu 2 centos\-6 i386/x86_64 .IP \(bu 2 fedora\-17 i386/x86_64 .UNINDENT .sp ビルドが正常終了すると$GROONGA_CLONE_DIR/packages/yum/repositories配下にRPMパッケージが生成されます。 .INDENT 0.0 .IP \(bu 2 repositories/yum/centos/5/i386/Packages .IP \(bu 2 repositories/yum/centos/5/x86_64/Packages .IP \(bu 2 repositories/yum/centos/6/i386/Packages .IP \(bu 2 repositories/yum/centos/6/x86_64/Packages .IP \(bu 2 repositories/yum/fedora/17/i386/Packages .IP \(bu 2 repositories/yum/fedora/17/x86_64/Packages .UNINDENT .sp リリース対象のRPMに署名を行うには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make sign\-packages .ft P .fi .UNINDENT .UNINDENT .sp リリース対象のファイルをリポジトリに反映するには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-repository .ft P .fi .UNINDENT .UNINDENT .SS Windows用パッケージのビルド .sp packages/windowsサブディレクトリに移動して、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/windows % make build % make package % make installer .ft P .fi .UNINDENT .UNINDENT .sp make releaseを実行することでbuildからuploadまで一気に実行することができますが、途中で失敗することもあるので順に実行することをおすすめします。 .sp make buildでクロスコンパイルを行います。 正常に終了するとdist\-x64/dist\-x86ディレクトリ以下にx64/x86バイナリを作成します。 .sp make packageが正常に終了するとzipアーカイブをfilesディレクトリ以下に作成します。 .sp make installerが正常に終了するとWindowsインストーラをfilesディレクトリ以下に作成します。 .SS パッケージの動作確認 .sp ビルドしたパッケージに対しリリース前の動作確認を行います。 .sp Debian系もしくはRed Hat系の場合には本番環境へとアップロードする前にローカルのaptないしyumのリポジトリを参照して正常に更新できることを確認します。 .sp ここでは以下のようにrubyを利用してリポジトリをwebサーバ経由で参照できるようにします。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ruby1.9.1 \-run \-e httpd \-\- packages/yum/repositories (yumの場合) % ruby1.9.1 \-run \-e httpd \-\- packages/apt/repositories (aptの場合) .ft P .fi .UNINDENT .UNINDENT .SS grntestの準備 .sp grntestを実行するためにはGroongaのテストデータとgrntestのソースが必要です。 .sp まずGroongaのソースを任意のディレクトリへと展開します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % tar zxvf groonga\-(バージョン).tar.gz .ft P .fi .UNINDENT .UNINDENT .sp 次にGroongaのtest/functionディレクトリ以下にgrntestのソースを展開します。 つまりtest/function/grntestという名前でgrntestのソースを配置します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ls test/function/grntest/ README.md binlib license test .ft P .fi .UNINDENT .UNINDENT .SS grntestの実行方法 .sp grntestではGroongaコマンドを明示的にしていすることができます。 後述のパッケージごとのgrntestによる動作確認では以下のようにして実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % GROONGA=(groongaのパス指定) test/function/run\-test.sh .ft P .fi .UNINDENT .UNINDENT .sp 最後にgrntestによる実行結果が以下のようにまとめて表示されます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 55 tests, 52 passes, 0 failures, 3 not checked tests. 94.55% passed. .ft P .fi .UNINDENT .UNINDENT .sp grntestでエラーが発生しないことを確認します。 .SS Debian系の場合 .sp Debian系の場合の動作確認手順は以下の通りとなります。 .INDENT 0.0 .IP \(bu 2 旧バージョンをchroot環境へとインストールする .IP \(bu 2 chroot環境の/etc/hostsを書き換えてpackages.groonga.orgがホストを 参照するように変更する .IP \(bu 2 ホストでwebサーバを起動してドキュメントルートをビルド環境のもの (repositories/apt/packages)に設定する .IP \(bu 2 アップグレード手順を実行する .IP \(bu 2 grntestのアーカイブを展開してインストールしたバージョンでテストを実 行する .IP \(bu 2 grntestの正常終了を確認する .UNINDENT .SS Red Hat系の場合 .sp Red Hat系の場合の動作確認手順は以下の通りとなります。 .INDENT 0.0 .IP \(bu 2 旧バージョンをchroot環境へとインストール .IP \(bu 2 chroot環境の/etc/hostsを書き換えてpackages.groonga.orgがホストを参照するように変更する .IP \(bu 2 ホストでwebサーバを起動してドキュメントルートをビルド環境のもの(packages/yum/repositories)に設定する .IP \(bu 2 アップグレード手順を実行する .IP \(bu 2 grntestのアーカイブを展開してインストールしたバージョンでテストを実行する .IP \(bu 2 grntestの正常終了を確認する .UNINDENT .SS Windows向けの場合 .INDENT 0.0 .IP \(bu 2 新規インストール/上書きインストールを行う .IP \(bu 2 grntestのアーカイブを展開してインストールしたバージョンでテストを実行する .IP \(bu 2 grntestの正常終了を確認する .UNINDENT .sp zipアーカイブも同様にしてgrntestを実行し動作確認を行います。 .SS リリースアナウンスの作成 .sp リリースの際にはリリースアナウンスを流して、Groongaを広く通知します。 .sp news.txtに変更点をまとめましたが、それを元にリリースアナウンスを作成します。 .sp リリースアナウンスには以下を含めます。 .INDENT 0.0 .IP \(bu 2 インストール方法へのリンク .IP \(bu 2 リリースのトピック紹介 .IP \(bu 2 リリース変更点へのリンク .IP \(bu 2 リリース変更点(news.txtの内容) .UNINDENT .sp リリースのトピック紹介では、これからGroongaを使う人へアピールする点や既存のバージョンを利用している人がアップグレードする際に必要な情報を提供します。 .sp 非互換な変更が含まれるのであれば、回避方法等の案内を載せることも重要です。 .sp 参考までに過去のリリースアナウンスへのリンクを以下に示します。 .INDENT 0.0 .IP \(bu 2 [Groonga\-talk] [ANN] Groonga 2.0.2 .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://sourceforge.net/mailarchive/message.php?msg_id=29195195\fP .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 [groonga\-dev,00794] [ANN] Groonga 2.0.2 .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%http://sourceforge.jp/projects/groonga/lists/archive/dev/2012\-April/000794.html\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS パッケージのアップロード .sp 動作確認が完了し、Debian系、Red Hat系、Windows向け、ソースコードそれぞれにおいてパッケージやアーカイブのアップロードを行います。 .sp Debian系のパッケージのアップロードには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/apt % make upload .ft P .fi .UNINDENT .UNINDENT .sp Red Hat系のパッケージのアップロードには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/yum % make upload .ft P .fi .UNINDENT .UNINDENT .sp Windows向けのパッケージのアップロードには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/windows % make upload .ft P .fi .UNINDENT .UNINDENT .sp ソースアーカイブのアップロードには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % cd packages/source % make upload .ft P .fi .UNINDENT .UNINDENT .sp アップロードが正常終了すると、リリース対象のリポジトリデータやパッケージ、アーカイブ等がpackages.groonga.orgへと反映されます。 .SS blogroonga(ブログ)の更新 .sp \fI\%http://groonga.org/blog/\fP および \fI\%http://groonga.org/blog/\fP にて公開されているリリース案内を作成します。 .sp 基本的にはリリースアナウンスの内容をそのまま記載します。 .sp cloneしたWebサイトのソースに対して以下のファイルを新規追加します。 .INDENT 0.0 .IP \(bu 2 groonga.github.com/en/_post/(リリース日)\-release.textile .IP \(bu 2 groonga.github.com/ja/_post/(リリース日)\-release.textile .UNINDENT .sp 編集した内容をpushする前に確認したい場合にはjekyllおよびRedClothが必要です。 インストールするには以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo gem1.9.1 install jekyll RedCloth .ft P .fi .UNINDENT .UNINDENT .sp jekyllのインストールを行ったら、以下のコマンドでローカルにwebサーバを起動します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % jekyll serve \-\-watch .ft P .fi .UNINDENT .UNINDENT .sp あとはブラウザにてhttp://localhost:4000にアクセスして内容に問題がないかを確認します。 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 記事を非公開の状態でアップロードするには.textileファイルのpublished:をfalseに設定します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\- layout: post.en title: Groonga 2.0.5 has been released published: false \-\-\- .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS ドキュメントのアップロード .sp doc/source以下のドキュメントを更新、翻訳まで完了している状態で、ドキュメントのアップロード作業を行います。 .sp そのためにはまず以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-document .ft P .fi .UNINDENT .UNINDENT .sp これによりcloneしておいたgroonga.github.comのdoc/locale以下に更新したドキュメントがコピーされます。 .sp 生成されているドキュメントに問題のないことを確認できたら、コミット、pushしてgroonga.orgへと反映します。 .SS Homebrewの更新 .sp OS Xでのパッケージ管理方法として \fI\%Homebrew\fP があります。 .sp Groongaを簡単にインストールできるようにするために、Homebrewへpull requestを送ります。 .INDENT 0.0 .INDENT 3.5 \fI\%https://github.com/mxcl/homebrew\fP .UNINDENT .UNINDENT .sp すでにGroongaのFormulaは取り込まれているので、リリースのたびにFormulaの内容を更新する作業を実施します。 .sp Groonga 3.0.6のときは以下のように更新してpull requestを送りました。 .INDENT 0.0 .INDENT 3.5 \fI\%https://github.com/mxcl/homebrew/pull/21456/files\fP .UNINDENT .UNINDENT .sp 上記URLを参照するとわかるようにソースアーカイブのurlとsha1チェックサムを更新します。 .SS リリースアナウンス .sp 作成したリリースアナウンスをメーリングリストへと流します。 .INDENT 0.0 .IP \(bu 2 groonga\-dev \fI\%groonga\-dev@lists.sourceforge.jp\fP .IP \(bu 2 Groonga\-talk \fI\%groonga\-talk@lists.sourceforge.net\fP .UNINDENT .SS freecode.comへリリース情報を登録 .sp Groongaプロジェクトではfreecode.comでもリリース情報を発信しています。 .sp freecode.comのプロジェクトページは以下の通りです。 .INDENT 0.0 .INDENT 3.5 \fI\%https://freecode.com/projects/groonga\fP .UNINDENT .UNINDENT .sp プロジェクトの管理メニューから「Submit a release」をクリックし、 新規リリース情報を登録します。 .INDENT 0.0 .INDENT 3.5 \fI\%https://freecode.com/projects/groonga/releases/new\fP .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 投稿した内容に対するレビューが運営側で実施されるので、反映されるまでしばらく時間がかかります。 .UNINDENT .UNINDENT .SS Twitterでリリースアナウンスをする .sp blogroongaのリリースエントリには「リンクをあなたのフォロワーに共有する」ためのツイートボタンがあるので、そのボタンを使ってリリースアナウンスします。(画面下部に配置されている) .sp このボタンを経由する場合、ツイート内容に自動的にリリースタイトル(「groonga 2.0.8リリース」など)とblogroongaのリリースエントリのURLが挿入されます。 .sp この作業はblogroongaの英語版、日本語版それぞれで行います。 あらかじめgroongaアカウントでログインしておくとアナウンスを円滑に行うことができます。 .sp 以上でリリース作業は終了です。 .SS リリース後にやること .sp リリースアナウンスを流し終えたら、次期バージョンの開発が始まります。 .INDENT 0.0 .IP \(bu 2 Groonga プロジェクトの新規バージョン追加 .IP \(bu 2 Groonga のbase_versionの更新 .UNINDENT .SS Groonga プロジェクトの新規バージョン追加 .sp \fI\%Groonga プロジェクトの設定ページ\fP にて新規バージョンを追加します。(例: release\-2.0.6) .SS Groonga バージョン更新 .sp $GROONGA_CLONE_DIRにて以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-version NEW_VERSION=2.0.6 .ft P .fi .UNINDENT .UNINDENT .sp これにより$GROONGA_CLONE_DIR/base_versionが更新されるのでコミットしておきます。 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 base_versionはtar.gzなどのリリース用のファイル名で使用します。 .UNINDENT .UNINDENT .SS ビルド時のTIPS .SS ビルドを並列化したい .sp make build PALALLES=yesを指定するとchroot環境で並列にビルドを 実行できます。 .SS 特定の環境向けのみビルドしたい .sp Debian系の場合、CODES,ARCHITECTURESオプションを明示的に指定することで、特定のリリース、アーキテクチャのみビルドすることができます。 .sp squeezeのi386のみビルドしたい場合には以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make build ARCHITECTURES=i386 CODES=squeeze .ft P .fi .UNINDENT .UNINDENT .sp buildコマンド以外でも build\-package\-deb build\-repository\-debなどのサブタスクでもARCHITECTURES,CODES指定は有効です。 .sp Red Hat系の場合、ARCHITECTURES,DISTRIBUTIONSオプションを明示的に指定することで、特定のリリース、アーキテクチャのみビルドすることができます。 .sp fedoraのi386のみビルドしたい場合には以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make build ARCHITECTURES=i386 DISTRIBUTIONS=fedora .ft P .fi .UNINDENT .UNINDENT .sp buildコマンド以外でも build\-in\-chroot build\-repository\-rpmなどのサブタスクでもARCHITECTURES,DISTRIBUTIONSの指定は有効です。 .sp centosの場合、CENTOS_VERSIONSを指定することで特定のバージョンのみビルドすることができます。 .SS パッケージの署名用のパスフレーズを知りたい .sp パッケージの署名に必要な秘密鍵のパスフレーズについては リリース担当者向けの秘密鍵を復号したテキストの1行目に記載してあります。 .SS バージョンを明示的に指定してドキュメントを生成したい .sp リリース後にドキュメントの一部を差し替えたい場合、特に何も指定しないと生成したHTMLに埋め込まれるバージョンが「v3.0.1\-xxxxxドキュメント」となってしまうことがあります。gitでのコミット時ハッシュの一部が使われるためです。 .sp これを回避するには、以下のようにDOCUMENT_VERSIONやDOCUMENT_VERSION_FULLを明示的に指定します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % make update\-document DOCUMENT_VERSION=3.0.1 DOCUMENT_VERSION_FULL=3.0.1 .ft P .fi .UNINDENT .UNINDENT .SS テスト方法 .SS テスト環境の構築 .SS Cutterのインストール .sp Groongaは、テストのフレームワークとして \fI\%Cutter\fP を用いています。 .sp Cutterのインストール方法は \fI\%プラットフォーム毎のCutterのインストール方法\fP をご覧下さい。 .SS lcovのインストール .sp カバレッジ情報を計測するためには、lcov 1.6以上が必要です。DebianやUbuntuでは以下のようにしてインストールできます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo aptitude install \-y lcov .ft P .fi .UNINDENT .UNINDENT .SS clangのインストール .sp ソースコードの静的解析を行うためには、clang(scan\-build)をインストールする必要があります。DebianやUbuntuでは以下のようにしてインストールできます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo aptitude install \-y clang .ft P .fi .UNINDENT .UNINDENT .SS libmemcachedのインストール .sp memcachedのバイナリプロトコルのテストを動作させるためには、libmemcachedの導入が必要です。squeeze以降のDebianやKarmic以降のUubntuでは以下の用にしてインストールできます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % sudo aptitude install \-y libmemcached\-dev .ft P .fi .UNINDENT .UNINDENT .SS テストの動作 .sp Groongaのトップディレクトリで、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make check .ft P .fi .UNINDENT .UNINDENT .SS カバレッジ情報 .sp Groongaのトップディレクトリで、以下のコマンドを実行します。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make coverage .ft P .fi .UNINDENT .UNINDENT .sp すると、coverageディレクトリ以下に、カバレッジ情報が入ったhtmlが出力されます。 .sp カバレッジには、Lines/Functions/Branchesの3つの対象があります。それぞれ、行／関数／分岐に対応します。Functionsがもっとも重要な対象です。すべての関数がテストされるようになっていることを心がけてください。 .sp テストがカバーしていない部分の編集は慎重に行ってください。また、テストがカバーしている部分を増やすことも重要です。 .SS 様々なテスト .sp テストは、test/unitディレクトリにおいて、./run\-test.shを実行することによっても行えます。run\-test.shはいくつかのオプションをとります。詳細は、./run\-test.sh \-\-helpを実行しヘルプをご覧ください。 .SS 特定のテスト関数のみテストする .sp 特定のテスト関数(Cutterではテストと呼ぶ)のみをテストすることができます。 .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./run\-test.sh \-n test_text_otoj .ft P .fi .UNINDENT .UNINDENT .SS 特定のテストファイルのみテストする .sp 特定のテストファイル(Cutterではテストケースと呼ぶ)のみテストすることができます。 .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % ./run\-test.sh \-t test_string .ft P .fi .UNINDENT .UNINDENT .SS 不正メモリアクセス・メモリリーク検出 .sp 環境変数CUTTER_CHECK_LEAKをyesと設定すると、valgrindを用いて不正メモリアクセスやメモリリークを検出しつつ、テストを動作させることができます。 .sp run\-test.shのみならず、make checkでも利用可能です。 .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % CUTTER_CHECK_LEAK=yes make check .ft P .fi .UNINDENT .UNINDENT .SS デバッガ上でのテスト実行 .sp 環境変数CUTTER_DEBUGをyesと設定すると、テストが実行できる環境が整ったgdbが実行されます。gdb上でrunを行うと、テストの実行が開始されます。 .sp run\-test.shのみならず、make checkでも利用可能です。 .sp 実行例: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % CUTTER_DEBUG=yes make check .ft P .fi .UNINDENT .UNINDENT .SS 静的解析 .sp scan\-buildを用いて、ソースコードの静的解析を行うことができます。scan_buildというディレクトリに解析結果のhtmlが出力されます。: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % scan\-build ./configure \-\-prefix=/usr % make clean % scan\-build \-o ./scan_build make \-j4 .ft P .fi .UNINDENT .UNINDENT .sp configureは１度のみ実行する必要があります。 .INDENT 0.0 .IP \(bu 2 \fIgenindex\fP .IP \(bu 2 \fImodindex\fP .IP \(bu 2 \fIsearch\fP .UNINDENT .SH AUTHOR Groonga Project .SH COPYRIGHT 2009-2014, Brazil, Inc .\" Generated by docutils manpage writer. .