.TH "GROONGA" "1" "February 28, 2012" "2.0.0" "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 .. .\" Man page generated from reStructeredText. . .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 Groonga 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. .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 Debian GNU/Linux squeeze .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/debian/ squeeze main deb\-src http://packages.groonga.org/debian/ squeeze main .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo aptitude update % sudo aptitude \-V \-D \-y install groonga .ft P .fi .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, please install groonga\-munin\-plugins package. .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo aptitude \-V \-D \-y install groonga\-munin\-plugins .ft P .fi .SS Debian GNU/Linux wheezy .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/debian/ wheezy main deb\-src http://packages.groonga.org/debian/ wheezy main .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo aptitude update % sudo aptitude \-V \-D \-y install groonga .ft P .fi .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo aptitude \-V \-D \-y install groonga\-munin\-plugins .ft P .fi .SS Debian GNU/Linux sid .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/debian/ unstable main deb\-src http://packages.groonga.org/debian/ unstable main .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo aptitude update % sudo aptitude \-V \-D \-y install groonga .ft P .fi .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo aptitude \-V \-D \-y install groonga\-munin\-plugins .ft P .fi .SS Ubuntu 10.04 LTS Lucid Lynx .IP Note You\(aqll need to enable the universe repository of Ubuntu to install groonga. The following describes how to do it. .RE .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/ubuntu/ lucid universe deb\-src http://packages.groonga.org/ubuntu/ lucid universe .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo apt\-get update % sudo apt\-get \-y install groonga .ft P .fi .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo apt\-get \-y install groonga\-munin\-plugins .ft P .fi .SS Ubuntu 11.04 Natty Narwhal .IP Note You\(aqll need to enable the universe repository of Ubuntu to install groonga. The following describes how to do it. .RE .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/ubuntu/ natty universe deb\-src http://packages.groonga.org/ubuntu/ natty universe .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo apt\-get update % sudo apt\-get \-y install groonga .ft P .fi .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo apt\-get \-y install groonga\-munin\-plugins .ft P .fi .SS Ubuntu 11.10 Oneiric Ocelot .IP Note You\(aqll need to enable the universe repository of Ubuntu to install groonga. The following describes how to do it. .RE .sp /etc/apt/sources.list.d/groonga.list: .sp .nf .ft C deb http://packages.groonga.org/ubuntu/ oneiric universe deb\-src http://packages.groonga.org/ubuntu/ oneiric universe .ft P .fi .sp Install: .sp .nf .ft C % sudo apt\-key adv \-\-recv\-keys \-\-keyserver keyserver.ubuntu.com 1C837F31 % sudo apt\-get update % sudo apt\-get \-y install groonga .ft P .fi .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo apt\-get \-y install groonga\-munin\-plugins .ft P .fi .SS CentOS 5 .sp Install: .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/centos/groonga\-repository\-1.0.0\-0.noarch.rpm % sudo yum update % sudo yum install \-y groonga .ft P .fi .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, please install groonga\-munin\-plugins package. .IP Note Groonga\-munin\-plugins package requires munin\-node package that isn\(aqt included in the official CentOS repository. You need to enable \fI\%RPMforge\fP repository or \fI\%EPEL\fP repository to install it by yum. .sp Enable RPMforge repository on i386 environment: .sp .nf .ft C % sudo rpm \-ivh http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.2\-2.el5.rf.i386.rpm .ft P .fi .sp Enable RPMforge repository on x86_64 environment: .sp .nf .ft C % sudo rpm \-ivh http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.2\-2.el5.rf.x86_64.rpm .ft P .fi .sp Enable EPEL repository on any environment: .sp .nf .ft C % sudo rpm \-ivh http://download.fedoraproject.org/pub/epel/5/i386/epel\-release\-5\-4.noarch.rpm .ft P .fi .RE .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo yum update % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .SS CentOS 6 .sp Install: .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/centos/groonga\-repository\-1.0.0\-0.noarch.rpm % sudo yum update % sudo yum install \-y groonga .ft P .fi .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, please install groonga\-munin\-plugins package. .IP Note Groonga\-munin\-plugins package requires munin\-node package that isn\(aqt included in the official CentOS repository. You need to enable \fI\%RPMforge\fP repository or \fI\%EPEL\fP repository to install it by yum. .sp Enable RPMforge repository on i686 environment: .sp .nf .ft C % sudo rpm \-ivh http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.2\-2.el6.rf.i686.rpm .ft P .fi .sp Enable RPMforge repository on x86_64 environment: .sp .nf .ft C % sudo rpm \-ivh http://pkgs.repoforge.org/rpmforge\-release/rpmforge\-release\-0.5.2\-2.el6.rf.x86_64.rpm .ft P .fi .sp Enable EPEL repository on any environment: .sp .nf .ft C % sudo rpm \-ivh http://download.fedoraproject.org/pub/epel/6/i386/epel\-release\-6\-5.noarch.rpm .ft P .fi .RE .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo yum update % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .SS Fedora 16 .sp Install: .sp .nf .ft C % sudo rpm \-ivh http://packages.groonga.org/fedora/groonga\-repository\-1.0.0\-0.noarch.rpm % sudo yum update % sudo yum install \-y groonga .ft P .fi .sp There is a package that provides \fI\%Munin\fP plugins. If you want to monitor groonga status by Munin, please install groonga\-munin\-plugins package. .sp Install groonga\-munin\-plugins package: .sp .nf .ft C % sudo yum install \-y groonga\-munin\-plugins .ft P .fi .SS Mac OS X (MacPorts) .sp Install: .sp .nf .ft C % sudo port install groonga .ft P .fi .SS Mac OS X (Homebrew) .sp Install: .sp .nf .ft C % brew install groonga .ft P .fi .SS Windows (Installer) .sp You just download an installer (.exe file) from \fI\%packages.groonga.org/windows/\fP and execute it. .SS Windows (zip) .sp You just download a zip file from \fI\%packages.groonga.org/windows/\fP and extract it. .SS Others .sp If you want to use a morphological analyzer for tokenization in full\-text indexing, please install \fI\%MeCab\fP before installing groonga. .sp Then, download a tar.gz file from \fI\%packages.groonga.org/source/\fP and extract it. After that, please run the following command to install groonga. .sp Install: .sp .nf .ft C \&./configure \-\-prefix=/usr \-\-localstatedir=/var && make && sudo make install .ft P .fi .sp The "prefix" option specifies the path to install groonga. If you don\(aqt specify the install path, "/usr/local" is used. Please specify "/usr" if you are not familiar with environment variables such as LD_LIBRARY_PATH. .sp There are some \fI\%Munin\fP plugins in groonga package. You need to pass \fI\-\-with\-munin\-plugins\fP option to install them. .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 speaker \fI\%groonga-talk@lists.sourceforge.net\fP .TP .B For Japanese speaker \fI\%groonga-dev@lists.sourceforge.jp\fP .UNINDENT .SH TUTORIAL .SS Basic operations .sp The groonga package provides a C library (libgroonga) and a command line tool (groonga). This tutorial explains how to use the groonga command, with which you can create/operate databases, start a server, establish a connection with a server, etc. .SS Create a database .sp You can create a new database with the following command. .sp Form: .sp .nf .ft C groonga \-n DB_PATH_NAME .ft P .fi .sp The \(aq\-n\(aq option specifies to create a new database. DB_PATH_NAME specifies the path of the new database. Note that this command fails if the specified path already exists. .sp This command creates a 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: .sp .nf .ft C % groonga \-n /tmp/tutorial.db > Ctrl\-d % .ft P .fi .SS Operate a database .sp Form: .sp .nf .ft C groonga DB_PATH_NAME [COMMAND] .ft P .fi .sp DB_PATH_NAME specifies the path of a target database. .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 execute them one by one. This tutorial focuses on the interactive mode. .sp Let\(aqs try to see the status of a groonga process by using a \fB/commands/status\fP command. .sp Execution example: .sp .nf .ft C % groonga \-n /tmp/groonga\-databases/introduction.db > status [[0,1322616280.40348,0.000158121],{"alloc_count":127,"starttime":1322616279,"uptime":1,"version":"1.2.8\-9\-gbf05b82","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] .ft P .fi .sp As shown in the above example, a command basically 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: .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 .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/executables/groonga\fP. .SS Basic commands .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB/commands/status\fP shows status of a groonga process. .TP .B \fB/commands/table_list\fP shows a list of tables in a database. .TP .B \fB/commands/column_list\fP shows a list of columns in a table. .TP .B \fB/commands/table_create\fP adds a table to a database. .TP .B \fB/commands/column_create\fP adds a column to a table. .TP .B \fB/commands/select\fP searches records from a table and shows the result. .TP .B \fB/commands/load\fP inserts records to a table. .UNINDENT .UNINDENT .UNINDENT .SS Create a table .sp A \fB/commands/table_create\fP command creates a table. .sp In most cases, a table of groonga has a primary key which must be specified with its data type and index type. .sp There are various data types such as integers, floating\-point numbers, etc. The index type determines the search performance and the availability of prefix searches. We will explain the details later. .sp Let\(aqs create a \(aqSite\(aq table which has a primary key of ShortText. In this example, the index type is HASH. .sp Execution example: .sp .nf .ft C > table_create \-\-name Site \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1322616280.60791,0.01234375],true] .ft P .fi .SS View a table .sp A \fB/commands/select\fP command shows contents of table. .sp Execution example: .sp .nf .ft C > select \-\-table Site [[0,1322616280.82196,0.000451873],[[[0],[["_id","UInt32"],["_key","ShortText"]]]]] .ft P .fi .sp When only a table is specified, the \(aqselect\(aq command returns the first (at most) 10 records of that table. "[0]" in the result shows the number of records in the \(aqSite\(aq 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, \(aq_id\(aq and \(aq_key\(aq, are the necessary columns. The \(aq_id\(aq column stores IDs those are automatically allocated by groonga. The \(aq_key\(aq column is associated with the primary key. You are not allowed to rename these columns. .SS Create a column .sp A \fB/commands/column_create\fP command adds a column to a table. .sp Let\(aqs add a column of ShortText to store titles. You may give a descriptive name \(aqtitle\(aq to the column. .sp Execution example: .sp .nf .ft C > column_create \-\-table Site \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212712.91734,0.077833747],true] > select \-\-table Site [[0,1317212713.19572,0.000121119],[[[0],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]]]]] .ft P .fi .sp The COLUMN_SCALAR flag specifies to add a regular column. .SS Create a lexicon table for full text searches .sp Let\(aqs go on to how to make a 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 \(aqTerms\(aq. The data type of its primary key is ShortText. .sp Execution example: .sp .nf .ft C > table_create \-\-name Terms \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram [[0,1317212713.39679,0.092312046],true] .ft P .fi .sp The table_create 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 \(aqTABLE_PAT_KEY\(aq flag specifies to store index terms in a patricia trie. The \(aqKEY_NORMALIZE\(aq flag specifies to normalize index terms. In this example, both flags are validated by using a \(aq|\(aq. The \(aqdefault_tokenizer\(aq parameter specifies a method for tokenizing text. This example specifies \(aqTokenBigram\(aq that is generally called \(aqN\-gram\(aq. .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 for the \(aqtitle\(aq column in the \(aqSite\(aq table. .sp Execution example: .sp .nf .ft C > column_create \-\-table Terms \-\-name blog_title \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Site \-\-source title [[0,1317212713.68994,0.19739078],true] .ft P .fi .sp This command creates an index column \(aqblog_title\(aq in the \(aqTerms\(aq table. The \(aq\-\-type\(aq option specifies a target table and the \(aq\-\-source\(aq option specifies a target column. Then, the \(aqCOLUMN_INDEX\(aq flag specifies to create an index column and the \(aqWITH_POSITION\(aq flag specifies to create a full inverted index, which contains the positions of each index term. This combination \(aqCOLUMN_INDEX|WITH_POSITION\(aq is recommended for the general purpose. .SS Load data .sp A \fB/commands/load\fP command loads JSON\-formatted records into a table. .sp The following adds nine records to the \(aqSite\(aq table. .sp Execution example: .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,1317212714.08816,2.203527402],9] .ft P .fi .sp Let\(aqs make sure that these records are correctly stored. .sp Execution example: .sp .nf .ft C > select \-\-table Site [[0,1317212716.49285,0.000270908],[[[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 .SS Search data .sp Before a full text search, let\(aqs try to search data by \(aq_id\(aq and \(aq_key\(aq. These columns work as unique keys. .sp You can search records by using a \(aqselect\(aq command with a \(aqquery\(aq parameter. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-query _id:1 [[0,1317212716.69871,0.000308514],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]] .ft P .fi .sp \(aq_id:1\(aq specifies to search a record whose ID is 1. .sp Next, let\(aqs search a record by a primary key. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-query "_key:\e"http://example.org/\e"" [[0,1317212716.9005,0.000478343],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]] .ft P .fi .sp \(aq_key:"\fI\%http://example.org/\fP"\(aq specifies to search a record whose primary key is "\fI\%http://example.org/\fP". .SS Full text search .sp It\(aqs time to make a full text search. You can make a full text search query with the same \(aqquery\(aq parameter. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-query title:@this [[0,1317212717.10303,0.000581287],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]] .ft P .fi .sp This command searches records whose \(aqtitle\(aq column contains a string \(aqthis\(aq. In this case, only one record matches this query. Note that the lower case query \(aqthis\(aq matches a capitalized \(aqThis\(aq in the 1st record because \(aqKEY_NORMALIZE\(aq was specified in lexicon column creation. .sp The \(aqselect\(aq command has an optional parameter \(aqmatch_columns\(aq. This parameter specifies default target columns and it is used when target columns are not specified in a query.[1]_ .sp A combination of \(aq\-\-match_columns title\(aq and \(aq\-\-query this\(aq brings you the same result that \(aq\-\-query title:@this\(aq does. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-match_columns title \-\-query this [[0,1317212717.30596,0.000716439],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]] .ft P .fi .SS Specify output columns .sp An \(aqoutput_columns\(aq parameter in a \(aqselect\(aq command specifies columns to be shown in the search result. If you want to specify more than one columns, please separate column names by commas (,). .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-output_columns _key,title,_score \-\-query title:@test [[0,1317212717.50916,0.00060758],[[[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 .sp This command specifies three output columns including the \(aq_score\(aq column, which stores the relevance score of each record. .SS Specify output ranges .sp A \(aqselect\(aq command returns a part of its search result if \(aqoffset\(aq and/or \(aqlimit\(aq 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 \(aqoffset\(aq parameter specifies the starting point and a \(aqlimit\(aq 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: .sp .nf .ft C > select \-\-table Site \-\-offset 0 \-\-limit 3 [[0,1317212717.71574,0.000238544],[[[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,1317212717.91925,0.00023617],[[[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,1317212718.12219,0.00019999],[[[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 .SS Sort .sp A \(aqselect\(aq command sorts its result when used with a \(aqsortby\(aq parameter. .sp A \(aqsortby\(aq 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 (\-) to the column name of a parameter. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-sortby \-_id [[0,1317212718.32565,0.000385755],[[[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 .sp You can use the \(aq_score\(aq column as a sorting criteria for ranking a search result. .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-query title:@test \-\-output_columns _id,_score,title \-\-sortby _score [[0,1317212718.5331,0.000667311],[[[9],[["_id","UInt32"],["_score","Int32"],["title","ShortText"]],[1,1,"This is test record 1!"],[2,1,"test record 2."],[4,1,"test record four."],[3,2,"test test record three."],[9,2,"test test record nine."],[8,2,"test test record eight."],[7,3,"test test test record seven."],[5,3,"test test test record five."],[6,4,"test test test test record six."]]]] .ft P .fi .sp If you want to specify more than one columns, please separate column names by commas. In such a case, a search result is sorted in order of the column 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: .sp .nf .ft C > select \-\-table Site \-\-query title:@test \-\-output_columns _id,_score,title \-\-sortby _score,_id [[0,1317212718.73819,0.00069225],[[[9],[["_id","UInt32"],["_score","Int32"],["title","ShortText"]],[1,1,"This is test record 1!"],[2,1,"test record 2."],[4,1,"test record four."],[3,2,"test test record three."],[8,2,"test test record eight."],[9,2,"test test record nine."],[5,3,"test test test record five."],[7,3,"test test test record seven."],[6,4,"test test test test record six."]]]] .ft P .fi footnote .IP [1] 5 Currently, a \(aqmatch_columns\(aq parameter is available iff there exists an inverted index for full text search. A \(aqmatch_columns\(aq parameter for a regular column is not supported. .SS How to use groonga with network .sp You can use groonga with network. When you run groonga by using the groonga original protocol or HTTP, groonga accepts connection for network. .SS Connect with groonga\(aqs original protocol .SS Run groonga daemon .sp Form: .sp .nf .ft C groonga [\-p PORT_NUMBER] \-d DB_PATH_NAME .ft P .fi .sp The DB_PATH_NAME is set the full\-path of existing database. With this form, you can run groonga as a daemon and connect by with groonga original protocol on PORT_NUMBER. (The port number is 10041 when you don\(aqt specify PORT_NUMBER.) .sp Execution example: .sp .nf .ft C % groonga \-d /tmp/groonga\-databases/introduction.db 12345 % .ft P .fi .sp Groonga shows its process ID on daemon mode. .SS Connect to groonga server .sp Form: .sp .nf .ft C groonga [\-p PORT_NUMBER] \-c [HOST_NAME_OR_IP_ADDRESS] .ft P .fi .sp This command connects to groonga server running at specified HOST_NAME_OR_IP_ADDRESS. .sp When you don\(aqt specify HOST_NAME_OR_IP_ADDRESS, this command connects to groonga server running at localhost. When you don\(aqt specify PORT_NUMBER, 10041 is used. .sp Groonga runs in interactive mode after connect to groonga server successfully. Groonga reads command from standard input and evaluates it repeatedly. .sp Execution example: .sp .nf .ft C % groonga \-c > status [[0,1317212813.13814,0.000102148],{"alloc_count":184,"starttime":1317212806,"uptime":7,"version":"1.2.5\-84\-g5c190df","n_queries":14,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] > ctrl\-d % .ft P .fi .SS Terminate groonga daemon .sp You can terminate groonga daemon with shutdown command. .sp Execution example: .sp .nf .ft C % groonga \-c > shutdown % .ft P .fi .SS Connect with HTTP .sp You need to run groonga in HTTP protocol mode when you want to use groonga via HTTP. .sp Form: .sp .nf .ft C groonga [\-p PORT_NUMBER] \-d \-\-protocol http DB_PATH_NAME .ft P .fi .sp \fI\-\-protocol\fP option specifies a protocol of groonga server. \fIhttp\fP means that groonga accepts connections via HTTP. .SS Administration tool based on HTML .sp You can access administration tool based on HTML at \fIhttp://[HOST_NAME_OR_IP_ADDRESS]:[PORT_NUMBER]/\fP after the above command is ran. Your browser must enable JavaScript. .SS Run command with HTTP .sp You can run command at \fI/d/COMMAND_NAME\fP when groonga is ran in HTTP protocol mode. .sp Command options are passed as HTTP\(aqs GET parameters. They are in \fI?OPTION=VALUE&OPTION=VALUE&...\fP form. .sp Execution example: .sp .nf .ft C http://[IPまたはホスト名]:[ポート番号]/d/status 実行される処理： > status [[0,1317212813.33982,0.000109691],{"alloc_count":184,"starttime":1317212806,"uptime":7,"version":"1.2.5\-84\-g5c190df","n_queries":14,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}] http://[IPまたはホスト名]:[ポート番号]/d/select?table=Site&query=title:@this 実行される処理： > select \-\-table Site \-\-query title:@this [[0,1317212813.54112,6.7993e\-05],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]] .ft P .fi .SS Security .sp Network service of groonga doesn\(aqt support authentication. Everyone can view and modify the database. We recommend that you restrict client accesses by IP address. You can use iptables or any similar tool for it. .SS さまざまな種類をもったデータの保存 .sp groongaでは、さまざまなデータを格納させることが出来ます。 .SS データ型 .sp groongaでは、数値（整数・小数）や文字列や時刻や経緯度などの情報を格納することができます。 .sp ここでは、Int32型のカラムに整数を格納、Float型のカラムに浮動小数点の小数を、ShortText型のカラムに文字列を、Time型のカラムに時間を格納する例を示します。経緯度の格納については、のちのチュートリアルで触れます。 .sp その他のデータ型の一覧は、 \fB/type\fP を参照してください。 .sp Execution example: .sp .nf .ft C > table_create \-\-name Type \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1322616293.7274,0.012551106],true] > column_create \-\-table Type \-\-name number \-\-type Int32 [[0,1322616293.94115,0.008619605],true] > column_create \-\-table Type \-\-name float \-\-type Float [[0,1322616294.15095,0.004959989],true] > column_create \-\-table Type \-\-name string \-\-type ShortText [[0,1322616294.35693,0.005551818],true] > column_create \-\-table Type \-\-name time \-\-type Time [[0,1322616294.56333,0.006356953],true] > load \-\-table Type > [{"_key":"sample","number":12345,"float":42.195,"string":"GROONGA","time":1234567890.12}] [[0,1322616294.77086,0.202357708],1] > select \-\-table Type [[0,1322616295.1744,0.000340057],[[[1],[["_id","UInt32"],["_key","ShortText"],["float","Float"],["number","Int32"],["string","ShortText"],["time","Time"]],[1,"sample",42.195,12345,"GROONGA",1234567890.12]]]] .ft P .fi .SS テーブル型 .sp table_createで作成したテーブルを、カラムの型として使うことが出来ます。 .sp また、output_columnsにおいて「.」を区切りとして、参照先のテーブルに存在するカラムを指定すると、指定したカラムの値を表示することができます。 .sp ここでは、先のチュートリアルで作成したSiteテーブルに手を加え、どのサイトをリンクしているのかを保存してみましょう。 .sp 他のテーブルを参照するカラムにデータを入力する場合には、参照先のテーブルの_keyカラムの値を代入する必要があります。 .sp Execution example: .sp .nf .ft C > column_create \-\-table Site \-\-name link \-\-type Site [[0,1322616295.37864,0.005674045],true] > load \-\-table Site > [{"_key":"http://example.org/","link":"http://example.net/"}] [[0,1322616295.5854,0.200879317],1] > select \-\-table Site \-\-output_columns _key,title,link._key,link.title \-\-query title:@this [[0,1322616295.98732,0.000872177],[[[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 .sp このように、linkカラムに他のサイトへの参照を保存することができました。また、参照先の_keyとtitleカラムの内容を表示することができました。 .SS ベクターカラム .sp column_createコマンドでカラムを作成するとき、\-\-flagsオプションでCOLUMN_VECTORフラグを指定すると、複数の値を配列で格納できるカラムが作成されます。 .sp テーブル型で配列を格納するカラムは、1対多の参照関係を表すのに有効です。 .sp テーブル型のチュートリアルでは、Siteテーブルに手を加え、どのサイトをリンクしているのかを保存しました。しかし、通常は1つのサイトから多くのサイトにリンクが張られています。複数のリンク情報を格納するために、複数の参照関係を保存するカラムを作成してみましょう。 .sp 他のテーブルを参照するベクターカラムにデータを入力する場合には、参照先のテーブルの_keyカラムの値の「配列」を代入する必要があります。 .sp Execution example: .sp .nf .ft C > column_create \-\-table Site \-\-name links \-\-flags COLUMN_VECTOR \-\-type Site [[0,1322616296.19238,0.007598942],true] > load \-\-table Site > [{"_key":"http://example.org/","links":["http://example.net/","http://example.org/","http://example.com/"]}] [[0,1322616296.40092,0.201036234],1] > select \-\-table Site \-\-output_columns _key,title,links._key,links.title \-\-query title:@this [[0,1322616296.80305,0.000899975],[[[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 .sp このように、複数の参照関係が保存できました。また、output_columnsによって、複数の参照先のカラム値も表示させることができました。 .SS さまざまな検索条件の指定 .sp groongaは、JavaScriptに似た文法での条件絞込や、計算した値を用いたソートを行うことができます。また、位置情報(緯度・経度)を用いた絞込・ソートを行うことができます。 .SS JavaScriptに似た文法での絞込・全文検索 .sp selectコマンドのfilterパラメータは、queryパラメータと同様に、レコードの検索条件を指定します。filterパラメータとqueryパラメータが異なる点は、filterパラメータには、JavaScriptの式に似た文法で条件を指定する点です。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-filter "_id <= 1" \-\-output_columns _id,_key [[0,1317212733.77852,0.000333188],[[[1],[["_id","UInt32"],["_key","ShortText"]],[1,"http://example.org/"]]]] .ft P .fi .sp ここで、filterパラメータには .INDENT 0.0 .INDENT 3.5 _id <= 1 .UNINDENT .UNINDENT .sp という条件を指定しています。この場合は_idの値が1以下のレコードが検索結果として得られます。 .sp また、&& や || を使って、条件のAND・OR指定をすることもできます。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-filter "_id >= 4 && _id <= 6" \-\-output_columns _id,_key [[0,1317212733.97986,0.000297681],[[[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,1317212734.18118,0.000250524],[[[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 .sp queryパラメータとfilterパラメータを同時に指定すると、両者の条件をともに満たすレコードが結果として返ります。 .SS scorerを利用したソート .sp selectコマンドのscorerパラメータは、 全文検索を行った結果の各レコードに対して処理を行うためのパラメータです。 .sp filterパラメータと同様に、 JavaScriptの式に似たな文法で様々な条件を指定することができます。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-filter "1" \-\-scorer "_score = rand()" \-\-output_columns _id,_key,_score \-\-sortby _score [[0,1317212734.38283,0.000354558],[[[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 "1" \-\-scorer "_score = rand()" \-\-output_columns _id,_key,_score \-\-sortby _score [[0,1317212734.58497,0.000350529],[[[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 .sp 検索結果には、\(aq_score\(aqという名前の、全文検索のスコアが代入されている仮想的なカラムが付与されることをチュートリアル中ソートの項目で説明しました。 .sp 上記の実行例では、scorerパラメータに .INDENT 0.0 .INDENT 3.5 _score = rand() .UNINDENT .UNINDENT .sp という条件を指定しています。ここでは、rand()という乱数を返す関数を用いて、全文検索のスコアを乱数で上書きしています。 .sp sortbyパラメータには、 .INDENT 0.0 .INDENT 3.5 _score .UNINDENT .UNINDENT .sp を指定しています。これは、スコア順に昇順にソートすることを意味しています。 .sp よって、上記のクエリは実行されるたびに検索結果の並び順がランダムに変わります。 .SS 位置情報を用いた絞込・ソート .sp groongaでは、位置情報（経緯度）を保存することができます。また、保存した経緯度を用いて絞込やソートができます。 .sp 位置情報を保存するためのカラムの型として、TokyoGeoPoint/WGS84GeoPointの２つの型があります。前者は日本測地系、後者は世界測地系(WGS84相当)の経緯度を保存します。 .sp 経緯度は以下のいずれかの形式の文字列として指定します。 .INDENT 0.0 .IP \(bu 2 "[緯度のミリ秒]x[経度のミリ秒]"（例: "128452975x503157902"） .IP \(bu 2 "[緯度のミリ秒],[経度のミリ秒]"（例: "128452975,503157902"） .IP \(bu 2 "[緯度の小数表記の度数]x[経度の小数表記の度数]"（例: "35.6813819x139.7660839"） .IP \(bu 2 "[緯度の小数表記の度数],[経度の小数表記の度数]"（例: "35.6813819,139.7660839"） .UNINDENT .sp ここでは、ためしに東京駅と新宿駅とついて、世界測地系での位置情報を保存してみましょう。東京駅は緯度が35度40分52.975秒、経度が139度45分57.902秒です。新宿駅は緯度が35度41分27.316秒、経度が139度42分0.929秒です。よって、ミリ秒表記の場合はそれぞれ"128452975x503157902"/"128487316x502920929"となります。度数表記の場合はそれぞれ"35.6813819x139.7660839"/"35.6909211x139.7002581"となります。ここではミリ秒表記で登録しましょう。 .sp Execution example: .sp .nf .ft C > column_create \-\-table Site \-\-name location \-\-type WGS84GeoPoint [[0,1317212734.78744,0.047997601],true] > load \-\-table Site > [ > {"_key":"http://example.org/","location":"128452975x503157902"} > {"_key":"http://example.net/","location":"128487316x502920929"}, > ] [[0,1317212735.0361,0.801149613],2] > select \-\-table Site \-\-query "_id:1 OR _id:2" \-\-output_columns _key,location [[0,1317212736.03775,0.000261897],[[[2],[["_key","ShortText"],["location","WGS84GeoPoint"]],["http://example.org/","128452975x503157902"],["http://example.net/","128487316x502920929"]]]] .ft P .fi .sp scorerパラメータにおいて、 \fB/functions/geo_distance\fP 関数を用いることにより、２点間の距離を計算することができます。 .sp ここでは、秋葉原駅からの距離を表示させてみましょう。世界測地系では、秋葉原駅の位置は緯度が35度41分55.259秒、経度が139度46分27.188秒です。よって、geo_distance関数に与える文字列は"128515259x503187188"となります。 .sp Execution example: .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,1317212736.23918,0.000393211],[[[2],[["_key","ShortText"],["location","WGS84GeoPoint"],["_score","Int32"]],["http://example.org/","128452975x503157902",2054],["http://example.net/","128487316x502920929",6720]]]] .ft P .fi .sp この結果を見ると、東京駅と秋葉原駅は2054m、秋葉原駅と新宿駅は6720m離れているようです。 .sp geo_distance関数は、_scoreを通じてソートでも用いることができます。 .sp Execution example: .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,1317212736.44102,0.000345608],[[[2],[["_key","ShortText"],["location","WGS84GeoPoint"],["_score","Int32"]],["http://example.net/","128487316x502920929",6720],["http://example.org/","128452975x503157902",2054]]]] .ft P .fi .sp 「ある地点から何m以内に存在する」といった絞込も可能です。 .sp filterパラメータにおいて、 \fB/functions/geo_in_circle\fP 関数を用いることにより、２点間の距離が指定のm以下におさまるかどうかを判定することができます。 .sp たとえば、秋葉原駅から5000m以内にあるレコードを検索してみましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-output_columns _key,location \-\-filter \(aqgeo_in_circle(location, "128515259x503187188", 5000)\(aq [[0,1317212736.64335,0.000245378],[[[1],[["_key","ShortText"],["location","WGS84GeoPoint"]],["http://example.org/","128452975x503157902"]]]] .ft P .fi .sp また、経緯度が指定の矩形領域内であるかどうかを判定する \fB../functions/geo_in_rectangle\fP 関数も存在します。 .SS ドリルダウン .sp groongaでは、特定のカラム値で検索結果をグループ化することができます。これをドリルダウンと呼びます。 .sp Siteテーブルに２つのカラムを追加します。TLDドメイン名を格納するdomainカラムと、国名を格納するcountryカラムです。これらのカラムの型は、それぞれドメイン名を主キーとするSiteDomainテーブルと、国名を主キーとするSiteCountryテーブルとします。 .sp Execution example: .sp .nf .ft C > table_create \-\-name SiteDomain \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1317212750.98228,0.098212593],true] > table_create \-\-name SiteCountry \-\-flags TABLE_HASH_KEY \-\-key_type ShortText > column_create \-\-table Site \-\-name domain \-\-flags COLUMN_SCALAR \-\-type SiteDomain [[0,1317212751.28095,0.256200943],true] [[0,1317212751.53719,0.085740621],true] > column_create \-\-table Site \-\-name country \-\-flags COLUMN_SCALAR \-\-type SiteCountry [[0,1317212751.82329,0.064026147],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,1317212752.0878,2.202801388],9] .ft P .fi .sp domainカラムとcountryカラムでドリルダウンを行う例を以下に示します。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-limit 0 \-\-drilldown domain [[0,1317212754.4912,0.000250704],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["location","WGS84GeoPoint"],["links","Site"],["link","Site"],["domain","SiteDomain"],["country","SiteCountry"]]],[[3],[["_key","ShortText"],["_nsubrecs","Int32"]],[".org",3],[".net",3],[".com",3]]]] .ft P .fi .sp テーブル型を持つカラムに対してドリルダウンを行った場合、参照先のテーブルに存在するカラム値を取得することもできます。ドリルダウンを行ったテーブルには、_nsubrecsという仮想的なカラムが追加されます。このカラムには、グループ化されたレコード数が入ります。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-limit 0 \-\-drilldown domain \-\-drilldown_output_columns _id,_key,_nsubrecs [[0,1317212754.69307,0.000359614],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["location","WGS84GeoPoint"],["links","Site"],["link","Site"],["domain","SiteDomain"],["country","SiteCountry"]]],[[3],[["_id","UInt32"],["_key","ShortText"],["_nsubrecs","Int32"]],[1,".org",3],[2,".net",3],[3,".com",3]]]] .ft P .fi .sp 複数のカラムに対してドリルダウンを行うことができます。複数のカラムに対してドリルダウンを行う場合には、drilldownパラメータにカラム名をカンマ区切りで与えます。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-limit 0 \-\-drilldown domain,country [[0,1317212754.89542,0.000263258],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["location","WGS84GeoPoint"],["links","Site"],["link","Site"],["domain","SiteDomain"],["country","SiteCountry"]]],[[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 .sp ドリルダウン結果を並びかえることができます。例えば、_nsubrecsパラメータの降順で並び替えることができます。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-limit 0 \-\-drilldown country \-\-drilldown_sortby _nsubrecs [[0,1317212755.09777,0.000284575],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["location","WGS84GeoPoint"],["links","Site"],["link","Site"],["domain","SiteDomain"],["country","SiteCountry"]]],[[5],[["_key","ShortText"],["_nsubrecs","Int32"]],["brazil",1],["korea",1],["usa",2],["china",2],["japan",3]]]] .ft P .fi .sp ドリルダウン結果は、デフォルトでは10件のみ表示されます。drilldown_offsetパラメータと、drilldown_limitパラメータによって、offsetとlimitを指定することができます。 .sp Execution example: .sp .nf .ft C > select \-\-table Site \-\-limit 0 \-\-drilldown country \-\-drilldown_sortby _nsubrecs \-\-drilldown_limit 2 \-\-drilldown_offset 2 [[0,1317212755.29988,0.000237191],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["location","WGS84GeoPoint"],["links","Site"],["link","Site"],["domain","SiteDomain"],["country","SiteCountry"]]],[[5],[["_key","ShortText"],["_nsubrecs","Int32"]],["usa",2],["china",2]]]] .ft P .fi .sp 文字列型のカラムに対するドリルダウンは、他の型でのドリルダウンに比べて低速です。文字列でのドリルダウンを行いたい場合には、このチュートリアルのように、文字列型を主キーとするテーブルを別途作成し、そのテーブルを型とするカラムを作成します。 .SS タグ検索・参照関係の逆引き .sp 本チュートリアルで、groongaはカラム値として他のテーブルへの参照の配列を持つことができることを紹介いたしました。実は、テーブルへの参照の配列データを用いることによって、いわゆるタグ検索を行うことが可能となります。 .sp タグ検索はgroongaの転置インデックスというデータ構造を用いて高速に行われます。 .SS タグ検索 .sp 動画共有サイトの検索エンジンを作ることを想定します。1つの動画には、その動画の特徴を表す、複数の語句が付与されています。「ある語句が付与されている動画の一覧を取得する」検索を行いたいとします。 .sp 実際に、動画情報のテーブルを作成し、検索をしてみましょう。 .sp 動画の情報を保存する、Videoテーブルを作成します。Videoテーブルでは、動画のタイトルをtitleカラムに、動画のタグ情報をtagsカラムにTagテーブル型で複数格納しています。 タグの情報を保存する、Tagテーブルを作成します。Tagテーブルでは、タグ文字列を主キーに格納し、Videoテーブルのtagsカラムに対するインデックスをindex_tagsカラムに格納しています。 .sp Execution example: .sp .nf .ft C > table_create \-\-name Video \-\-flags TABLE_HASH_KEY \-\-key_type UInt32 [[0,1317212832.70606,0.061331715],true] > table_create \-\-name Tag \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1317212832.968,0.039868236],true] > column_create \-\-table Video \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212833.20833,0.040494862],true] > column_create \-\-table Video \-\-name tags \-\-flags COLUMN_VECTOR \-\-type Tag [[0,1317212833.44939,0.051861409],true] > column_create \-\-table Tag \-\-name index_tags \-\-flags COLUMN_INDEX \-\-type Video \-\-source tags [[0,1317212833.70185,0.092878953],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,1317212833.99531,2.002850011],8] .ft P .fi .sp インデックスカラムを作成すると、全文検索が高速に行えるようになります。インデックスカラムは、対象のカラムに保存されたデータに更新があったとき、自動的に更新されます。 .sp 「ある語句が付与されている動画の一覧を取得する」検索を行いましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table Video \-\-query tags:@Variety \-\-output_columns _key,title [[0,1317212836.19894,0.000330108],[[[2],[["_key","UInt32"],["title","ShortText"]],[2,"Zenigata Kinjirou"],[5,"Hex Gone!"]]]] > select \-\-table Video \-\-query tags:@Sports \-\-output_columns _key,title [[0,1317212836.39998,0.000316897],[[[2],[["_key","UInt32"],["title","ShortText"]],[1,"Soccer 2010"],[4,"Moero!! Ultra Baseball"]]]] > select \-\-table Video \-\-query tags:@Animation \-\-output_columns _key,title [[0,1317212836.60111,0.000349157],[[[3],[["_key","UInt32"],["title","ShortText"]],[6,"Pikonyan 1"],[7,"Draw 8 Month"],[8,"K.O."]]]] .ft P .fi .sp このように、「Variety」、「Sports」、「Animation」のようなタグで検索を行うことができました。 .SS 参照関係の逆引き .sp groongaはテーブル間の参照関係の逆引きを高速に行うためのインデックスを付与することができます。タグ検索は、その1例にすぎません。 .sp 例えば、ソーシャルネットワーキングサイトにおける友人関係を逆引き検索することができます。 .sp 以下の例では、ユーザー情報を格納するUserテーブルを作成し、ユーザー名を格納するusernameカラム、ユーザーの友人一覧を配列で格納するfriendsカラムとそのインデックスのindex_friendsカラムを追加しています。 .sp Execution example: .sp .nf .ft C > table_create \-\-name User \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1317212836.80268,0.048923839],true] > column_create \-\-table User \-\-name username \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212837.05226,0.040322616],true] > column_create \-\-table User \-\-name friends \-\-flags COLUMN_VECTOR \-\-type User [[0,1317212837.29306,0.039978793],true] > column_create \-\-table User \-\-name index_friends \-\-flags COLUMN_INDEX \-\-type User \-\-source friends [[0,1317212837.53369,0.067271637],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,1317212837.80152,1.602221355],6] .ft P .fi .sp 指定したユーザーを友人リストに入れているユーザーの一覧を表示してみましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table User \-\-query friends:@tomo \-\-output_columns _key,username [[0,1317212839.60442,0.000260617],[[[5],[["_key","ShortText"],["username","ShortText"]],["ken","健作"],["taro","ぐるんが太郎"],["jiro","ぐるんが次郎"],["moritapo","森田"],["hana","花子"]]]] > select \-\-table User \-\-query friends:@jiro \-\-output_columns _key,username [[0,1317212839.80577,0.000253172],[[[3],[["_key","ShortText"],["username","ShortText"]],["ken","健作"],["taro","ぐるんが太郎"],["hana","花子"]]]] .ft P .fi .sp さらに、ドリルダウンを使って、友人リストに入っている数の一覧を表示してみましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table User \-\-limit 0 \-\-drilldown friends [[0,1317212840.00717,0.000223187],[[[6],[["_id","UInt32"],["_key","ShortText"],["username","ShortText"],["index_friends","User"],["friends","User"]]],[[6],[["_key","ShortText"],["_nsubrecs","Int32"]],["taro",3],["jiro",3],["tomo",5],["moritapo",2],["ken",3],["hana",1]]]] .ft P .fi .sp このように、テーブルの参照関係を逆にたどる検索ができました。 .SS インデックス付きジオサーチ .sp 位置情報のカラムに対して、インデックスを付与することが出来ます。大量の位置情報レコードを検索する場合に、検索速度が速くなります。 .sp Execution example: .sp .nf .ft C > table_create \-\-name GeoIndex \-\-flags TABLE_PAT_KEY \-\-key_type WGS84GeoPoint [[0,1317212840.20962,0.088534001],true] > column_create \-\-table GeoIndex \-\-name index_point \-\-type Site \-\-flags COLUMN_INDEX \-\-source location [[0,1317212840.49869,0.093704431],true] > load \-\-table Site > [ > {"_key":"http://example.org/","location":"128452975x503157902"}, > {"_key":"http://example.net/","location":"128487316x502920929"} > ] [[0,1317212840.79332,0.801438285],2] > select \-\-table Site \-\-filter \(aqgeo_in_circle(location, "128515259x503187188", 5000)\(aq \-\-output_columns _key,location [[0,1317212841.79563,0.000626003],[[[1],[["_key","ShortText"],["location","WGS84GeoPoint"]],["http://example.org/","128452975x503157902"]]]] .ft P .fi .sp 同様に、位置情報レコードを用いてソートする場合に、ソート速度が速くなります。 .sp Execution example: .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,1317212841.99878,0.0011657],[[[2],[["_key","ShortText"],["location","WGS84GeoPoint"],["_score","Int32"]],["http://example.org/","128452975x503157902",2054],["http://example.net/","128487316x502920929",6720]]]] .ft P .fi .SS match_columnsパラメータ .SS 複数のカラムを対象とした全文検索 .sp groongaでは、複数のカラムを対象とした全文検索を行うことができます。例えば、ブログのテーブルで、タイトルと内容とがそれぞれ別のカラムに入ったものがあるとしましょう。「タイトルもしくは内容に特定の単語を含む」検索を行いたいとします。 .sp この場合、2つのインデックス作成方式があります。1つは、それぞれのカラムに1つずつインデックスを付与する方式です。もう1つは、複数のカラムに対して1つのインデックスを付与する方式です。groongaでは、どちらの形式のインデックスが存在している場合でも、同一の記法で全文検索を行うことができます。 .SS カラムごとにインデックスを付与する場合 .sp Blog1テーブルを作り、タイトル文字列のtitleカラム、本文のmessageカラムを追加しています。 インデックス用のIndexBlog1テーブルも作り、titleカラムのインデックス用にindex_titleカラム、messageカラムのインデック用にindex_messageカラムと、それぞれ1カラムごとに1つずつ追加しています。 .sp Execution example: .sp .nf .ft C > table_create \-\-name Blog1 \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1317212795.41036,0.047939793],true] > column_create \-\-table Blog1 \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212795.65884,0.040658195],true] > column_create \-\-table Blog1 \-\-name message \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212795.89978,0.029458384],true] > table_create \-\-name IndexBlog1 \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram [[0,1317212796.12974,0.183567683],true] > column_create \-\-table IndexBlog1 \-\-name index_title \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Blog1 \-\-source title [[0,1317212796.51381,0.092148792],true] > column_create \-\-table IndexBlog1 \-\-name index_message \-\-flags COLUMN_INDEX|WITH_POSITION \-\-type Blog1 \-\-source message [[0,1317212796.80646,0.088690675],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,1317212797.09575,1.001254761],3] .ft P .fi .sp match_columnsオプションで、検索対象のカラムを複数指定することが出来ます。検索する文字列はqueryオプションで指定します。これを使うことで、タイトルと本文を全文検索することができます。 .sp 実際に検索してみましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table Blog1 \-\-match_columns title||message \-\-query groonga [[0,1317212798.29761,0.000365318],[[[3],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[1,"grn1","groonga test","groonga message"],[3,"grn3","groonga message","none"],[2,"grn2","baseball result","rakutan eggs 4 \- 4 groonga moritars"]]]] > select \-\-table Blog1 \-\-match_columns title||message \-\-query message [[0,1317212798.49954,0.000310648],[[[2],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[3,"grn3","groonga message","none"],[1,"grn1","groonga test","groonga message"]]]] > select \-\-table Blog1 \-\-match_columns title \-\-query message [[0,1317212798.70102,0.000314581],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[3,"grn3","groonga message","none"]]]] .ft P .fi .SS 複数のカラムにまたがったインデックスを付与する場合 .sp 内容は上の例とほぼ同じですが、titleとmessageの2つのカラムに対するインデックスが共通になっており、インデックスカラムが1つしかありません。 .sp 共通のインデックスを用いても、titleカラムのみでの検索、messageカラムのみでの検索、titleもしくはmessageカラムでの検索、全ての検索を行うことができます。 .sp Execution example: .sp .nf .ft C > table_create \-\-name Blog2 \-\-flags TABLE_HASH_KEY \-\-key_type ShortText [[0,1317212798.90253,0.052986511],true] > column_create \-\-table Blog2 \-\-name title \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212799.156,0.028355347],true] > column_create \-\-table Blog2 \-\-name message \-\-flags COLUMN_SCALAR \-\-type ShortText [[0,1317212799.38486,0.040142104],true] > table_create \-\-name IndexBlog2 \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram [[0,1317212799.62539,0.039673533],true] > column_create \-\-table IndexBlog2 \-\-name index_blog \-\-flags COLUMN_INDEX|WITH_POSITION|WITH_SECTION \-\-type Blog2 \-\-source title,message [[0,1317212799.86551,0.079790187],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,1317212800.14589,1.001367315],3] .ft P .fi .sp 実際に検索してみましょう。結果は上の例と同じになります。 .sp Execution example: .sp .nf .ft C > select \-\-table Blog2 \-\-match_columns title||message \-\-query groonga [[0,1317212801.34801,0.000328232],[[[3],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[1,"grn1","groonga test","groonga message"],[2,"grn2","baseball result","rakutan eggs 4 \- 4 groonga moritars"],[3,"grn3","groonga message","none"]]]] > select \-\-table Blog2 \-\-match_columns title||message \-\-query message [[0,1317212801.54962,0.000320935],[[[2],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[1,"grn1","groonga test","groonga message"],[3,"grn3","groonga message","none"]]]] > select \-\-table Blog2 \-\-match_columns title \-\-query message [[0,1317212801.75107,0.000323124],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"],["message","ShortText"]],[3,"grn3","groonga message","none"]]]] .ft P .fi .SS インデックス名を指定した全文検索 .sp 執筆中です。 .SS インデックスの重み .sp 執筆中です。 .SS パトリシア木による前方一致検索 .sp groongaのテーブルは、テーブル作成時にパトリシア木オプションを指定すると、前方一致検索を行うことができます。また、追加のオプションを指定することにより、主キーの後方一致検索をも行うことができます。 .SS 主キーによる前方一致検索 .sp table_createコマンドのflagsオプションにTABLE_PAT_KEYを指定することで、主キーによる前方一致検索ができるようになります。 .sp Execution example: .sp .nf .ft C > table_create \-\-name PatPrefix \-\-flags TABLE_PAT_KEY \-\-key_type ShortText [[0,1317212719.34619,0.047490604],true] > load \-\-table PatPrefix > [ > {"_key":"ひろゆき"}, > {"_key":"まろゆき"}, > {"_key":"ひろあき"} > ] [[0,1317212719.59456,1.001406593],3] > select \-\-table PatPrefix \-\-query _key:@ひろ [[0,1317212720.79648,0.00031203],[[[2],[["_id","UInt32"],["_key","ShortText"]],[3,"ひろあき"],[1,"ひろゆき"]]]] .ft P .fi .SS 主キーによる後方一致検索 .sp table_createコマンドのflagsオプションにTABLE_PAT_KEYとKEY_WITH_SISを指定することで、主キーによる前方一致検索・後方一致検索の両方が可能となります。 .sp KEY_WITH_SISフラグを付与すると、データを追加する際に後方一致用のレコードも追加されてしまいます。そのため、単純に検索すると、元のレコードに加えて自動的に追加されたレコードまでヒットしてしまいます。元のレコードのみ検索するために、一工夫必要になります。 .sp 例えば、元のレコードと自動的に追加されたレコードとの区別をつけるために、元のレコードであることを示すoriginalカラムを追加して、検索時にはoriginalカラムが \fBtrue\fP も検索条件に加えます。 .sp Execution example: .sp .nf .ft C > table_create \-\-name PatSuffix \-\-flags TABLE_PAT_KEY|KEY_WITH_SIS \-\-key_type ShortText [[0,1317212720.99778,0.0531648179999999],true] > column_create \-\-table PatSuffix \-\-name original \-\-type Bool [[0,1317212721.25163,0.099479727],true] > load \-\-table PatSuffix > [ > {"_key":"ひろゆき","original":true}, > {"_key":"まろゆき","original":true}, > {"_key":"ひろあき","original":true} > ] [[0,1317212721.55167,1.001449341],3] > select \-\-table PatSuffix \-\-query _key:@ゆき [[0,1317212722.75369,0.000313623],[[[4],[["_id","UInt32"],["_key","ShortText"],["original","Bool"]],[1,"ひろゆき",true],[5,"まろゆき",true],[3,"ゆき",false],[2,"ろゆき",false]]]] > select \-\-table PatSuffix \-\-query "_key:@ゆき original:true" [[0,1317212722.95502,0.00032577],[[[2],[["_id","UInt32"],["_key","ShortText"],["original","Bool"]],[1,"ひろゆき",true],[5,"まろゆき",true]]]] .ft P .fi .SS 全文検索の語彙表に対する追加情報 .sp groongaでは、全文検索に用いるための語意表がテーブルとして扱えます。よって、語彙ごとに複数の情報を保持することができます。例えば、語彙の出現数や検索ストップワードのフラグ、単語の重要度などを保持することができます。 .sp この項目については、現在執筆中です。 .SS マイクロブログ検索システムの作成 .sp これまで学んだgroongaの機能を用いて、マイクロブログの検索システムを作成してみましょう。マイクロブログとは、Twitterのような短いメッセージを投稿するブログです。 .SS テーブルの作成 .sp まずは、テーブルを作成します。 .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 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 .ft P .fi .SS Usersテーブル .sp ユーザーの名前や自己紹介文、フォローしているユーザー一覧など、ユーザー情報を格納するためのテーブルです。 .INDENT 0.0 .TP .B \fB_key\fP ユーザーID .TP .B \fBname\fP ユーザー名 .TP .B \fBfollower\fP フォローしているユーザーの一覧 .TP .B \fBfavorites\fP お気に入りのコメント一覧 .TP .B \fBlocation\fP ユーザーの現在地（緯度経度座標） .TP .B \fBlocation_str\fP ユーザーの現在地（文字列） .TP .B \fBdescription\fP ユーザーの自己紹介 .TP .B \fBfollowee\fP Usersテーブルのfollowerカラムに対するインデックス。 このインデックスを作ることで、あるユーザーをフォローしているユーザーを検索できるようになります。 .UNINDENT .SS Commentsテーブル .sp コメント内容や投稿日時、返信先情報など、コメントに関する内容を格納するテーブルです。 .INDENT 0.0 .TP .B \fB_key\fP コメントID .TP .B \fBcomment\fP コメント内容 .TP .B \fBlast_modified\fP 投稿日時 .TP .B \fBreplied_to\fP 返信元のコメント内容 .TP .B \fBreplied_users\fP 返信先のユーザーの一覧 .TP .B \fBhash_tags\fP コメントのハッシュタグの一覧 .TP .B \fBlocation\fP 投稿場所(緯度経度座標のため) .TP .B \fBposted_by\fP コメントを書いたユーザー .TP .B \fBfavorited_by\fP Usersテーブルのfavoritesカラムに対するインデックス。 このインデックスを作ることで、指定したコメントを誰がお気に入りに入れているのかを検索できるようになります。 .UNINDENT .SS HashTagsテーブル .sp コメントのハッシュタグを一覧で保存するためのテーブルです。 .INDENT 0.0 .TP .B \fB_key\fP ハッシュタグ .TP .B \fBhash_index\fP 「Comments.hash_tags」のインデックス。 このインデックスを作ることで、指定したハッシュタグのついているコメントの一覧を出すことが出来るようになります。 .UNINDENT .SS Bigramテーブル .sp ユーザー情報・コメントで全文検索が出来るようにするためのインデックスを格納するテーブルです。 .INDENT 0.0 .TP .B \fB_key\fP 単語 .TP .B \fBusers_index\fP ユーザー情報のインデックス。 このカラムは、ユーザー名「Users.name」、現在地「Users.location_str」、自己紹介文「Users.description」のインデックスになっています。 .TP .B \fBcomment_index\fP コメント内容「Comments.comment」のインデックス .UNINDENT .SS データのロード .sp つづいて、テスト用データをロードします。 .sp .nf .ft C load \-\-table Users [ { "_key": "daijiro", "name": "hsiomaneki", "follower": ["tasukuchan"], "favorites": [], "location": "127678039x502643091", "location_str": "神奈川県", "description": "groonga developer" }, { "_key": "tasukuchan", "name": "グニャラくん", "follower": ["daijiro","OffGao"], "favorites": ["daijiro:1","OffGao:1"], "location": "128423343x502929252", "location_str": "東京都渋谷区", "description": "エロいおっさん" }, { "_key": "OffGao", "name": "OffGao", "follower": ["tasukuchan","daijiro"], "favorites": ["tasukuchan:1","daijiro:1"], "location": "128544408x502801502", "location_str": "東京都中野区", "description": "がおがお" } ] load \-\-table Comments [ { "_key": "daijiro:1", "comment": "マイクロブログ作ってみました（甘栗むいちゃいました的な感じで）。", "last_modified": "2010/03/17 12:05:00", "posted_by": "daijiro", }, { "_key": "tasukuchan:1", "comment": "初の書き込み。テストテスト。", "last_modified": "2010/03/17 12:00:00", "posted_by": "tasukuchan", }, { "_key": "daijiro:2", "comment": "@tasukuchan ようこそ!!!", "last_modified": "2010/03/17 12:05:00", "replied_to": "tasukuchan:1", "replied_users": ["tasukuchan"], "posted_by": "daijiro", }, { "_key": "tasukuchan:2", "comment": "@daijiro ありがとう！", "last_modified": "2010/03/17 13:00:00", "replied_to": "daijiro:2", "replied_users": ["daijiro"], "posted_by": "tasukuchan", }, { "_key": "tasukuchan:3", "comment": "groongaなう #groonga", "last_modified": "2010/03/17 14:00:00", "hash_tags": ["groonga"], "location": "127972422x503117107", "posted_by": "tasukuchan", }, { "_key": "tasukuchan:4", "comment": "groonga開発合宿のため羽田空港に来ました！ #groonga #travel", "last_modified": "2010/03/17 14:05:00", "hash_tags": ["groonga", "travel"], "location": "127975798x502919856", "posted_by": "tasukuchan", }, { "_key": "OffGao:1", "comment": "@daijiro @tasukuchan 登録してみましたよー！", "last_modified": "2010/03/17 15:00:00", "replied_users": ["daijiro", "tasukuchan"], "location": "128551935x502796433", "posted_by": "OffGao", } { "_key": "OffGao:2", "comment": "中野ブロードウェイなうなう", "last_modified": "2010/03/17 15:05:00", "location": "128551935x502796434", "posted_by": "OffGao", } ] .ft P .fi .sp Usersテーブルのfollowerカラムとfavoritesカラム、そしてCommentsテーブルのreplied_usersカラムは、ベクターカラムです。そのため、これらのカラムは配列で値を指定します。 .sp Usersテーブルのlocationカラムと、Commentsテーブルのlocationカラムは、GeoPoint型です。この型での値の指定は、"[緯度]x[経度]"と記述して指定します。 .sp Commentsテーブルのlast_modifiedカラムは、Time型です。この型での値の指定方法は、マイクロ秒数の値を直接指定する方法のほかに、文字列で指定する方法もあります。"年/月/日 時:分:秒"というフォーマットで記述することで、データロードの際に文字列からキャストされ、マイクロ秒数の値が格納されます。 .SS 検索 .sp それでは、実際に検索をしてみましょう。 .SS キーワードでユーザー検索 .sp ここでは、 \fBmatch_columns\fP で扱った、複数カラムを対象とした検索を行います。 指定された文字列で、ユーザー名・現在地・自己紹介文を対象に検索をします。 .sp Execution example: .sp .nf .ft C > select \-\-table Users \-\-match_columns name,location_str,description \-\-query 東京 \-\-output_columns _key,name [[0,1317212781.80175,0.000302755],[[[2],[["_key","ShortText"],["name","ShortText"]],["tasukuchan","グニャラくん"],["OffGao","OffGao"]]]] .ft P .fi .sp 「東京」をキーワードにユーザー検索した結果、東京都に住んでいる「グニャラくん」と「OffGao」がヒットしました。 .SS GeoPointでユーザー検索 .sp ここでは、 \fBsearch\fP で扱った、GeoPoint型のカラムで検索をします。 以下の例では、指定された位置から5000m以内にいるユーザーを検索しています。 .sp Execution example: .sp .nf .ft C > select \-\-table Users \-\-filter \(aqgeo_in_circle(location,"128484216x502919856",5000)\(aq \-\-output_columns _key,name [[0,1317212782.00321,0.000241271],[[[2],[["_key","ShortText"],["name","ShortText"]],["tasukuchan","グニャラくん"],["OffGao","OffGao"]]]] .ft P .fi .sp 新宿駅から5km以内にすんでいるユーザーを検索したところ、「グニャラくん」と「OffGao」がヒットしました。 .SS あるユーザーをフォローしているユーザーの検索 .sp ここでは、 \fBindex\fP で扱った、参照関係の逆引きをします。 以下の例では、Usersテーブルのfollowerカラムにあるフォローリストを逆引きします。 .sp Execution example: .sp .nf .ft C > select \-\-table Users \-\-query follower:@tasukuchan \-\-output_columns _key,name [[0,1317212782.20472,0.000231885],[[[2],[["_key","ShortText"],["name","ShortText"]],["daijiro","hsiomaneki"],["OffGao","OffGao"]]]] .ft P .fi .sp 「グニャラくん」をフォローしている「hsiomaneki」と「OffGao」がヒットしました。 .SS GeoPointでコメント検索 .sp ある範囲内で書かれたコメントを検索します。 また、 \fBdrilldown\fP で扱ったドリルダウンも行います。検索結果をハッシュタグとユーザーでドリルダウンし、ユーザー別・ハッシュタグ別のカウントを出します。 .sp Execution example: .sp .nf .ft C > select \-\-table Comments \-\-filter \(aqgeo_in_circle(location,"127975798x502919856",20000)\(aq \-\-output_columns posted_by.name,comment \-\-drilldown hash_tags,posted_by [[0,1317212782.40617,0.000451828],[[[4],[["posted_by.name","ShortText"],["comment","ShortText"]],["OffGao","@daijiro @tasukuchan 登録してみましたよー！"],["グニャラくん","groongaなう #groonga"],["グニャラくん","groonga開発合宿のため羽田空港に来ました！ #groonga #travel"],["OffGao","中野ブロードウェイなうなう"]],[[2],[["_key","ShortText"],["_nsubrecs","Int32"]],["groonga",2],["travel",1]],[[2],[["_key","ShortText"],["_nsubrecs","Int32"]],["OffGao",2],["tasukuchan",2]]]] .ft P .fi .sp 範囲を広く指定したため、位置情報のあるすべてのコメントがヒットしました。そして、ヒットしたコメントからドリルダウンされた結果も返ってきており、ハッシュタグは「#groonga」が2つに「#travel」が1つ、投稿者は「グニャラくん」「OffGao」がそれぞれ2件ずつであることがわかります。 .SS キーワードでコメント検索 .sp あるキーワードを含むコメントを検索します。 さらに、 \fBsearch\fP で扱った、スコア値_scoreも出してみましょう。 .sp Execution example: .sp .nf .ft C > select \-\-table Comments \-\-query comment:@なう \-\-output_columns comment,_score [[0,1317212782.60919,0.000239996],[[[2],[["comment","ShortText"],["_score","Int32"]],["groongaなう #groonga",1],["中野ブロードウェイなうなう",2]]]] .ft P .fi .sp 「なう」をキーワードにコメント検索した結果、2件のコメントがヒットしました。また、_scoreの値も返ってきており、「なう」の数が出力されていることが確認できます。 .SS GeoPointとキーワードでコメント検索 .sp 今度は、キーワードとGeoPointの両方を条件に検索をしてみます。\-\-queryと\-\-filterの両方を使用した場合、両方の条件に一致するレコードがヒットします。 .sp Execution example: .sp .nf .ft C > select \-\-table Comments \-\-query comment:@羽田 \-\-filter \(aqgeo_in_circle(location,"127975798x502919856",20000)\(aq \-\-output_columns posted_by.name,comment \-\-drilldown hash_tags,posted_by [[0,1317212782.81082,0.000427163],[[[1],[["posted_by.name","ShortText"],["comment","ShortText"]],["グニャラくん","groonga開発合宿のため羽田空港に来ました！ #groonga #travel"]],[[2],[["_key","ShortText"],["_nsubrecs","Int32"]],["groonga",1],["travel",1]],[[1],[["_key","ShortText"],["_nsubrecs","Int32"]],["tasukuchan",1]]]] .ft P .fi .sp 両方の条件を満たすコメントが1件ヒットしました。また、ドリルダウンの結果も返ってきており、「グニャラくん」のコメント1件であることがわかります。 .SS ハッシュタグでコメント検索 .sp あるハッシュタグのついているコメントを検索します。 これも、 \fBindex\fP で扱った、参照関係の逆引きを使います。 .sp Execution example: .sp .nf .ft C > select \-\-table Comments \-\-query hash_tags:@groonga \-\-output_columns posted_by.name,comment \-\-drilldown posted_by [[0,1317212783.01379,0.000311974],[[[2],[["posted_by.name","ShortText"],["comment","ShortText"]],["グニャラくん","groongaなう #groonga"],["グニャラくん","groonga開発合宿のため羽田空港に来ました！ #groonga #travel"]],[[1],[["_key","ShortText"],["_nsubrecs","Int32"]],["tasukuchan",2]]]] .ft P .fi .sp #groongaタグの付いている2件のコメントがヒットしました。また、投稿者のドリルダウンも返ってきており、2件とも「グニャラくん」のものであることがわかります。 .SS ユーザーIDでコメント検索 .sp あるユーザーが投稿したコメントを検索します。 .sp Execution example: .sp .nf .ft C > select \-\-table Comments \-\-query posted_by:tasukuchan \-\-output_columns comment \-\-drilldown hash_tags [[0,1317212783.21601,0.000313114],[[[4],[["comment","ShortText"]],["初の書き込み。テストテスト。"],["@daijiro ありがとう！"],["groongaなう #groonga"],["groonga開発合宿のため羽田空港に来ました！ #groonga #travel"]],[[2],[["_key","ShortText"],["_nsubrecs","Int32"]],["groonga",2],["travel",1]]]] .ft P .fi .sp 「グニャラくん」が書き込んだ4件のコメントがヒットしました。また、ハッシュタグでドリルダウンした結果も返ってきており、ハッシュタグは「#groonga」が2つに「#travel」が1つあることがわかります。 .SS ユーザーのお気に入りコメントを検索 .sp あるユーザーがお気に入りに入れているコメントを検索します。 .sp Execution example: .sp .nf .ft C > select \-\-table Users \-\-query _key:tasukuchan \-\-output_columns favorites.posted_by,favorites.comment [[0,1317212783.41809,0.000257979],[[[1],[["favorites.posted_by","Users"],["favorites.comment","ShortText"]],[["daijiro","OffGao"],["マイクロブログ作ってみました（甘栗むいちゃいました的な感じで）。","@daijiro @tasukuchan 登録してみましたよー！"]]]]] .ft P .fi .sp 「グニャラくん」がお気に入りに入れている2件のコメントがヒットしました。 .SS 投稿時間でコメント検索 .sp コメントの投稿時間で検索をします。Time型については \fBdata\fP で扱っています。 この例では、指定した時間よりも前に投稿されているコメントを検索します。 .sp Execution example: .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,1317212783.61997,0.000426254],[[[5],[["posted_by.name","ShortText"],["comment","ShortText"],["last_modified","Time"]],["hsiomaneki","マイクロブログ作ってみました（甘栗むいちゃいました的な感じで）。",1268795100.0],["グニャラくん","初の書き込み。テストテスト。",1268794800.0],["hsiomaneki","@tasukuchan ようこそ!!!",1268795100.0],["グニャラくん","@daijiro ありがとう！",1268798400.0],["グニャラくん","groongaなう #groonga",1268802000.0]],[[1],[["_key","ShortText"],["_nsubrecs","Int32"]],["groonga",1]],[[2],[["_key","ShortText"],["_nsubrecs","Int32"]],["daijiro",2],["tasukuchan",3]]]] .ft P .fi .sp 2010/03/17 14:00:00以前に書かれたコメント5件がヒットしました。また、ドリルダウンの結果も返ってきており、「hsiomaneki」が2件、「グニャラくん」が3件ヒットしていることがわかります。 .SS クエリ拡張 .sp groongaでは、 \fB/commands/select\fP コマンドにquery_expansionパラメータを指定することによって、ユーザが指定した検索文字列を適宜拡張することが可能です。 .sp たとえば、ユーザが\(aqシークヮーサー\(aqという文字列で検索した場合に、\(aqシークヮーサー OR シークァーサー\(aqで検索した場合と同一の結果を返すことによって、本来ユーザが必要とする結果をよりもれなく検索できるようになります。 .SS 準備 .sp クエリ拡張機能を使用するためには、検索対象となる文書を格納するテーブル(ここでは文書テーブルと呼びます)以外に、ユーザの指定した検索文字列を置換するためのテーブル(ここでは置換テーブルと呼びます)を準備します。置換テーブルでは、その主キーが置換前の文字列となり、文字列型(ShortText)のカラムの値が置換後の文字列となります。 .sp TODO: 文字列型のベクターカラムでも可能であり、その場合は各要素をORでつなげたものに置換されるということを記述する。 .sp 実際に文書テーブルと置換テーブルを作成してみましょう。 .sp Execution example: .sp .nf .ft C > table_create Doc TABLE_PAT_KEY ShortText [[0,1317212801.95257,0.054058921],true] > column_create Doc body COLUMN_SCALAR ShortText [[0,1317212802.2071,0.040301713],true] > table_create Term TABLE_PAT_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram [[0,1317212802.44812,0.027340933],true] > column_create Term Doc_body COLUMN_INDEX|WITH_POSITION Doc body [[0,1317212802.676,0.079743674],true] > table_create Synonym TABLE_PAT_KEY ShortText [[0,1317212802.95629,0.03656858],true] > column_create Synonym body COLUMN_SCALAR ShortText [[0,1317212803.19316,0.040515932],true] > load \-\-table Doc > [ > {"_key": "001", "body": "すっぱいブドウと甘いシークァーサー"}, > {"_key": "002", "body": "シークヮーサージュースとゴーヤチャンプル"}, > ] [[0,1317212803.43422,0.80056314],2] > load \-\-table Synonym > [ > {"_key": "シークァーサー", "body": "(シークァーサー OR シークヮーサー)"}, > {"_key": "シークヮーサー", "body": "(シークァーサー OR シークヮーサー)"}, > ] [[0,1317212804.43524,0.801037492],2] .ft P .fi .sp この例では、ユーザが"シークァーサー"と入力しても、"シークヮーサー"と入力しても、それぞれの異なる表記の文書をもれなく検索するための置換テーブルを作成しています。 .SS 検索 .sp それでは実際に、準備した置換テーブルを使ってみましょう。まずは、query_expansionパラメータを指定せずにselectコマンドを使って検索してみます。 .sp Execution example: .sp .nf .ft C > select Doc \-\-match_columns body \-\-query "シークァーサー" [[0,1317212805.4371,0.000567851],[[[1],[["_id","UInt32"],["_key","ShortText"],["body","ShortText"]],[1,"001","すっぱいブドウと甘いシークァーサー"]]]] > select Doc \-\-match_columns body \-\-query "シークヮーサー" [[0,1317212805.63859,0.000387831],[[[1],[["_id","UInt32"],["_key","ShortText"],["body","ShortText"]],[2,"002","シークヮーサージュースとゴーヤチャンプル"]]]] .ft P .fi .sp 指定された文字列に完全に一致するレコードのみがそれぞれヒットします。次に、query_expansionパラメータに、準備したSynonymテーブルのbodyカラムを指定してみましょう。 .sp Execution example: .sp .nf .ft C > select Doc \-\-match_columns body \-\-query "シークァーサー" \-\-query_expansion Synonym.body [[0,1317212805.84016,0.000441852],[[[2],[["_id","UInt32"],["_key","ShortText"],["body","ShortText"]],[1,"001","すっぱいブドウと甘いシークァーサー"],[2,"002","シークヮーサージュースとゴーヤチャンプル"]]]] > select Doc \-\-match_columns body \-\-query "シークヮーサー" \-\-query_expansion Synonym.body [[0,1317212806.04176,0.000580261],[[[2],[["_id","UInt32"],["_key","ShortText"],["body","ShortText"]],[1,"001","すっぱいブドウと甘いシークァーサー"],[2,"002","シークヮーサージュースとゴーヤチャンプル"]]]] .ft P .fi .sp どちらのクエリ文字列も、"(シークァーサー OR シークヮーサー)"という文字列に置換されてから検索されるため、表記の揺れを吸収して検索できるようになりました。 .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 gronga gronnga T} T{ groonga groonga 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 "に". .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/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: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query en [[0,1317212704.42103,0.001348612],{"complete":[[1],[["_key","ShortText"],["_score","Int32"]],["engine",1]]}] .ft P .fi .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: .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 .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/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/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: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types correction \-\-frequency_threshold 1 \-\-query saerch [[0,1317212708.7696,0.000882462],{"correct":[[1],[["_key","ShortText"],["_score","Int32"]],["search",1]]}] .ft P .fi .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: .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 .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/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: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types suggest \-\-frequency_threshold 1 \-\-query search [[0,1317212711.42188,0.000553344],{"suggest":[[2],[["_key","ShortText"],["_score","Int32"]],["search engine",1],["web search realtime",1]]}] .ft P .fi .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: .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 .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 リファレンスマニュアル .SS 実行ファイル .sp groongaパッケージが提供する実行ファイルについて説明します。 .SS grnslap .SS 名前 .sp grnslap \- groongaプロセスの通信層のパフォーマンスをチェックするツール .SS 書式 .sp .nf .ft C grnslap [options] [dest] .ft P .fi .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でリクエストを行う。 .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 .SS grntest .SS 名前 .sp grntest \- groongaテストプログラム .SS 書式 .sp .nf .ft C grntest [options...] [script] [db] .ft P .fi .SS 説明 .sp grntestは、groonga汎用テストツールです。 .sp groongaを単独のプロセスとして利用する場合はもちろん、サーバプログラムとして利用する場合の動作確認や実行速度測定が可能です。 .sp grntest用のデータファイルは自分で作成することも既存のものを利用することもできます。既存のデータファイルは、ftp.groonga.orgから必要に応じダウンロードします。そのため、groonga及びgrntestが動作し、インターネットに接続できる環境であればgroongaコマンドの知識がなくてもgroongaの動作を確認できます。 .sp 現在は、Linux 及びWindows上で動作します。make installしてもインストールは行われません。 .SS オプション .INDENT 0.0 .TP .B \-i, \-\-host 接続するgroongaサーバを、ipアドレスまたはホスト名で指定します。指定先にgroongaサーバが立ち上がっていない場合、接続不能となることに注意してください。このオプションを指定しない場合、grntestは自動的に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 デフォルトでは、grntest終了後のログファイルの出力先ははカレントディレクトリです。このオプションを利用すると、任意のディレクトリに出力先を変更することができます。 .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 grntestの動作方法(以下、grntest命令と呼びます)を記述したテキストファイルです。拡張子は.scrです。 .UNINDENT .INDENT 0.0 .TP .B db grntestが利用するgroonga データベースです。指定されたデータベースが存在しない場合、grntestが新規に作成します。またgroonga サーバを自動的に起動する場合もこの引数で指定したデータベースが利用されます。接続するgroonga サーバを明示的に指定した場合に利用するデータベースは、接続先サーバが使用中のデータベースになることに注意してください。 .UNINDENT .SS 使い方 .sp まず、シェル上(Windowsならコマンドプロンプト上)で: .sp .nf .ft C grntest test.scr 任意のDB名 .ft P .fi .sp とタイプしてください。もしgrntestが正常に動作すれば、: .sp .nf .ft C test\-ユーザ名\-数字.log .ft P .fi .sp というファイルが作成されるはずです。作成されない場合、このドキュメントの「トラブルシューティング」の章を参照してください。 .SS スクリプトファイル .sp スクリプトファイルは、grntest命令を記述したテキストファイルです。 ";"セミコロンを利用して、一行に複数のgrntest命令を記述することができます。一行に複数のgrntest命令がある場合、各命令は並列に実行されます。 "#"で始まる行はコメントとして扱われます。 .SS grntest命令 .sp 現在サポートされているgrntest命令は以下の8つです。 .INDENT 0.0 .INDENT 3.5 do_local コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgrntest単体で実行します。スレッド数が指定されている場合、複数のスレッドで同じコマンドファイルを同時に実行します。繰り返し数が指定されてい場合、コマンドファイルの内容を繰り返し実行します。スレッド数、繰り返し数とも省略時は1です。1スレッドで複数回動作させたい場合は、do_local コマンドファイル 1 [繰り返し数]と明示的に指定してください。 .UNINDENT .UNINDENT .sp do_gqpt コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバで実行します。スレッド数や繰り返し数の意味はdo_localの場合と同じです。 .UNINDENT .UNINDENT .sp rep_local コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgrntest単体で実行し、より詳細な報告を行います。 .UNINDENT .UNINDENT .sp rep_gqpt コマンドファイル [スレッド数] [繰り返し数] .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバで実行し、より詳細な報告を行います。 スレッド数や繰り返し数の意味はdo_localと 同じです。 .UNINDENT .UNINDENT .sp out_local コマンドファイル 入力ファイル名 .INDENT 0.0 .INDENT 3.5 コマンドファイルをgrntest単体で実行し、各コマンドの実行結果をすべて”出力ファイル"に書きだします。この結果は、test_local,　test_gqtp命令で利用します。なおこの命令の「出力ファイル」とは、grntest実行時に自動的に作成されるログとは別のものです。grntestではコメントが利用できる以外、: .sp .nf .ft C groonga < コマンドファイル > 出力ファイル .ft P .fi .sp とした場合と同じです。 .UNINDENT .UNINDENT .sp out_gqtp コマンドファイル 出力ファイル名 .INDENT 0.0 .INDENT 3.5 コマンドファイルをgroongaサーバで実行します。その他はout_local命令と同等です。 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B test_local コマンドファイル 入力ファイル名 コマンドファイルをgrntest単体で実行し、各コマンドの実行結果を入力ファイルと比較します。処理時間など本質的要素以外に差分があった場合、差分を、入力ファイル.diffというファイルに書きだします。 .UNINDENT .UNINDENT .UNINDENT .SS コマンドファイル .sp コマンドファイルは、groonga組み込みコマンドを1行に1つずつ記述したテキストファイルです。拡張子に制限はありません。groonga組み込みコマンドに関しては \fB/commands\fP を参照してください。 .SS サンプル .sp スクリプトファイルのサンプルです。: .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 .sp 上記の意味は以下のとおりです。 .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B 1行目 コメント行。 .TP .B 2行目 test.dll というコマンドファイルをgroonga単体で実行し、詳細に報告する。 .TP .B 3行目 test.load というコマンドファイルをgroonga単体で実行する。(最後の";"セミコロンは複数のgrntest命令を記述する場合に必要ですが、この例のように1つのgrntest命令を実行する場合に付与しても問題ありません。) .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 例えば、 .sp .nf .ft C $ ./grntest \-\-port 20010 test.scr testdb .ft P .fi .sp とコマンド上でポートを指定した場合でも、もしtest.scrの中身が .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 .sp であれば、自動的に起動されるgroongaサーバはポート番号10400を利用します。 .SS grntest実行結果 .sp grntestが正常に終了すると、(拡張子を除いた)スクリプト名\-ユーザ名\-実行開始時刻.logという形式のログファイルがカレントディレクトリに作られます。ログファイルは自動的にftp.groonga.org に送信されます。ログファイルは以下のようなjson形式のテキストです。 .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 .SS 制限事項 .INDENT 0.0 .IP \(bu 2 スクリプトファイルの一行には複数のgrntest命令を記述できますが、すべてのスレッド数の合計は最大64までに制限されます。 .IP \(bu 2 コマンドファイル中のgroongaコマンドの長さは最長5000000byteです。 .UNINDENT .SS トラブルシューティング .sp もし、grntestが正常に動作しない場合、まず以下を確認してください。 .INDENT 0.0 .IP \(bu 2 インターネットに接続しているか？ \fI\-\-ftp\fP オプションを指定すると、grntestは動作のたびにftp.groonga.orgと通信します。ftp.groonga.orgと通信可能でない場合、grntestは正常に動作しません。 .IP \(bu 2 groonga サーバが動作していないか？　grntestは、\-i, \-\-host オプションで明示的にサーバを指定しないかぎり、自動的にlocalhostのgroongaサーバを立ち上げます。すでにgroongaサーバが動作している場合、grntestは正常に動作しない可能性があります。 .IP \(bu 2 指定したDBが適切か？ grntestは、引数で指定したDBの中身はチェックしません。もし指定されたDBが存在しなければ自動的にDBを作成しますが、もしファイルとして存在する場合は中身に関わらず動作を続けてしまい、結果が異常になる可能性があります。 .UNINDENT .sp 以上の原因でなければ、問題はgrntestかgroongaにあります。ご報告をお願いします。 .SS groonga実行ファイル .SS 名前 .sp groonga \- 列指向データベース機能を持つ全文検索エンジンソフトウェア .SS 書式 .sp .nf .ft C groonga [options] [dest] [command [args]] .ft P .fi .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ポート番号。 (デフォルトは10041番) .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 設定ファイルのパスを指定します。設定ファイルは以下のようなフォーマットになります。: .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 .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:10041\(aq)。ポート番号を指定しない場合には、10041が指定されたものとします。 .UNINDENT .INDENT 0.0 .TP .B command [args] スタンドアロンおよびクライアントモードの場合は、実行するコマンドとその引数をコマンドライン引数に指定できます。コマンドライン引数にcommandを与えなかった場合は、標準入力から一行ずつEOFに達するまでコマンド文字列を読み取り、順次実行します。 .UNINDENT .SS コマンド .sp groonga実行ファイルを通してデータベースを操作する命令をコマンドと呼びます。コマンドは主にC言語で記述され、groongaプロセスにロードすることによって使用できるようになります。 それぞれのコマンドは一意な名前と、0個以上の引数を持ちます。 .sp 引数は以下の2種類の方法のいずれかで指定することができます。: .sp .nf .ft C 形式1: コマンド名 値1 値2,.. 形式2: コマンド名 \-\-引数名1 値1 \-\-引数名2 値2,.. .ft P .fi .sp 形式1でコマンドを実行する場合は、定義された順番で値を指定しなければならず、途中の引数の値を省略することはできません。形式2でコマンドを実行する場合は、「\-\-引数名」のように引数の名前を明示しなければならない代わりに、任意の順番で引数を指定することが可能で、途中の引数の指定を省略することもできます。 .sp 標準入力からコマンド文字列を与える場合は、コマンド名と引数名と値は、空白( )で区切ります。空白や、記号「"\(aq()」のうちいずれかを含む値を指定したい場合は、シングルクォート(\(aq)かダブルクォート(")で値を囲みます。値として指定する文字列の中では、改行文字は\(aqn\(aqに置き換えて指定します。また、引用符に使用した文字を値の中で指定する場合には、その文字の前にバックスラッシュ(\(aq\(aq) を指定します。バックスラッシュ文字自身を値として指定する場合には、その前にバックスラッシュを指定します。 .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 \fBview_add\fP VIEW型のテーブルに要素となるテーブルを定義します。 .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 新しいデータベースを作成します。: .sp .nf .ft C % groonga \-n /tmp/hoge.db quit % .ft P .fi .sp 作成済みのデータベースにテーブルを定義します。: .sp .nf .ft C % groonga /tmp/hoge.db table_create Table 0 ShortText [[0]] % .ft P .fi .sp サーバを起動します。: .sp .nf .ft C % groonga \-d /tmp/hoge.db % .ft P .fi .sp httpサーバとして起動します。: .sp .nf .ft C % groonga \-d \-p 80 \-\-protocol http \-\-document\-root /usr/share/groonga/admin_html /tmp/hoge.db % .ft P .fi .sp サーバに接続し、テーブル一覧を表示します。: .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 .SS groonga HTTPサービス .SS 名前 .sp groonga HTTPサービス .SS 書式 .sp .nf .ft C groonga \-d \-\-protocol http DB_PATH .ft P .fi .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サーバと通信する際には、以下のような形式でコマンドを指定します。: .sp .nf .ft C 形式: /d/コマンド名.output_type?引数名1=値1&引数名2=値2&... .ft P .fi .sp ただし、コマンド名、引数名、値はURLエンコードが必要です。 .sp GETメソッドのみが使用可能です。 .sp output_typeにはjson, tsv, xmlが指定可能です。 .sp command_versionはコマンドの仕様の互換性を指定します。詳細は \fB/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 .sp .nf .ft C groonga\-suggest\-create\-dataset [options] DATABASE DATASET .ft P .fi .SS DESCTIPION .sp groonga\-suggest\-create\-dataset creates a dataset for \fB/suggest\fP. A database has many datasets. This command just defines schea for a suggestion dataset. .SS OPTIONS .sp None. .SS EXIT STATUS .sp TODO .SS FILES .sp TODO .SS EXAMPLE .sp TODO .SS SEE ALSO .sp \fB/suggest\fP .. : doc:\fIgroonga\-suggest\-httpd\fP .. : doc:\fIgroonga\-suggest\-learner\fP .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: .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 .sp You can specify \fBjson\fP as \fBoutput_type\fP value to get a result in JSON format explicitly: .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 .sp You need to specify \fBxml\fP as \fBoutput_type\fP value to get a result in XML format: .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 .sp You need to specify \fBtsv\fP as \fBoutput_type\fP value to get a result in TSV format: .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 .sp You need to specify \fBmsgpack\fP as \fBoutput_type\fP value to get a result in MessagePack format: .sp .nf .ft C > status \-\-output_type msgpack (... omitted because MessagePack is binary data format. ...) .ft P .fi .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: .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 .sp You can specify \fBjson\fP as extension to get a result in JSON format explicitly: .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 .sp You need to specify \fBxml\fP as extension to get a result in XML format: .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 .sp You need to specify \fBtsv\fP as extension to get a result in TSV format: .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 .sp You need to specify \fBmsgpack\fP as extension to get a result in MessagePack format: .sp .nf .ft C % curl http://localhost:10041/d/status.msgpack (... omitted because MessagePack is binary data format. ...) .ft P .fi .SS コマンド .sp まず、すべてのコマンドに関係するコマンドバージョンについて説明します。その後、組み込みのコマンドを順に説明します。 .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のサポートするコマンドバージョンは推移します。: .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 .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 実行例: .sp .nf .ft C groonga \-\-default\-command\-version 1 .ft P .fi .sp そのプロセスで実行するすべてのコマンドについて、デフォルトのコマンドバージョンとして指定されたバージョンを使用します。指定されたコマンドバージョンがstableであった場合にはなんのメッセージも表示されずそのまま起動します。指定されたコマンドバージョンがdevelopあるいはdeprecatedであった場合には、groonga.logファイルに警告メッセージを出力します。指定されたコマンドバージョンがサポート対象外であった場合には標準エラー出力にエラーメッセージを出力し、プロセスは速やかに終了します。 .SS command_versionパラメータ .sp select,loadなどのすべてのgroongaコマンドにcommand_versionが指定できます。 .sp 実行例: .sp .nf .ft C select \-\-command_version 1 \-\-table tablename .ft P .fi .sp 指定されたコマンドバージョンでコマンドを実行します。指定されたコマンドバージョンがサポート対象外であった場合にはエラーが返されます。command\-versionが指定されなかった場合は、当該プロセス起動時にdefault\-command\-versionに指定した値が指定されたものとみなします。 .SS cache_limit .SS 名前 .sp cache_limit \- cacheサイズの設定・取得 .SS 書式 .sp .nf .ft C cache_limit max .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるcache_limitについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp cache_limitは、クエリキャッシュの最大件数を取得したり設定したりします。 .SS 引数 .sp \fBmax\fP .INDENT 0.0 .INDENT 3.5 クエリキャッシュの最大件数を整数で指定します。 maxが指定されなかった場合には、クエリキャッシュの最大件数は変更せず、 現在の設定値のみが返されます。 .UNINDENT .UNINDENT .SS 返値 .SS json .sp .nf .ft C [以前の設定値] \(ga\(ga以前の設定値\(ga\(ga すでに設定されていたクエリキャッシュの最大件数を返す。 .ft P .fi .SS 例 .sp .nf .ft C cache_limit 4 [100] .ft P .fi .SS check .SS 名前 .sp check \- オブジェクトの状態表示 .SS 書式 .sp .nf .ft C check obj .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるcheckについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp checkコマンドは、groongaプロセス内の指定したオブジェクトの状態を表示します。主にデータベースが壊れた場合など異常時の問題解決のために使用することを想定しています。デバッグ用のため、返値のフォーマットが安定しているということは保証されません。（フォーマットが変更される可能性が高い） .SS 引数 .sp \fBobj\fP .INDENT 0.0 .INDENT 3.5 状態を表示するオブジェクトの名前を指定します。 .UNINDENT .UNINDENT .SS 返値 .SS json形式 .sp チェックするオブジェクトにより返される値が変わります。 .sp インデックスカラムの場合: .sp .nf .ft C 下記のような配列が出力されます。 [インデックスの状態, バッファの状態1, バッファの状態2, ...] \(ga\(gaインデックスの状態\(ga\(gaには下記の項目がハッシュ形式で出力されます。 \(ga\(gaflags\(ga\(ga 指定されているフラグ値です。16進数で表現されています。 \(ga\(gamax sid\(ga\(ga セグメントのうち最も大きなIDです。 \(ga\(ganumber of garbage segments\(ga\(ga ゴミセグメントの数です。 \(ga\(ganumber of array segments\(ga\(ga 配列セグメントの数です。 \(ga\(gamax id of array segment\(ga\(ga 配列セグメントのうち最も大きなIDです。 \(ga\(ganumber of buffer segments\(ga\(ga バッファセグメントの数です。 \(ga\(gamax id of buffer segment\(ga\(ga バッファセグメントのうち最も大きなIDです。 \(ga\(gamax id of physical segment in use\(ga\(ga 使用中の論理セグメントのうち最も大きなIDです。 \(ga\(ganumber of unmanaged segments\(ga\(ga 管理されていないセグメントの数です。 \(ga\(gatotal chunk size\(ga\(ga チャンクサイズの合計です。 \(ga\(gamax id of chunk segments in use\(ga\(ga 使用中のチャンクセグメントのうち最も大きなIDです。 \(ga\(ganumber of garbage chunk\(ga\(ga 各チャンク毎のゴミの数です。 \(ga\(gaバッファの状態\(ga\(gaには下記の項目がハッシュ形式で出力されます。 \(ga\(gabuffer id\(ga\(ga バッファIDです。 \(ga\(gachunk size\(ga\(ga チャンクのサイズです。 \(ga\(gabuffer term\(ga\(ga バッファ内にある語の一覧です。各語の状態は以下のような配列となっています。 [語, バッファに登録されている語のID, 用語集に登録されている語のID, バッファ内でのサイズ, チャンク内でのサイズ] \(ga\(gabuffer free\(ga\(ga バッファの空き容量です。 \(ga\(gasize in buffer\(ga\(ga バッファの使用量です。 \(ga\(ganterms\(ga\(ga バッファ内にある語の数です。 \(ga\(ganterms with chunk\(ga\(ga バッファ内にある語のうち、チャンクを使っている語の数です。 .ft P .fi .SS 例 .sp テーブルTermsのインデックスカラムnameの状態を表示します。: .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 .SS clearlock .SS 名前 .sp clearlock \- オブジェクトにセットされたロックを解除する .SS 書式 .sp .nf .ft C clearlock objname .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるclearlockについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp clearlockは、対象となるオブジェクト(データベース,テーブル,インデックス等)を指定し、オブジェクトにかけられたロックを再帰的に解除します。 .SS 引数 .sp \fBobjname\fP .INDENT 0.0 .INDENT 3.5 対象となるオブジェクト名を指定します。空の場合、開いているdbオブジェクトが対象となります。 .UNINDENT .UNINDENT .sp 返値 \-\-\- .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp 開いているデータベースのロックをすべて解除する: .sp .nf .ft C clearlock [true] .ft P .fi .sp テーブル名 Entry のカラム body のロックを解除する: .sp .nf .ft C clearlock Entry.body [true] .ft P .fi .SS 関連項目 .sp \fBload\fP .SS column_create .SS 名前 .sp column_create \- カラムの追加 .SS 書式 .sp .nf .ft C column_create table name flags type [source] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるcolumn_createについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp column_createは、使用しているデータベースのテーブルに対してカラムを追加します。 .SS 引数 .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 インデックス型のカラムについては、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 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp テーブルEntryに、ShortText型の値を格納するカラム、bodyを作成します。: .sp .nf .ft C column_create Entry body \-\-type ShortText [true] .ft P .fi .sp テーブルTermに、Entryテーブルのbodyカラムの値を対象とする完全転置インデックス型カラム、entry_bodyを作成します。: .sp .nf .ft C column_create Term entry_body COLUMN_INDEX|WITH_POSITION Entry body [true] .ft P .fi .SS column_list .SS 名前 .sp column_list \- テーブルに定義されているカラムのリスト表示 .SS 書式 .sp .nf .ft C column_list table .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるcolumn_listについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp column_listはテーブルに定義されているカラムをリスト表示します。 .SS 引数 .INDENT 0.0 .TP .B \fBtable\fP カラム情報を出力するテーブルの名前を指定します。 .UNINDENT .SS 返値 .SS json形式 .sp カラム名一覧を以下の形式で返却します。: .sp .nf .ft C [[[カラム情報名1,カラム情報型1],...], カラム情報1,...] .ft P .fi .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 \fBtype\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 テーブルのkeyの型 .UNINDENT .UNINDENT .sp \fBsource\fP .INDENT 0.0 .INDENT 3.5 インデックスカラムのとき、インデックス対象カラム名の配列 .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 例 .sp .nf .ft C column_list Entry [[["id", "UInt32"], ["name","ShortText"], ["path","ShortText"], ["type","ShortText"], ["flags","ShortText"], ["domain", "ShortText"], ["range", "ShortText"], ["source","ShortText"]], [258, "Entry.body", "test.db.0000102", "var", "COLUMN_SCALAR|COMPRESS_NONE|PERSISTENT", "Entry", "ShortText", []]] .ft P .fi .sp 注: 実際は改行が入りません。 .SS column_remove .SS 名前 .sp column_remove \- テーブルに定義されているカラムの削除 .SS 書式 .sp .nf .ft C column_remove table name .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるcolumn_removeについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp column_removeはテーブルに定義されているカラムを削除します。 また、付随するインデックスも削除されます。[#]_ .SS 引数 .INDENT 0.0 .TP .B \fBtable\fP 削除対象のカラムが定義されているテーブルの名前を指定します。 .TP .B \fBname\fP 削除対象のカラム名を指定します。 .UNINDENT .SS 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp .nf .ft C column_remove Entry body [true] .ft P .fi 脚注 .IP [1] 5 マルチセクションインデックスの一部である場合も、インデックスが削除されます。 .SS define_selector .SS 名前 .sp define_selector \- 検索コマンドを定義 .SS 書式 .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 .SS 説明 .sp groonga組込コマンドの一つであるdefine_selectorについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp define_selectorは、検索条件をカスタマイズした新たな検索コマンドを定義します。 .SS 引数 .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 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp テーブルEntryの全レコード・全カラムの値を出力するselectorコマンドを定義します。: .sp .nf .ft C define_selector entry_selector Entry [true] .ft P .fi .SS 関連項目 .sp \fB../expr\fP .SS defrag .SS 名前 .sp defrag \- オブジェクトにセットされたロックを解除する .SS 書式 .sp .nf .ft C defrag objname threshold .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるdefragについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp defragは、対象となるオブジェクト(データベースか可変長サイズカラム)を指定し、オブジェクトのフラグメンテーションを解消します。 .SS 引数 .sp \fBobjname\fP .INDENT 0.0 .INDENT 3.5 対象となるオブジェクト名を指定します。空の場合、開いているdbオブジェクトが対象となります。 .UNINDENT .UNINDENT .SS 返値 .SS json形式 .sp .nf .ft C [フラグメンテーション解消を実行したセグメントの数] \(ga\(gaフラグメンテーション解消を実行したセグメントの数\(ga\(ga フラグメンテーション解消を実行したセグメントの数を返す。 .ft P .fi .SS 例 .sp 開いているデータベースのフラグメンテーションを解消する: .sp .nf .ft C defrag [300] .ft P .fi .sp テーブル名 Entry のカラム body のフラグメンテーションを解消する: .sp .nf .ft C defrag Entry.body [30] .ft P .fi .SS delete .SS 名前 .sp delete \- 一件のレコードの削除 .SS 書式 .sp .nf .ft C delete table [key [id [filter]]] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるdeleteについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp deleteは、使用しているデータベースのテーブルに1件のレコードを削除します。 .SS 引数 .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 レコードを削除しようとするテーブルの名前を指定します。 .UNINDENT .UNINDENT .sp \fBkey\fP .INDENT 0.0 .INDENT 3.5 削除するレコードの主キー値を指定します。主キーなしのテーブルの場合はこのパラメータを指定しても無視されます(idパラメータを代わりに指定します)。 .UNINDENT .UNINDENT .sp \fBid\fP .INDENT 0.0 .INDENT 3.5 レコードIDによってレコードを指定します。idパラメータを指定する場合は、keyパラメータを指定してはいけません。 .UNINDENT .UNINDENT .sp \fBfilter\fP .INDENT 0.0 .INDENT 3.5 script形式のgrn_expr文字列によってレコードを指定します。filterパラメータを指定する場合は、id及びkeyパラメータを指定してはいけません。 .UNINDENT .UNINDENT .sp 返値 \-\-\- .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp テーブルEntryからレコードを削除します。: .sp .nf .ft C delete Entry abandon [true] .ft P .fi .SS 関連項目 .sp \fBload\fP .SS dump .SS 名前 .sp dump \- データベースのスキーマとデータを出力する .SS 書式 .sp .nf .ft C dump [tables] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるdumpについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp dumpはデータベースのスキーマとデータを後から読み込めるフォーマットで出力します。dumpの結果は大きくなるため、主にコマンドラインから使うことを想定しています。データベースのバックアップが主な利用方法です。 .sp dumpが出力するフォーマットは直接groongaが解釈できるフォーマットです。そのため、以下のようにしてデータベースをコピーすることができます。: .sp .nf .ft C % groonga original/db dump > dump.grn % mkdir backup % groonga \-n backup/db < dump.grn .ft P .fi .SS 引数 .sp \fBtables\fP .INDENT 0.0 .INDENT 3.5 出力対象のテーブルを「,」（カンマ）区切りで指定します。存在しないテーブルを指定した場合は無視されます。 .UNINDENT .UNINDENT .SS 返値 .sp データベースのスキーマとデータをgroongaの組み込みコマンド呼び出し形式で出力します。output_type指定は無視されます。 .SS 例 .sp データベース内のすべてのデータを出力: .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 .sp データベース内のスキーマと特定のテーブルのデータのみ出力: .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 .SS load .SS 名前 .sp load \- データのロード .SS 書式 .sp .nf .ft C load values table [columns [ifexists [input_type]]] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるloadについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp loadは、使用しているデータベースのテーブルにレコードを登録し、カラムの値を更新します。 .SS 引数 .sp \fBvalues\fP .INDENT 0.0 .INDENT 3.5 input_typeに指定する形式で登録するレコードの値を表現した文字列を渡します。 .sp input_typeがjsonである場合には、以下のいずれかの形式が使用できます。 .INDENT 0.0 .TP .B \fB形式1\fP [[カラム名1, カラム名2,..], [カラム値1, カラム値2,..], [カラム値1, カラム値2,..],..] .TP .B \fB形式2\fP [{カラム名1: カラム値1, カラム名2: カラム値2}, {カラム名1: カラム値1, カラム名2: カラム値2},..] .UNINDENT .sp 形式1の[カラム名1, カラム名2,..]の要素はcolumns引数が省略された場合のみ有効です。 .sp 対象のテーブルが主キーを持つテーブルであった場合は、カラム名の中に\(aq_key\(aq(主キーを示す疑似カラム名)が含まれていなければなりません。 .sp values引数が省略された場合には、括弧の対応が取れるまで標準入力からvaluesの値を読み取ります。引数として値を指定する場合は、文字列のエスケープが必要ですが、標準入力から与える文字列はエスケープする必要がありません。 .sp 続きの文字列については、空白文字(\(aq \(aq)をエスケープする必要はありません。 .UNINDENT .UNINDENT .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 レコードを追加しようとするテーブルの名前を指定します。 .UNINDENT .UNINDENT .sp \fBcolumns\fP .INDENT 0.0 .INDENT 3.5 テーブルに登録するレコードに値を設定するカラム名のリストを、カンマ区切りで指定します。 .UNINDENT .UNINDENT .sp \fBifexists\fP .INDENT 0.0 .INDENT 3.5 指定した主キーに対応するレコードが既にテーブルに登録済みであった場合に実行するscript形式のgrn_expr文字列を指定します。ifexistsにgrn_exprが指定された場合は、式の値が真である場合に限り、その他のカラムの値が更新されます。(デフォルトはtrue) .UNINDENT .UNINDENT .sp \fBinput_type\fP .INDENT 0.0 .INDENT 3.5 入力形式を指定します。JSONのみに対応しています。 .UNINDENT .UNINDENT .SS 返値 .SS JSON形式 .sp .nf .ft C [登録件数] .ft P .fi .sp \fB登録件数\fP .INDENT 0.0 .INDENT 3.5 テーブルに登録されたレコードの件数が返されます。 .UNINDENT .UNINDENT .SS 例 .sp テーブルEntryにレコードを登録します。: .sp .nf .ft C load \-\-table Entry \-\-input_type json \-\-values [{\e"_key\e":\e"abandon\e",\e"body\e":\e"放棄する\e"}] [1] .ft P .fi .sp 標準入力からvaluesの値を与えます。: .sp .nf .ft C load \-\-table Entry \-\-input_type json [ {"_key": "abbreviate", "body": "短縮する"} ] [1] .ft P .fi .SS 関連項目 .sp \fB../expr\fP .SS log_level .SS 名前 .sp log_level \- ログ出力レベルの設定 .SS 書式 .sp .nf .ft C log_level level .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるlog_levelについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_levelは、ログ出力レベルを設定します。 .SS 引数 .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 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp .nf .ft C log_level warning [true] .ft P .fi .SS 関連項目 .sp \fBlog_put\fP \fBlog_reopen\fP .SS log_put .SS 名前 .sp log_put \- ログ出力 .SS 書式 .sp .nf .ft C log_put level message .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるlog_putについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_putは、ログにmessageを出力します。 .SS 引数 .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 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp .nf .ft C log_put ERROR ****MESSAGE**** [true] .ft P .fi .SS 関連項目 .sp \fBlog_level\fP \fBlog_reopen\fP .SS log_reopen .SS 名前 .sp log_reopen \- ログファイルの再読み込み .SS 書式 .sp .nf .ft C log_reopen .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるlog_reopenについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp log_reopenは、ログファイルを再読み込みします。 .sp 現在、デフォルトのログ関数を用いている場合のみに対応しています。 .SS 引数 .sp ありません。 .SS 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp .nf .ft C log_reopen [true] .ft P .fi .SS log_reopenを用いたログのローテーション .INDENT 0.0 .IP 1. 3 ログファイルをmvなどで移動する。 ログはmvで移動された先のファイルに書き込まれる。 .IP 2. 3 log_reopenコマンドを実行する。 .IP 3. 3 既存のログファイル名と同じファイル名で、新たなログファイルが作成される。 今後のログは新たなログファイルに書き込まれる。 .UNINDENT .SS 関連項目 .sp \fBlog_level\fP \fBlog_put\fP .SS quit .SS 名前 .sp quit \- セッション終了 .SS 書式 .sp .nf .ft C quit .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるquitについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp quitは、groongaプロセスとのセッションを終了します。クライアントプロセスならばgroongaプロセスとの接続を切ります。 .SS 引数 .sp ありません。 .SS 返値 .sp ありません。 .SS 例 .sp .nf .ft C quit .ft P .fi .SS select .SS 名前 .sp select \- テーブルの中から条件にマッチするレコードを検索して出力する .SS 書式 .sp .nf .ft C select table [match_columns [query [filter [scorer [sortby [output_columns [offset [limit [drilldown [drilldown_sortby [drilldown_output_columns [drilldown_offset [drilldown_limit [cache [match_escalation_threshold [query_expansion]]]]]]]]]]]]]]]] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるselectについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp selectは、使用しているデータベースのテーブルの中から条件にマッチするレコードを検索して出力します。 .SS 引数 .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 検索対象のテーブルを指定します。存在しないテーブルを指定した場合はエラーになります。 .UNINDENT .UNINDENT .sp \fBmatch_columns\fP .INDENT 0.0 .INDENT 3.5 query引数に指定する検索条件文字列でデフォルトの検索対象となるカラムを指定します。 .INDENT 0.0 .INDENT 3.5 カラム名 .UNINDENT .UNINDENT .sp カラム名の後ろに\(aq* 数値\(aqを指定することによって、そのカラムにヒットした際のスコアに積算される重みを指定することができます。 .INDENT 0.0 .INDENT 3.5 カラム名 * 重み .UNINDENT .UNINDENT .sp 複数のカラムを\(aq||\(aqで結合して指定することもできます。 .INDENT 0.0 .INDENT 3.5 カラム名1 * 重み1 || カラム名2 * 重み2 .UNINDENT .UNINDENT .sp また、カラム名ではなく、検索に使用するインデックス名を指定することもできます。 .UNINDENT .UNINDENT .sp \fBquery\fP .INDENT 0.0 .INDENT 3.5 以下の形式の文字列によって検索条件を指定します。 .UNINDENT .UNINDENT .SS 条件式 .sp 以下の条件式が使用できます。 .INDENT 0.0 .TP .B 文字列 全文検索条件(デフォルト検索対象カラムの値が指定された文字列を含んでいる) .TP .B "文字列" フレーズ検索条件(デフォルト検索対象カラムの値が指定されたフレーズを含んでいる) .TP .B カラム名:値 一致条件(カラム値 == 値) .TP .B カラム名:!値 不一致条件(カラム値 != 値) .TP .B カラム名:<値 比較条件(カラム値 < 値) .TP .B カラム名:>値 比較条件(カラム値 > 値) .TP .B カラム名:<=値 比較条件(カラム値 <= 値) .TP .B カラム名:>=値 比較条件(カラム値 >= 値) .TP .B カラム名:@文字列 全文検索条件(カラム値が指定された文字列を含んでいる) .UNINDENT .SS 結合演算子 .sp 複数の条件式を結合するために以下の演算子が使用できます。 .INDENT 0.0 .TP .B a OR b 論理和(aとbといずれかの条件がマッチする) .TP .B a + b 論理積(aとbの両方がマッチする) .TP .B a \- b aにマッチし、bにはマッチしない .TP .B ( ) 複数の条件をまとめる .UNINDENT .sp \fBfilter\fP .INDENT 0.0 .INDENT 3.5 絞り込み条件をscript形式のgrn_expr文字列によって指定します。 .sp query引数とfilter引数をどちらも指定した場合は、両方の条件を満足するレコードのみがヒットします。どちらも指定しない場合は全件がヒットします。 .UNINDENT .UNINDENT .sp \fBscorer\fP .INDENT 0.0 .INDENT 3.5 検索条件にマッチする全てのレコードに対して適用するgrn_exprをscript形式で指定します。 .sp scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。 .UNINDENT .UNINDENT .sp \fBsortby\fP .INDENT 0.0 .INDENT 3.5 ソートキーとなるカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。: .sp .nf .ft C [\-]カラム名1, [\-]カラム名2, [\-]カラム名3, ... .ft P .fi .sp カラム名1の値でソートし、値が同一である場合はカラム名2でソート、と順次比較を行いソートします。カラム名の前に \- を付加した場合は降順にソートします。付加しない場合には昇順にソートします。 .sp query引数またはfilter引数を指定した場合はカラム名に\(aq_score\(aqを使えます。\(aq_score\(aqを指定することでスコアでソートすることができます。query引数もfilter引数も指定していない状態で\(aq_score\(aqを指定するとエラーになります。 .UNINDENT .UNINDENT .sp \fBoutput_columns\fP .INDENT 0.0 .INDENT 3.5 出力するカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。 .sp アスタリスク(\(aq*\(aq)を指定すると、全てのカラムが指定されたものとみなされます。または、script形式のgrn_expr文字列を指定します。 (デフォルトは、\(aq_id, _key, *\(aq) .UNINDENT .UNINDENT .sp \fBoffset\fP .INDENT 0.0 .INDENT 3.5 検索条件にマッチしたレコードのうち、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。offsetに負の値を指定した場合は、ヒットした件数 + offset によって算出される値が指定されたものとみなされます。 .UNINDENT .UNINDENT .sp \fBlimit\fP .INDENT 0.0 .INDENT 3.5 検索条件にマッチしたレコードのうち、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、offset + limit がヒットした件数を超えない範囲でレコードが出力されます。limitに負の値を指定した場合は、ヒットした件数 + limit + 1 によって算出される値が指定されたものとみなされます。 .UNINDENT .UNINDENT .sp \fBdrilldown\fP .INDENT 0.0 .INDENT 3.5 グループ化のキーとなるカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。検索条件にマッチした各レコードを出力したのちに、drilldownに指定されたカラムの値が同一であるレコードをとりまとめて、それぞれについて結果レコードを出力します。 .UNINDENT .UNINDENT .sp \fBdrilldown_sortby\fP .INDENT 0.0 .INDENT 3.5 drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、ソートキーとなるカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。sortbyパラメータと同様に昇降順を指定できます。 .UNINDENT .UNINDENT .sp \fBdrilldown_output_columns\fP .INDENT 0.0 .INDENT 3.5 drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力するカラム名のリストをカンマ(\(aq,\(aq)区切りで指定します。 .UNINDENT .UNINDENT .sp \fBdrilldown_offset\fP .INDENT 0.0 .INDENT 3.5 drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。drilldown_offsetに負の値を指定した場合は、ヒットした件数 + drilldown_offsetによって算出される値が指定されたものとみなされます。 .UNINDENT .UNINDENT .sp \fBdrilldown_limit\fP .INDENT 0.0 .INDENT 3.5 drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、drilldown_offset + drilldown_limit がヒットした件数を超えない範囲でレコードが出力されます。drilldown_limitに負の値を指定した場合は、ヒットした件数 + drilldown_limit + 1 によって算出される値が指定されたものとみなされます。 .UNINDENT .UNINDENT .sp \fBcache\fP .INDENT 0.0 .INDENT 3.5 クエリキャッシュに関する動作を設定します。 .INDENT 0.0 .INDENT 3.5 \fBno\fP .INDENT 0.0 .INDENT 3.5 検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBmatch_escalation_threshold\fP .INDENT 0.0 .INDENT 3.5 検索の挙動をエスカレーションするかどうかの閾値を設定します。デフォルト値は0です。デフォルト値は以下のいずれかの方法で設定できます。 .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 configureの\-\-with\-match\-escalation\-thresholdオプション .IP \(bu 2 groongaコマンド起動時の\-\-match\-escalation\-thresholdオプション .IP \(bu 2 設定ファイル中のmatch\-escalation\-threshold設定項目 .UNINDENT .UNINDENT .UNINDENT .sp クエリのヒット件数が閾値を越えない場合は \fB/spec/search\fP で説明している方法で検索方法をエスカレーションしてきます。 .UNINDENT .UNINDENT .sp \fBquery_expansion\fP .INDENT 0.0 .INDENT 3.5 query_expansionパラメータには、queryパラメータに指定された文字列を置換(拡張)する条件となるテーブル・カラムを指定します。フォーマットは「${テーブル名}.${カラム名}」となります。指定するテーブルは文字列を主キーとするハッシュ型あるいはパトリシア木型のテーブルで、一つ以上の文字列型のカラムが定義されている必要があります。(ここでは置換テーブルと呼びます。) .sp queryパラメータに指定された文字列が、指定されたテーブルの主キーと完全一致する場合、その文字列を指定されたカラム値の文字列に置換します。queryパラメータが、空白、括弧、演算子などを含む場合は、その演算子によって区切られた文字列の単位で置換が実行されます。ダブルクォート("")で括られた範囲は、その内部に空白を含んでいても一つの置換される単位と見なされます。検索文字列と置換テーブルの主キー値との比較に際して大文字小文字等を区別したくない場合には、置換テーブルを定義する際にKEY_NORMALIZEを指定します。置換後の文字列となるカラムの値には、括弧や*, ORなど、queryパラメータで利用可能な全ての演算子を指定することができます。 .UNINDENT .UNINDENT .SS 返値 .sp 以下のようなjson形式で値が返却されます。 .sp .nf .ft C [[リターンコード, 処理開始時間, 処理時間], [検索結果, ドリルダウン結果]] .ft P .fi .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条件が実行される前の検索結果が以下のように出力されます。: .sp .nf .ft C [[検索件数], [[カラム名1,カラム型1],..], 検索結果1,..] .ft P .fi .sp \fB検索件数\fP .INDENT 0.0 .INDENT 3.5 検索件数が出力されます。 .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処理の結果が以下のように出力されます。: .sp .nf .ft C [[[件数], [[カラム名1,カラム型1],..], 検索結果1,..],..] .ft P .fi .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 例 .sp テーブルEntryの全レコード・全カラムの値を出力します。: .sp .nf .ft C select Entry [[[2],[["_id", "UInt32"],["_key","ShortText"],["body","ShortText"]],[1,"abandon","放棄する"],[2,"abbreviate","短縮する"]]] .ft P .fi .SS 関連項目 .sp \fB../expr\fP .SS shutdown .SS 名前 .sp shutdown \- サーバプロセスの停止 .SS 書式 .sp .nf .ft C shutdown .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるshutdownについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp shutdownは、接続しているgroongaサーバプロセスを停止します。 .SS 引数 .sp ありません。 .SS 返値 .sp ありません。 .SS 例 .sp .nf .ft C shutdown .ft P .fi .SS status .SS 名前 .sp status \- groongaプロセスの状態表示 .SS 書式 .sp .nf .ft C status .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるstatusについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp statusコマンドは、groongaプロセスの状態を表示します。主にgroongaサーバプロセスに対して使用することを想定しています。 .SS 引数 .sp ありません。 .SS 返値 .SS json形式 .sp .nf .ft C 下記の項目がハッシュ形式で出力されます。 \(ga\(gaalloc_count\(ga\(ga groongaプロセスの内部でアロケートされ、まだ解放されてないメモリブロックの数を示します。groongaをbuildする際に、configureオプションで \-\-enable\-exact\-alloc\-countが指定されていたならば、正確な値を返します。それ以外の場合は不正確な値を返す場合があります。 \(ga\(gastarttime\(ga\(ga groongaプロセスが起動した時刻のtvsec値を返します。 \(ga\(gauptime\(ga\(ga groongaプロセスが起動してから経過した秒数を返します。 .ft P .fi .SS 例 .sp .nf .ft C status {"alloc_count":104, "starttime":1268213679, "uptime":1} .ft P .fi .SS suggest .IP Note The suggest feature specification isn\(aqt stable. The specification may be changed. .RE .SS NAME .sp suggest \- returns completion, correction and/or suggestion for a query. .SS SYNOPSIS .sp .nf .ft C suggest types table column query [sortby [output_columns [offset [limit [frequency_threshold [conditional_probability_threshold [prefix_search]]]]]]] .ft P .fi .SS DESCRIPTION .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 OPTIONS .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: .sp .nf .ft C correct .ft P .fi .sp It returns correction and suggestion: .sp .nf .ft C correct|suggest .ft P .fi .sp It returns complete, correction and suggestion: .sp .nf .ft C complete|correct|suggest .ft P .fi .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: .sp .nf .ft C groonga\-suggest\-create\-dataset /tmp/db\-path query .ft P .fi .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 .UNINDENT .SS RETURN VALUE .SS JSON format .sp Here is a returned JSON format: .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 .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 EXAMPLE .sp Here are learned data for completion. .sp Execution example: .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,1317212843.70335,1.584911917],6] .ft P .fi .sp Here are learned data for correction. .sp Execution example: .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,1317212845.48948,2.003051709],8] .ft P .fi .sp Here are learned data for suggestion. .sp Execution example: .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,1317212847.69365,0.801326259],2] .ft P .fi .sp Here is a completion example. .sp Execution example: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types complete \-\-frequency_threshold 1 \-\-query en [[0,1317212848.69611,0.00164469],{"complete":[[1],[["_key","ShortText"],["_score","Int32"]],["engine",1]]}] .ft P .fi .sp Here is a correction example. .sp Execution example: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types correct \-\-frequency_threshold 1 \-\-query saerch [[0,1317212848.8995,0.00037794],{"correct":[[1],[["_key","ShortText"],["_score","Int32"]],["search",1]]}] .ft P .fi .sp Here is a suggestion example. .sp Execution example: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types suggest \-\-frequency_threshold 1 \-\-query search [[0,1317212849.10158,0.000376811],{"suggest":[[2],[["_key","ShortText"],["_score","Int32"]],["search engine",1],["web search realtime",1]]}] .ft P .fi .sp Here is a mixed example. .sp Execution example: .sp .nf .ft C > suggest \-\-table item_query \-\-column kana \-\-types complete|correct|suggest \-\-frequency_threshold 1 \-\-query search [[0,1317212849.30453,0.001329747],{"complete":[[2],[["_key","ShortText"],["_score","Int32"]],["search",2],["search engine",2]],"correct":[[1],[["_key","ShortText"],["_score","Int32"]],["search",2]],"suggest":[[2],[["_key","ShortText"],["_score","Int32"]],["search engine",1],["web search realtime",1]]}] .ft P .fi .SS SEE ALSO .INDENT 0.0 .IP \(bu 2 \fB/suggest\fP .IP \(bu 2 \fB/executables/groonga\-suggest\-create\-dataset\fP .UNINDENT .SS table_create .SS 名前 .sp table_create \- テーブルの追加 .SS 書式 .sp .nf .ft C table_create name [flags [key_type [value_type [default_tokenizer]]]] .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるtable_createについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp table_createコマンドは、使用しているデータベースに対してテーブルを追加します。groongaには名前付きテーブルと名前なしテーブル、永続テーブルと一時テーブルがありますが、table_createコマンドでは、名前付きの永続テーブルのみが作成できます。テーブルはレコードの集合であり、全てのレコードは一意なIDを持ちます。IDはレコードを追加した順序に従って自動的に付与されます。 .sp テーブルにカラムを追加する時にはcolumn_createコマンドを使用します。また、テーブルを作成した時点でいくつかの疑似カラムが使用可能になっています。 .SS 引数 .sp \fBname\fP .INDENT 0.0 .INDENT 3.5 作成するテーブルの名前を指定します。nameはデータベース内で一意な、未定義の名前でなければなりません。組込型名・組込コマンド名・組込関数名は予約済みであり、テーブル名には 使用できません。また、ピリオド(\(aq.\(aq), コロン(\(aq:\(aq)を含む名前のテーブルは作成できません。 .UNINDENT .UNINDENT .sp \fBflags\fP .INDENT 0.0 .INDENT 3.5 作成するテーブルの属性を示す数値か、パイプ(\(aq|\(aq)で組み合わせたシンボル名を指定します。(デフォルト値は0(="TABLE_HASH_KEY")) .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B 0, \fBTABLE_HASH_KEY\fP 主キー値をハッシュ表で管理するテーブルを作成します。ハッシュ表を使用したテーブルでは、主キー値に完全一致するレコードを非常に高速に検索することができます。 .TP .B 1, \fBTABLE_PAT_KEY\fP 主キー値をパトリシア木で管理するテーブルを作成します。パトリシア木を使用したテーブルでは、主キー値に完全一致するレコードを検索することができるとともに、前方一致するレコード、および最長共通接頭辞となるレコードを高速に検索することができます。また、キー値の昇降順でレコードを取り出したり、キー値の範囲での検索を行うことができます。また、flagsの値に64を加えることによって、後方一致検索も可能となります。 .TP .B 2, \fBTABLE_DAT_KEY\fP 主キー値をダブル配列で管理するテーブルを作成します。ダブル配列を使用したテーブルでは、主キー値に完全一致するレコードを高速に検索することができるとともに、前方一致するレコード、および最長共通接頭辞となるレコードを検索することができます。また、キー値の昇降順でレコードを取り出したり、キー値の範囲での検索を行うことができます。 .TP .B 3, \fBTABLE_NO_KEY\fP 主キーを持たないテーブルを作成します。各レコードはIDのみによって特定することができます。 .TP .B 4, \fBTABLE_VIEW\fP 複数のテーブルをまとめて操作するための仮想的なテーブル(view)を作成します。 .TP .B 64, \fBKEY_WITH_SIS\fP 語彙表となるパトリシア木型のテーブルにおいて、後方一致検索を可能とします。 .TP .B 128, \fBKEY_NORMALIZE\fP ハッシュ表型か、パトリシア木型のテーブルにおいて、主キー値を正規化した上で登録します。この値が指定されたテーブルではたとえば、主キー値\(aqabc\(aqと\(aqABC\(aq は同一のレコードに対応するものとみなされます。 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBkey_type\fP .INDENT 0.0 .INDENT 3.5 主キー値の型を指定します。主キー値を持つテーブルに限り有効です。型にはgroongaの組込型か、同一データベースに定義済みのユーザ定義型、定義済みのテーブルを指定することができます。 .UNINDENT .UNINDENT .sp \fBvalue_type\fP .INDENT 0.0 .INDENT 3.5 値の型を指定します。tableの値には固定長の型のみが指定できます。(可変長の値が必要な場合は別途カラムを作成します) 型にはgroongaの組込型か、同一データベースに定義済みのユーザ定義型、またはテーブルを指定することができます。(デフォルトはvalueなし) .UNINDENT .UNINDENT .sp \fBdefault_tokenizer\fP .INDENT 0.0 .INDENT 3.5 作成するテーブルを語彙表として使用する場合、文字列を分割するトークナイザを指定します。 .sp 組込のトークナイザとして、以下が準備されています。 .INDENT 0.0 .TP .B \fBTokenDelimit\fP 空白で区切られた文字列をトークンとする .TP .B \fBTokenUnigram\fP unigram(1文字を1トークンとする) .TP .B \fBTokenBigram\fP bigram(2文字の文字列要素をトークンとする) .TP .B \fBTokenTrigram\fP trigram(3文字の文字列要素をトークンとする) .TP .B \fBTokenMecab\fP 形態素解析器mecabで解析した形態素をトークンとする。(mecabを組み込んだ場合のみ有効) .UNINDENT .sp トークナイザが指定されなかった場合は、対象の文字列を分割せずに語彙表に登録します。 .UNINDENT .UNINDENT .SS 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp ShortText型の主キーを持つハッシュ表型のテーブル、Entryを作成します。: .sp .nf .ft C table_create Entry \-\-key_type ShortText [true] .ft P .fi .sp ShortText型の主キーを持つパトリシア木型のテーブル、Termを作成します。主キー値は正規化して管理します。また、このテーブルを語彙表とする転置索引を作成する場合には、バイグラムの索引を作成します。: .sp .nf .ft C table_create Term \-\-flags TABLE_PAT_KEY|KEY_NORMALIZE \-\-key_type ShortText \-\-default_tokenizer TokenBigram [true] .ft P .fi .SS table_list .SS 名前 .sp table_list \- DBに定義されているテーブルをリスト表示 .SS 書式 .sp .nf .ft C table_list .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるtable_listについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp table_listは、DBに定義されているテーブルのリストを表示します。 .SS 引数 .sp ありません。 .SS 返値 .SS json形式 .sp テーブル名一覧が以下の形式で返却されます。: .sp .nf .ft C [[[テーブル情報名1,テーブル情報型1],...], テーブル情報1,...] .ft P .fi .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 例 .sp .nf .ft C table_list Entry [[["id", "UInt32"], ["name","ShortText"], ["path","ShortText"], ["flags","ShortText"], ["domain", "ShortText"], ["range","ShortText"]], [256, "Entry", "test.db.0000100", "TABLE_HASH_KEY|PERSISTENT", "ShortText", "null"], [257, "Term", "test.db.0000101", "TABLE_PAT_KEY|KEY_NORMALIZE|PERSISTENT", "ShortText", "null"]] .ft P .fi .sp 注: 実際は改行が入りません。 .SS table_remove .SS 名前 .sp table_remove \- テーブルの削除 .SS 書式 .sp .nf .ft C table_remove table .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるtable_removeについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp table_removeはテーブルと定義されているカラムを削除します。カラムに付随するインデックスも再帰的に削除されます。 .SS 引数 .INDENT 0.0 .TP .B \fBtable\fP 削除対象のカラムが定義されているテーブルの名前を指定します。 .UNINDENT .SS 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .sp .nf .ft C column_remove Entry body [true] .ft P .fi .SS view_add .SS 名前 .sp view_add \- view型のテーブルに要素となるテーブルを追加 .SS 書式 .sp .nf .ft C view_add view table .ft P .fi .SS 説明 .sp groonga組込コマンドの一つであるview_addについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。 .sp view_addは、view型のテーブルに要素となるテーブルを定義します。 .SS 引数 .sp \fBview\fP .INDENT 0.0 .INDENT 3.5 テーブルを追加するview型のテーブルの名前を指定します。 .UNINDENT .UNINDENT .sp \fBtable\fP .INDENT 0.0 .INDENT 3.5 view型のテーブルに追加されるテーブルの名前を指定します。 .UNINDENT .UNINDENT .SS 返値 .SS json形式 .sp .nf .ft C [成功かどうかのフラグ] \(ga\(ga成功かどうかのフラグ\(ga\(ga エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。 .ft P .fi .SS 例 .INDENT 0.0 .TP .B :: view_add Ventry Entry [true] .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 bool型。trueとfalse。 .UNINDENT .UNINDENT .sp \fBInt8\fP .INDENT 0.0 .INDENT 3.5 8bit符号付き整数。 .UNINDENT .UNINDENT .sp \fBUInt8\fP .INDENT 0.0 .INDENT 3.5 8bit符号なし整数。 .UNINDENT .UNINDENT .sp \fBInt16\fP .INDENT 0.0 .INDENT 3.5 16bit符号付き整数。 .UNINDENT .UNINDENT .sp \fBUInt16\fP .INDENT 0.0 .INDENT 3.5 16bit符号なし整数。 .UNINDENT .UNINDENT .sp \fBInt32\fP .INDENT 0.0 .INDENT 3.5 32bit符号付き整数。 .UNINDENT .UNINDENT .sp \fBUInt32\fP .INDENT 0.0 .INDENT 3.5 32bit符号なし整数。 .UNINDENT .UNINDENT .sp \fBInt64\fP .INDENT 0.0 .INDENT 3.5 64bit符号付き整数。 .UNINDENT .UNINDENT .sp \fBUInt64\fP .INDENT 0.0 .INDENT 3.5 64bit符号なし整数。 .UNINDENT .UNINDENT .sp \fBFloat\fP .INDENT 0.0 .INDENT 3.5 ieee754形式の64bit浮動小数点数。 .UNINDENT .UNINDENT .sp \fBTime\fP .INDENT 0.0 .INDENT 3.5 1970年1月1日0時0分0秒からの経過マイクロ秒数を64bit符号付き整数で表現した値。 .UNINDENT .UNINDENT .sp \fBShortText\fP .INDENT 0.0 .INDENT 3.5 4Kbyte以下の文字列。 .UNINDENT .UNINDENT .sp \fBText\fP .INDENT 0.0 .INDENT 3.5 64Kbyte以下の文字列。 .UNINDENT .UNINDENT .sp \fBLongText\fP .INDENT 0.0 .INDENT 3.5 2Gbyte以下の文字列。 .UNINDENT .UNINDENT .sp \fBTokyoGeoPoint\fP .INDENT 0.0 .INDENT 3.5 日本測地系緯度経度座標。緯度と経度はミリ秒単位での整数。 "経度のミリ秒x緯度のミリ秒"という文字列表現を持つ。 度分秒形式であれば、x度y分z秒は(((x * 60) + y) * 60 + z) * 1000という計算式で変換した値を代入します。 .UNINDENT .UNINDENT .sp \fBWGS84GeoPoint\fP .INDENT 0.0 .INDENT 3.5 世界測地系緯度経度座標。緯度と経度はミリ秒単位での整数。 "経度のミリ秒x緯度のミリ秒"という文字列表現を持つ。 度分秒形式であれば、x度y分z秒は(((x * 60) + y) * 60 + z) * 1000という計算式で変換した値を代入します。 .UNINDENT .UNINDENT .SS 型に関する制限事項 .SS テーブルの主キーに指定できない型 .sp Text型とLongText型については、テーブルの主キーに指定することはできません。 .SS ベクターとして格納できない型 .sp groongaのカラムは、ある型のベクターを保存することができます。しかし、ShortText, Text, LongTextの３つの型についてはベクターとして保存したり出力したりすることはできますが、検索条件やドリルダウン条件に指定することができません。 .sp テーブル型は、ベクターとして格納することができます。よって、ShortTextのベクターを検索条件やドリルダウン条件に使用したい場合には、主キーがShortText型のテーブルを別途作成し、そのテーブルを型として利用します。 脚注 .IP [1] 5 Object型はv1.2でサポートされます。 .SS 疑似カラム (pseudo_column) .SS 名前 .sp 疑似カラム .SS 説明 .sp groongaのデータベースで作成したテーブルには、いくつかのカラムが自動的に定義されます。 .sp これらのカラムはいずれもアンダースコア(\(aq_\(aq)で始まる名前が付与されます。定義される疑似カラムは、テーブルの種類によって異なります。 .sp \fB_id\fP .INDENT 0.0 .INDENT 3.5 レコードに付与される一意な番号です。全てのテーブルに定義されます。値の範囲は1〜1073741824の整数で、通常はレコードを追加した順に1ずつ加算されます。_idの値は不変で、レコードが存在する限り変更することはできません。ただし、削除されたレコードの_idの値は再利用されます。 .UNINDENT .UNINDENT .sp \fB_key\fP .INDENT 0.0 .INDENT 3.5 レコードの主キー値を表します。主キーを持つテーブルのみに定義されます。主キー値はテーブルの中で一意であり、変更することはできません。 .UNINDENT .UNINDENT .sp \fB_value\fP .INDENT 0.0 .INDENT 3.5 レコードの値を表します。value_typeを指定したテーブルのみに定義されます。自由に変更可能です。 .UNINDENT .UNINDENT .sp \fB_score\fP .INDENT 0.0 .INDENT 3.5 各レコードのスコア値を表します。検索結果として生成されたテーブルのみに定義されます。 .sp 検索処理を実行する過程で値が設定されますが、自由に変更可能です。 .UNINDENT .UNINDENT .sp \fB_nsubrecs\fP .INDENT 0.0 .INDENT 3.5 主キーの値が同一であったレコードの件数を表します。検索結果として生成されたテーブルのみに定義されます。グループ化(drilldown)処理を実行すると、グループ化前のテーブルにおいて、グループ化キーの値が同一であったレコードの件数が、グループ化処理の結果を格納するテーブルの_nsubrecsに記録されます。 .UNINDENT .UNINDENT .SS grn_expr .SS 名前 .sp grn_expr \- 検索条件やデータベースへの操作を表現するデータ構造(読み方:"ぐるんしき") .SS 説明 .sp grn_exprは、検索条件やデータベースへの操作を表現するために使用されるデータ構造の形式です。 .sp データベースの中から特定の条件を満たすレコードを取り出すために、様々な条件をand,or,notなどの演算子で結合して自由に表現することができます。grn_exprは、一連のAPI関数を呼ぶことによって組み立てることができます。特定の文字列形式には依存していません。組み込みコマンドselectのqueryパラメータでは、検索エンジンのユーザがフォームで入力する文字列を直接受け取ることを想定して、文字列からgrn_exprを生成しています。また、多くの組み込みコマンドで共通に使用するために、ECMAScript形式の文字列からgrn_exprを生成するAPI関数grn_expr_parse()を用意しています。grn_expr_parseでパースできる文字列を特にscript形式のgrn_exprと呼びます。 .sp grn_exprを使うことによって非常に柔軟に検索条件を記述することができます。類似文書検索や近傍検索のような高度な検索もすべてgrn_exprによって記述できます。また、全文検索クエリにおいて、特定の文字列を含むレコードのスコアを細かく制御したり、検索結果数の多寡に応じてより検索漏れの少ないアルゴリズムで再検索するような機能も、grn_exprとgrn_table_select()API関数を組み合わせることによって自由に定義できます。 .SS script形式のgrn_expr .sp ECMAScript風の構文で検索条件やレコードへの操作を記述します。 .sp 式中のIDENTIFIER(識別子)は、以下のいずれかを指します。 .INDENT 0.0 .TP .B 引数名 grn_exprが受け取る引数の名前 .TP .B カラム名 操作対象としているレコードのカラム名 .TP .B 型名・関数名・テーブル名 データベースに定義された型・テーブル・関数の名前 .UNINDENT .SS 例 .sp script形式でcolumn1の値が\(aqhoge\(aqに等しいという条件 .INDENT 0.0 .INDENT 3.5 column1 == "hoge" .UNINDENT .UNINDENT 脚注.SS 組み込み関数一覧 .SS edit_distance .SS 名前 .sp edit_distance \- 指定した2つの文字列の編集距離を計算する .SS 書式 .sp .nf .ft C edit_distance(string1, string2) .ft P .fi .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 例 .sp .nf .ft C edit_distance(title, "hoge") 1 .ft P .fi .SS geo_distance .SS 名前 .sp geo_distance \- 指定した2点の距離を計算する .SS 書式 .sp .nf .ft C geo_distance(point1, point2[, approximate_type]) .ft P .fi .SS 説明 .sp groonga組込関数の一つであるgeo_distanceについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp geo_distance() 関数は、point1に指定した座標とpoint2に指定した座標の間の距離(近似値)を求めます。 .sp ... note: .sp .nf .ft C geo_distance()の他に、距離計算アルゴリズムの異なる、geo_distance2()、geo_distance3()がありましたが、1.2.9から非推奨になりました。 \(ga\(gageo_distance2()\(ga\(ga の代わりに \(ga\(gageo_distance(point1, point2, "sphere")\(ga\(ga を、 \(ga\(gageo_distance3()\(ga\(ga の代わりに \(ga\(gageo_distance(point1, point2, "ellipsoid")\(ga\(ga を使ってください。 .ft P .fi .SS 引数 .sp \fBpoint1\fP .INDENT 0.0 .INDENT 3.5 距離を求める2点のうち一つを指定します。GeoPoint型の値を指定できます。 [1] .UNINDENT .UNINDENT .sp \fBpoint2\fP .INDENT 0.0 .INDENT 3.5 距離を求める2点のうちもう一つを指定します。GeoPoint型の値、あるいは座標を示す文字列を指定できます。 .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 指定した2点の距離をFloat型の値(単位:メートル)として返します。 .SS 例 .sp .nf .ft C geo_distance(pos, "150x150") 100.0 # 方形近似を利用 geo_distance(pos, "150x150", "rectangle") 100.0 # 球面近似を利用 geo_distance(pos, "150x150", "sphere") 100.0 # 楕円体近似を利用 geo_distance(pos, "150x150", "ellipsoid") 100.0 .ft P .fi 脚注 .IP [1] 5 TokyoGeoPoint(日本測地系座標)かWGS84GeoPoint(世界測地系座標)のいずれかを指定できます。 .SS geo_in_circle .SS 名前 .sp geo_in_circle \- 座標が円の範囲内に存在するかどうかを調べます。 .SS 書式 .sp .nf .ft C geo_in_circle(point, center, radious_or_point[, approximate_type]) .ft P .fi .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 例 .sp .nf .ft C geo_in_circle(pos, "100x100", 100) true .ft P .fi 脚注 .IP [1] 5 TokyoGeoPoint(日本測地系座標)かWGS84GeoPoint(世界測地系座標)のいずれかを指定できます。 .SS geo_in_rectangle .SS 名前 .sp geo_in_rectangle \- 座標が矩形の範囲内に存在するかどうかを調べます。 .SS 書式 .sp .nf .ft C geo_in_rectangle(point, top_left, bottom_right) .ft P .fi .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 例 .sp .nf .ft C geo_in_rectangle(pos, "150x100", "100x150") true .ft P .fi 脚注 .IP [1] 5 TokyoGeoPoint(日本測地系座標)かWGS84GeoPoint(世界測地系座標)のいずれかを指定できます。 .SS now .SS 名前 .sp now \- 現在時刻を返す .SS 書式 .sp .nf .ft C now() .ft P .fi .SS 説明 .sp groonga組込関数の一つであるnowについて説明します。組込関数は、script形式のgrn_expr中で呼び出すことができます。 .sp now() 関数は現在時刻に対応するTime型の値を返します。 .SS 返値 .sp 現在時刻に対応するTime型のオブジェクトを返します。 .SS 例 .sp .nf .ft C now() 1256791194.55541 .ft P .fi .SS rand .SS 名前 .sp rand \- 乱数を生成する .SS 書式 .sp .nf .ft C rand([max]) .ft P .fi .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 例 .sp .nf .ft C rand(10) 3 .ft P .fi .SS Indexing .sp Groonga supports both online index construction and offline index construction since 1.3.1. .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: .sp .nf .ft C > table_create Tweets TABLE_NO_KEY [[0,1330339027.61804,0.000236272811889648],true] > column_create Tweets content COLUMN_SCALAR ShortText [[0,1330339027.81905,0.000560760498046875],true] > table_create Lexicon TABLE_HASH_KEY|KEY_NORMALIZE ShortText \-\-default_tokenizer TokenBigram [[0,1330339028.02028,0.000248432159423828],true] .ft P .fi .sp We register data: .sp Execution example: .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,1330339028.22155,1.00183534622192],3] .ft P .fi .sp We search without index. We get no result: .sp Execution example: .sp .nf .ft C > select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq [[0,1330339029.42452,0.000802278518676758],[[[0],[["_id","UInt32"],["content","ShortText"]]]]] .ft P .fi .sp We create index for \fBTweets.content\fP. Already registered data in \fBTweets.content\fP are indexed by offline index construction: .sp Execution example: .sp .nf .ft C > column_create Lexicon tweet COLUMN_INDEX|WITH_POSITION Tweets content [[0,1330339029.62682,0.00742125511169434],true] .ft P .fi .sp We search with index. We get a matched record: .sp Execution example: .sp .nf .ft C > select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq [[0,1330339029.83545,0.000765085220336914],[[[1],[["_id","UInt32"],["content","ShortText"]],[3,"I\(aqm sleepy... Have a nice day... Good night..."]]]] .ft P .fi .sp We register data again. They are indexed by online index construction: .sp Execution example: .sp .nf .ft C > load \-\-table Tweets > [ > {"content":"Good morning! Nice day."}, > {"content":"Let\(aqs go shopping."} > ] [[0,1330339030.03821,0.801372528076172],2] .ft P .fi .sp We can also get newly registered records by searching: .sp Execution example: .sp .nf .ft C > select Tweets \-\-match_columns content \-\-query \(aqgood nice\(aq [[0,1330339031.04064,0.000650644302368164],[[[2],[["_id","UInt32"],["content","ShortText"]],[3,"I\(aqm sleepy... Have a nice day... Good night..."],[4,"Good morning! Nice day."]]]] .ft P .fi .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: .sp .nf .ft C #{TIME_STAMP}|#{L}| #{MESSAGE} .ft P .fi .INDENT 0.0 .TP .B TIME_STAMP It\(aqs time stamp uses the following format: .sp .nf .ft C YYYY\-MM\-DD hh:mm:ss.SSSSSS .ft P .fi .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: .sp .nf .ft C 2011\-07\-05 06:25:18.345734 .ft P .fi .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: .sp .nf .ft C E .ft P .fi .TP .B MESSAGE Details about the log with free format. .sp Example: .sp .nf .ft C log opened. .ft P .fi .UNINDENT .sp Example: .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 .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: .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 .INDENT 0.0 .TP .B TIME_STAMP It\(aqs time stamp uses the following format: .sp .nf .ft C YYYY\-MM\-DD hh:mm:ss.SSSSSS .ft P .fi .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: .sp .nf .ft C 2011\-07\-05 06:25:18.345734 .ft P .fi .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: .sp .nf .ft C 45ea3034 .ft P .fi .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: .sp .nf .ft C query log opened. .ft P .fi .TP .B QUERY A query to be processed. .sp Example: .sp .nf .ft C select users \-\-match_columns hobby \-\-query music .ft P .fi .TP .B ELAPSED_TIME Elapsed time in nanoseconds since query is started. .sp Example: .sp .nf .ft C 000000000075770 (It means 75,770 nanoseconds.) .ft P .fi .TP .B PROGRESS A processed work at the time. .sp Example: .sp .nf .ft C select(313401) (It means that \(aqselect\(aq is processed and 313,401 records are remained.) .ft P .fi .TP .B RETURN_CODE A return code for the query. .sp Example: .sp .nf .ft C rc=0 (It means return code is 0. 0 means GRN_SUCCESS.) .ft P .fi .UNINDENT .sp Example: .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 .SH 仕様 .SS 検索 .sp \fB/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 例えば、以下のようなクエリの場合は、それぞれの検索でヒット件数が閾値以下の場合は完全一致検索、非わかち書き検索、部分一致検索を順に行います。: .sp .nf .ft C select Shops \-\-match_column description \-\-query スープカレー .ft P .fi .sp しかし、以下のように全文検索を行う前に検索結果セットが存在する場合は完全一致検索のみを行います。（point > 3で閾値の件数よりヒットしている場合）: .sp .nf .ft C select Shops \-\-filter \(aq"point > 3 && description @ \e"スープカレー\e""\(aq .ft P .fi .sp そのため、descriptionに「スープカレーライス」が含まれていても、「スープカレーライス」は「スープカレー」に完全一致しないのでヒットしません。 .SH LIMITATIONS .sp Groonga has some limitations. .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 26 million) .IP \(bu 2 The maximum number of distinct terms: 268,435,455 (more than 26 million) .IP \(bu 2 The maximum index size: 256GBytes .UNINDENT .sp Keep in mind that these limitations may vary depending on conditions. .SH トラブルシューティング .SS 同じ検索キーワードなのに全文検索結果が異なる .sp 同じ検索キーワードでも一緒に指定するクエリによっては全文検索の結果が異なることがあります。ここでは、その原因と対策方法を説明します。 .SS 例 .sp まず、実際に検索結果が異なる例を説明します。 .sp DDLは以下の通りです。BlogsテーブルのbodyカラムをTokenMecabトークナイザーを使ってトークナイズしてからインデックスを作成しています。: .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 .sp テスト用のデータは1件だけ投入します。: .sp .nf .ft C load \-\-table Blogs [ ["body", "updated_at"], ["東京都民に深刻なダメージを与えました。", "2010/9/21 10:18:34"], ] .ft P .fi .sp まず、全文検索のみで検索します。この場合ヒットします。: .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 .sp 続いて、範囲指定と全文検索を組み合わせて検索します（1285858800は2010/10/1 0:0:0の秒表記）。この場合もヒットします。: .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 .sp 最後に、範囲指定と全文検索の順番を入れ替えて検索します。個々の条件は同じですが、この場合はヒットしません。: .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 .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件もヒットしない場合でも部分一致検索などを行いません。: .sp .nf .ft C select Blogs \-\-filter \(aqupdated_at < 1285858800 && body @ "東京都"\(aq .ft P .fi .sp そのため、条件の順序を変えると検索結果が変わるという状況が発生します。以下で、この情報を回避する方法を2種類紹介しますが、それぞれトレードオフとなる条件があるので採用するかどうかを十分検討してください。 .SS 対策方法1: トークナイザーを変更する .sp TokenMecabトークナイザーは事前に準備した辞書を用いてトークナイズするため、再現率よりも適合率を重視したトークナイザーと言えます。一方、TokenBigramなど、N\-gram系のトークナイザーは適合率を重視したトークナイザーと言えます。例えば、TokenMecabの場合「東京都」で「京都」に完全一致することはありませんが、TokenBigramでは完全一致します。一方、TokenMecabでは「東京都民」に完全一致しませんが、TokenBigramでは完全一致します。 .sp このようにN\-gram系のトークナイザーを指定することにより再現率をあげることができますが、適合率が下がり検索ノイズが含まれる可能性が高くなります。この度合いを調整するためには \fB/commands/select\fP のmatch_columnsで使用する索引毎に重み付けを指定します。 .sp ここでも、前述の例を使って具体例を示します。まず、TokenBigramを用いた索引を追加します。: .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 .sp この状態でも以前はマッチしなかったレコードがヒットするようになります。: .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 .sp しかし、N\-gram系のトークナイザーの方がTokenMecabトークナイザーよりも語のヒット数が多いため、N\-gram系のヒットスコアの方が重く扱われてしまいます。N\-gram系のトークナイザーの方がTokenMecabトークナイザーよりも適合率の低い場合が多いので、このままでは検索ノイズが上位に表示される可能性が高くなります。 .sp そこで、TokenMecabトークナイザーを使って作った索引の方をTokenBigramトークナイザーを使って作った索引よりも重視するように重み付けを指定します。これは、match_columnsオプションで指定できます。: .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 .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件以下のヒット数であれば、たとえ完全一致検索でヒットしても、非わかち書き検索・部分一致検索を行います。: .sp .nf .ft C % ./configure \-\-with\-match\-escalation\-threashold=100 .ft P .fi .sp この場合も対策方法1同様、検索ノイズが上位に現れる可能性が高くなることに注意してください。検索ノイズが多くなった場合は指定する値を低くする必要があります。 .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 Use: If you are interested in groonga, please read this document and try it. .TP .B Introduction: Please introduce groonga to your friends and colleagues. .TP .B Bug report, development and documentation: This section describes the details. .UNINDENT .SS How to report a bug .sp We have two issue tracking systems, \fI\%Redmine\fP and \fI\%GitHub issue tracker\fP. Redmine is for Japanese and GitHub issue tracker is for English. You can use both of them to report a bug. .SS groonga開発者向け情報 .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 ドキュメント作成 .SS Sphinxのインストール .sp groongaのドキュメントは、Sphinxというツールを用いて作成されています。Sphinxは以下のように導入します。: .sp .nf .ft C # aptitude install python\-setuptools # easy_install \-U sphinx .ft P .fi .SS htmlの作成 .sp 以下のコマンドでhtmlが作成されます。: .sp .nf .ft C % make html .ft P .fi .SS pdfの作成 .sp groongaのドキュメントは、pdf出力することもできます。rst2pdfと、IPAフォント(IPA Gothic/IPAexGothic)が必要となります。 .SS rst2pdfのインストール .sp 以下のようにしてインストールできます。: .sp .nf .ft C # easy_install rst2pdf .ft P .fi .SS pdfの作成 .sp 以下のコマンドでpdfが作成されます。: .sp .nf .ft C % make pdf .ft P .fi .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種類があります。 .sp .nf .ft C && (論理積) || (論理和) ! (否定) .ft P .fi .sp 関係式は、下記の11種類が用意されています。また、ユーザが定義した関数を新たな関係式として使うこともできます。 .sp .nf .ft C equal(==) not_equal(!=) less(<) greater(>) less_equal(<=) greater_equal(>=) contain() near() similar() prefix() suffix() .ft P .fi .SS grn_table_select() .sp grn_table_select()関数は、grn_exprで表現された検索クエリを実行するときに使います。引数として、検索対象となるテーブル、クエリを表すgrn_expr、検索結果を格納するテーブル、それに検索にマッチしたレコードを検索結果にどのように反映するかを指定する演算子を渡します。演算子と指定できるのは下記の4種類です。 .sp .nf .ft C GRN_OP_OR GRN_OP_AND GRN_OP_BUT GRN_OP_ADJUST .ft P .fi .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として下記のいずれかを指定することができます。 .sp .nf .ft C EXACT: v2の値もv1の値と同様に要素に分解したとき、それぞれの要素が完全に一致する(デフォルト) UNSPLIT: v2の値は要素に分解しない PREFIX: v1の値の要素がv2の値に前方一致する SUFFIX: v1の値の要素がv2の値に後方一致する PARTIAL: v1の値の要素がv2の値に中間一致する .ft P .fi .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 .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 .sp tableのcolumnの値がstringを含むレコードをresultに返します。columnの値が\(aqneedle in haystack\(aqであるレコードr1と、columnの値が\(aqhaystack\(aqであるレコードr2がtableに登録されていたとき、stringに\(aqneedle\(aqを指定したなら、レコードr1のみがヒットします。 .SS 検索例2 .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 .sp tableのcolumn1の値がstringにexactモードでヒットするレコードについて得られるスコア値にscore1を積算してresultにセットします。次に、resultにセットされたレコードのうち、column2の値がstringにexactモードでヒットするレコードについては、得られたスコア値にscore2を積算したものを、元のスコア値に加えます。 .SS 検索例3 .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 .sp tableのcolumn1の値がstringにexactモードでヒットするレコードについて得られるスコア値にscore1を積算してresultにセットします。得られた検索結果数がt1よりも小さい場合は、partialモードで再度検索し、ヒットしたレコードについて得られるスコア値にscore2を積算してresultに追加します。 .SS 検索例4 .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 .sp tableのcolumnの値がstringに含まれるレコードをresultに返します。 columnの値が\(aqneedle\(aqであるレコードr1と、columnの値が\(aqhaystack\(aqであるレコードr2がtableに登録されていたとき、stringに\(aqhay in haystack\(aqを指定したなら、レコードr2のみがヒットします。 .SS テスト方法 .SS テスト環境の構築 .SS Cutterのインストール .sp groongaは、テストのフレームワークとして \fI\%Cutter\fP を用いています。 .sp Cutterのインストール方法は \fI\%プラットフォーム毎のCutterのインストール方法\fP をご覧下さい。 .SS lcovのインストール .sp カバレッジ情報を計測するためには、lcov 1.6以上が必要です。DebianやUbuntuでは以下のようにしてインストールできます。: .sp .nf .ft C % sudo aptitude install \-y lcov .ft P .fi .SS clangのインストール .sp ソースコードの静的解析を行うためには、clang(scan\-build)をインストールする必要があります。DebianやUbuntuでは以下のようにしてインストールできます。: .sp .nf .ft C % sudo aptitude install \-y clang .ft P .fi .SS libmemcachedのインストール .sp memcachedのバイナリプロトコルのテストを動作させるためには、libmemcachedの導入が必要です。squeeze以降のDebianやKarmic以降のUubntuでは以下の用にしてインストールできます。: .sp .nf .ft C % sudo aptitude install \-y libmemcached\-dev .ft P .fi .SS テストの動作 .sp groongaのトップディレクトリで、以下のコマンドを実行します。: .sp .nf .ft C make check .ft P .fi .SS カバレッジ情報 .sp groongaのトップディレクトリで、以下のコマンドを実行します。: .sp .nf .ft C make coverage .ft P .fi .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 実行例: .sp .nf .ft C % ./run\-test.sh \-n test_text_otoj .ft P .fi .SS 特定のテストファイルのみテストする .sp 特定のテストファイル(Cutterではテストケースと呼ぶ)のみテストすることができます。 .sp 実行例: .sp .nf .ft C % ./run\-test.sh \-t test_string .ft P .fi .SS 不正メモリアクセス・メモリリーク検出 .sp 環境変数CUTTER_CHECK_LEAKをyesと設定すると、valgrindを用いて不正メモリアクセスやメモリリークを検出しつつ、テストを動作させることができます。 .sp run\-test.shのみならず、make checkでも利用可能です。 .sp 実行例: .sp .nf .ft C % CUTTER_CHECK_LEAK=yes make check .ft P .fi .SS デバッガ上でのテスト実行 .sp 環境変数CUTTER_DEBUGをyesと設定すると、テストが実行できる環境が整ったgdbが実行されます。gdb上でrunを行うと、テストの実行が開始されます。 .sp run\-test.shのみならず、make checkでも利用可能です。 .sp 実行例: .sp .nf .ft C % CUTTER_DEBUG=yes make check .ft P .fi .SS 静的解析 .sp scan\-buildを用いて、ソースコードの静的解析を行うことができます。scan_buildというディレクトリに解析結果のhtmlが出力されます。: .sp .nf .ft C % scan\-build ./configure \-\-prefix=/usr % make clean % scan\-build \-o ./scan_build make \-j4 .ft P .fi .sp configureは１度のみ実行する必要があります。 .SS How to contribute in documentation topics .sp We use \fI\%Sphinx\fP for documentation tool. .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 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. .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 .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: .sp .nf .ft C % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git .ft P .fi .sp Then you need to configure your cloned repository: .sp .nf .ft C % cd groonga % ./autogen.sh % ./configure .ft P .fi .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.): .sp .nf .ft C % cd doc/locale/ja/LC_MESSAGES % make update .ft P .fi .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.): .sp .nf .ft C % cd doc/locale/ja/ % make html .ft P .fi .sp You can also generate HTML files for all languages by running \fImake html\fP on doc/locale: .sp .nf .ft C % cd doc/locale % make html .ft P .fi .IP Note .mo files are updated automatically by \fImake html\fP. So you don\(aqt care about .mo files. .RE .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: .sp .nf .ft C % firefox doc/locale/ja/html/index.html .ft P .fi .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: .sp .nf .ft C % git add doc/locale/ja/LC_MESSAGES/*.po % git commit % git push .ft P .fi .sp Now you can send pull request on GitHub. You just access your repository page on GitHub and press \fIPull Request\fP button. .IP "See also" .sp \fI\%Help.GitHub - Sending pull requests\fP. .RE .SS How to send patch .sp Here are command lines to create patch: .sp .nf .ft C % git add doc/locale/ja/LC_MESSAGES/*.po % git commit % git format\-patch origin/master .ft P .fi .sp You can find 000X\-YYY.patch files in the current directory. Please send those files to us! .IP "See also" .sp \fB/community\fP describes our contact information. .RE .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. .IP "See also" .sp \fB/community\fP describes our contact information. .RE .SS How to add new language .sp Here are command lines to add new translation language: .sp .nf .ft C % cd doc/locale % make add LOCALE=${LANGUAGE} # specify your language code such as \(aqde\(aq. .ft P .fi .sp Please substitute \fI${LANGUAGE}\fP with your language code such as \(aqja\(aq. .IP "See also" .sp \fI\%Codes for the Representation of Names of Languages\fP. .RE .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-2012, Brazil, Inc .\" Generated by docutils manpage writer. .\" .