none
There are many differences between groonga
and groonga-httpd
. Here is a comparison table.
groonga | groonga-httpd | |
---|---|---|
|
o | o |
|
o (by multi threading) | o (by multi process) |
|
optional | required |
|
x | o |
|
o | x (comming soon) |
|
x | o |
|
x | o |
|
x | o |
|
x | o |
|
x | o |
|
x | o |
Upgrading without downtime | x | o |
Both groonga
and groonga-httpd
are very fast. They can work with the same throughput.
Groonga scales on multi CPU cores. groonga
scales by multi threading. groonga-httpd
scales by multi processes.
groonga
uses the same number of threads as CPU cores by default. If you have 8 CPU cores, 8 threads are used by default.
groonga-httpd
uses 1 process by default. You need to set worker_processes directive to use CPU cores. If you have 8 CPU cores, specify worker_processes 8
in configuration file like the following:
worker_processes 8;
http {
# ...
}
groonga
can work without configuration file. All configuration items such as port number and the max number of threads can be specified by command line. Configuration file is also used to specify configuration items.
It's very easy to run groonga HTTP server because groonga
requires just a few options to run. Here is the most simple command line to start HTTP server by groonga
:
% groonga --protocol http -d /PATH/TO/DATABASE
groonga-httpd
requires configuration file to run. Here is the most simple configuration file to start HTTP server by groonga-httpd
:
events {
}
http {
server {
listen 10041;
location /d/ {
groonga on;
groonga_database /PATH/TO/DATABASE;
}
}
}
groonga
accepts a path that starts with /d/
as command URL such as http://localhost:10041/d/status
. You cannot change the prefix path /d/
.
groonga-httpd
can custom prefix path. For example, you can use http://localhost:10041/api/status
as command URL. Here is a sample configuration to use /api/
as prefix path:
events {
}
http {
server {
listen 10041;
location /api/ { # <- change this
groonga on;
groonga_database /PATH/TO/DATABASE;
}
}
}
Groonga has /reference/command/command_version
mechanism. It is for upgrading groonga commands with backward compatibility.
groonga
can change the default command veresion by --default-command-version
option. Here is a sample command line to use command version 2 as the default command version:
% groonga --protocol http --default-command-version 2 -d /PATH/TO/DATABASE
groonga-httpd
cannot custom the default command version yet. But it will be supported soon. If it is supported, you can provides different command version groonga commands in the same groonga-httpd
process. Here is a sample configuration to provide command version 1 commands under /api/1/
and command version 2 comamnds under /api/2/
:
events {
}
http {
server {
listen 10041;
groonga_database /PATH/TO/DATABASE;
location /api/1/ {
groonga on;
groogna_default_command_version 1;
}
location /api/2/ {
groonga on;
groogna_default_command_version 2;
}
}
}
groonga
can use only one database in a process.
groonga-httpd
can use one or more databases in a process. Here is a sample configuration to provide /tmp/db1
database under /db1/
path and /tmp/db2
database under /db2/
path:
events {
}
http {
server {
listen 10041;
location /db1/ {
groonga on;
groonga_database /tmp/db1;
}
location /db2/ {
groonga on;
groonga_database /tmp/db2;
}
}
}
HTTP supports authentications such as basic authentication and digest authentication. It can be used for restricting use of danger command such as /reference/commands/shutdown
.
groonga
doesn't support any authentications. To restrict use of danger command, other tools such as iptables and reverse proxy are needed.
groonga-httpd
supports basic authentication. Here is a sample configuration to restrict use of /reference/commands/shutdown
command:
events {
}
http {
server {
listen 10041;
groonga_database /PATH/TO/DATABASE;
location /d/shutdown {
groonga on;
auth_basic "manager is required!";
auth_basic_user_file "/etc/managers.htpasswd";
}
location /d/ {
groonga on;
}
}
}
HTTP supports response compression by gzip with Content-Encoding: gzip
response header. It can reduce network flow. It is useful for large search response.
groonga
doesn't support compression. To support compression, reverse proxy is needed.
groonga-httpd
supports gzip compression. Here is a sample configuration to compress response by gzip:
events {
}
http {
server {
listen 10041;
groonga_database /PATH/TO/DATABASE;
location /d/ {
groonga on;
gzip on;
gzip_types *;
}
}
}
Note that gzip_types * is specified. It's one of the important configuration. gzip_types specifies gzip target data formats by MIME types. groonga-httpd
returns one of JSON, XML or MessagePack format data. But those formats aren't included in the default value of gzip_types. The default value of gzip_types is text/html.
To compress response data from groonga-httpd
by gzip, you need to specify gzip_types * or gzip_types application/json text/xml application/x-msgpack explicitly. gzip_types * is recommended. There are two reasons for it. The first, groonga may support more formats in the future. The second, all requests for the location are processed by groonga. You don't need to consider about other modules.
You can load your data by POST JSON data. You need follow the following rules to use loading by POST.
- Content-Type header value must be application/json.
- JSON data is sent as body.
- Table name is specified by query parameter such as
table=NAME
.
Here is an example curl command line that loads two users alice and bob to Users table:
% curl --data-binary '[{"_key": "alice"}, {"_key": "bob"}]' -H "Content-Type: application/json" "http://localhost:10041/d/load?table=Users"
TODO
TODO
TODO