poyonga

Python Groonga Client. poyonga support to HTTP and GQTP protocol.

Requrements

• Python 3.8+

Installation

from pip:

pip install --upgrade poyonga

Usage

Setup Groonga Server

$ groonga -n grn.db     # create groonga database file
$ groonga -s grn.db     # start groonga server with GQTP

Basic Usage

>>> from poyonga import Groonga
>>> g = Groonga()
>>> g.protocol
'http'
>>> ret = g.call("status")
>>> ret
<poyonga.result.GroongaResult object at 0x8505ccc>
>>> ret.status
0
>>> ret.body
{u'uptime': 427, u'max_command_version': 2, u'n_queries': 3,
u'cache_hit_rate': 66.6666666666667, u'version': u'1.2.8', u
'alloc_count': 156, u'command_version': 1, u'starttime': 132
8286909, u'default_command_version': 1}
>>>

with eventlet

from poyonga import Groonga
import eventlet

eventlet.monkey_patch()

def fetch(cmd, **kwargs):
    g = Groonga()
    ret = g.call(cmd, **kwargs)
    print ret.status
    print ret.body
    print "*" * 40

cmds = [("status", {}),
        ("log_level", {"level": "warning"}),
        ("table_list", {})
        ("select", {"table": "Site"})]
pool = eventlet.GreenPool()
for cmd, kwargs in cmds:
    pool.spawn_n(fetch, cmd, **kwargs)
pool.waitall()

Custom prefix path

If you use the Custom prefix path and Multi databases , specify prefix_path .

# default is '/d/'
g = Groonga(prefix_path='/db2/')

with Apache Arrow

Groonga supports Apache Arrow, use it with load and select commands.

use poyonga with Apache Arrow, you need pyarrow .

requrie pyarrow:

$ pip install pyarrow

and call with output_type="apache-arrow" option:

from poyonga import Groonga

g = Groonga()
g.call(
    "select",
    table="Users",
    match_columns="name,location_str,description",
    query="東京",
    output_type="apache-arrow",
    output_columns="_key,name",
)

Note

output_type can also specify poyonga.const.OutputType.APACHE_ARROW. If is not specified, poyonga.const.OutputType.JSON is specified by default.

load with input_type="apache-arrow":

import pyarrow as pa
from poyonga import Groonga

# use Apache Arrow IPC Streaming Format
data = [pa.array(["groonga.org"])]
batch = pa.record_batch(data, names=["_key"])
sink = pa.BufferOutputStream()
with pa.ipc.new_stream(sink, batch.schema) as writer:
    writer.write_batch(batch)
buf = sink.getvalue()
values = buf.to_pybytes()

g = Groonga()
g.call("load", table="Site", values=values, input_type="apache-arrow")

Note

input_type can also specify poyonga.const.InputType.APACHE_ARROW. If is not specified, poyonga.const.InputType.JSON is specified by default.

more information:

• https://groonga.org/docs/reference/commands/load.html

example code

see examples directory

for Developer

install dev dependencies:

$ uv sync --dev

run tests:

$ uv run pytest test

run linter:

$ uv run ruff check .

run formatter:

$ uv run ruff format --check --diff .

run tests with tox and uv(python)

set-up:

$ uv python install py310 py311 py312 py313 py314 pypy3.10 pypy3.11
$ uv tool install tox --with tox-uv

run:

$ tox

Links

• PyPI
• GitHub