Difference between revisions of "Small Kyoto Cabinet and Kyoto Tycoon Notes"

From PaskvilWiki
Jump to: navigation, search
(→‎RPC API Interface)
 
(2 intermediate revisions by one user not shown)
Line 20: Line 20:
 
make install
 
make install
 
</pre>
 
</pre>
 +
 +
== RPC API Interface ==
 +
 +
Kyoto Tycoon's RPC API is a lovely example of simplicity - input parameters are consistent with regards to naming, output is '''always''' the same - be it success or error. As usual, this comes at a slightly higher data volume transferred in few cases (the "order" value in ''match_xyz'' calls), but this overhead is minimal and well worth the lowered complexity.
 +
 +
Data are always returned in TSV (tab-separated-values) format, one record per line, two columns per record, where first column is key and second column value. Input and output parameters that are not part of the KT language are always preceded by underscore (_). Parsing the output is then trivial for all calls.
 +
 +
Further on:
 +
<pre>- short description
 +
> input parameter, required
 +
> + input parameter, optional
 +
< output parameter
 +
< + output parameter, might be omitted if not set</pre>
 +
 +
All calls accept optional <tt>DB</tt> parameter (int) that identifies DB to use.
 +
 +
<pre> get
 +
=====
 +
- retrieve value of a record
 +
> key
 +
< value
 +
< + xt - absolute expiration time
 +
 +
http://localhost:1978/rpc/get?key=japan
 +
---
 +
value tokyo
 +
---
 +
 +
get_bulk
 +
==========
 +
- retrieve multiple records at once
 +
> + atomic - if present, attempt to store the records atomically
 +
> + [input] - arbitrary keys which trail the character '_'
 +
< num - number of retrieved records
 +
< + [output] - data with keys trailing the character '_'
 +
 +
http://localhost:1978/rpc/get_bulk?_japan
 +
---
 +
_japan tokyo
 +
num 1
 +
---
 +
 +
check
 +
=======
 +
- checks whether record exists in DB
 +
> key
 +
< + vsiz - size of the record's value
 +
< + xt
 +
 +
http://localhost:1978/rpc/check?key=japan
 +
---
 +
vsiz 5
 +
---
 +
 +
match_prefix
 +
==============
 +
- get keys matching prefix string
 +
> prefix
 +
> + max - maximum number of records to retrieve
 +
< num - number of retrieved keys
 +
< + [output] - set of keys training the character '_'; value specifies order of the key
 +
 +
http://localhost:1978/rpc/match_prefix?prefix
 +
---
 +
_japan 0
 +
num 1
 +
---
 +
 +
match_regex
 +
=============
 +
- get keys matching regular expression
 +
> regex
 +
> + max
 +
< num
 +
< + [output] - set of keys training the character '_'; value specifies order of the key
 +
 +
match_similar
 +
===============
 +
- get keys similar to a string in terms of the levenshtein distance
 +
> origin - origin string
 +
> + range - maximum distance, default is 1
 +
> + utf - treat keys as utf-8? default 'false'
 +
> + max
 +
< num
 +
< + [output] - set of keys training the character '_'; value specifies order of the key
 +
 +
set
 +
=====
 +
- set value of record
 +
> key
 +
> value
 +
> + xt - expiration time as offset in seconds; if negative, the absolute value is epoch time
 +
 +
set_bulk
 +
==========
 +
- store multiple records at once
 +
> + xt
 +
> + atomic - if present, attempt to store the records atomically
 +
> + [input] - arbitrary records whose keys trail the character '_'
 +
< num - number of stored records
 +
 +
add
 +
=====
 +
- add a record only if it does not exist
 +
> key
 +
> value
 +
> + xt
 +
 +
replace
 +
=========
 +
- replace value of a record
 +
> key
 +
> value
 +
> + xt
 +
 +
append
 +
========
 +
- append value to a record
 +
> key
 +
> value
 +
> + xt
 +
 +
increment
 +
===========
 +
- add int value to a record (treated as int)
 +
> key
 +
> num - the number to add
 +
> + orig - origin number, 0 if omitted, 'try' for INT64MIN, 'set' for INT64MAX
 +
> + xt
 +
< num - resulting value
 +
 +
increment_double
 +
==================
 +
- add double value to a record (treated as double)
 +
> key
 +
> num
 +
> + orig - origin number, 0 if omitted, 'try' for negative infinity, 'set' for positive infinity
 +
> + xt
 +
 +
cas
 +
=====
 +
- compare and swap (i.e. set the value of record to new value only if it still has the old value)
 +
> key
 +
> + oval - old value; if omitted, no record is meant
 +
> + nval - new value; if omitted, the record is removed
 +
> + xt
 +
 +
seize
 +
=======
 +
- retrieve value of a record and remove it atomically
 +
> key
 +
< + value
 +
< + xt
 +
 +
remove
 +
========
 +
- remove a record
 +
> key
 +
 +
remove_bulk
 +
=============
 +
- remove multiple records at once
 +
> + atomic - if present, attempt to store the records atomically
 +
> + [input] - arbitrary records whose keys trail the character '_'
 +
< num - number of removed records
 +
 +
clear
 +
==========
 +
- remove all records in DB

Latest revision as of 09:40, 18 January 2013

Kyoto Cabinet

Kyoto Cabinet at FAL Labs 

./configure --prefix=/home/user
make -j4
make check
make install

Kyoto Tycoon

Kyoto Tycoon at FAL Labs 

./configure --prefix=/home/user --with-kc=/home/user --enable-static
make -j4
make check
make install

RPC API Interface

Kyoto Tycoon's RPC API is a lovely example of simplicity - input parameters are consistent with regards to naming, output is always the same - be it success or error. As usual, this comes at a slightly higher data volume transferred in few cases (the "order" value in match_xyz calls), but this overhead is minimal and well worth the lowered complexity.

Data are always returned in TSV (tab-separated-values) format, one record per line, two columns per record, where first column is key and second column value. Input and output parameters that are not part of the KT language are always preceded by underscore (_). Parsing the output is then trivial for all calls.

Further on: 

- short description
> input parameter, required
> + input parameter, optional
< output parameter
< + output parameter, might be omitted if not set

All calls accept optional DB parameter (int) that identifies DB to use. 

 get
=====
- retrieve value of a record
> key
< value
< + xt - absolute expiration time

http://localhost:1978/rpc/get?key=japan
---
value	tokyo
---

 get_bulk
==========
- retrieve multiple records at once
> + atomic - if present, attempt to store the records atomically
> + [input] - arbitrary keys which trail the character '_'
< num - number of retrieved records
< + [output] - data with keys trailing the character '_'

http://localhost:1978/rpc/get_bulk?_japan
---
_japan	tokyo
num	1
---

 check
=======
- checks whether record exists in DB
> key
< + vsiz - size of the record's value
< + xt

http://localhost:1978/rpc/check?key=japan
---
vsiz	5
---

 match_prefix
==============
- get keys matching prefix string
> prefix
> + max - maximum number of records to retrieve
< num - number of retrieved keys
< + [output] - set of keys training the character '_'; value specifies order of the key

http://localhost:1978/rpc/match_prefix?prefix
---
_japan	0
num	1
---

 match_regex
=============
- get keys matching regular expression
> regex
> + max
< num
< + [output] - set of keys training the character '_'; value specifies order of the key

 match_similar
===============
- get keys similar to a string in terms of the levenshtein distance
> origin - origin string
> + range - maximum distance, default is 1
> + utf - treat keys as utf-8? default 'false'
> + max
< num
< + [output] - set of keys training the character '_'; value specifies order of the key

 set
=====
- set value of record
> key
> value
> + xt - expiration time as offset in seconds; if negative, the absolute value is epoch time

 set_bulk
==========
- store multiple records at once
> + xt
> + atomic - if present, attempt to store the records atomically
> + [input] - arbitrary records whose keys trail the character '_'
< num - number of stored records

 add
=====
- add a record only if it does not exist
> key
> value
> + xt

 replace
=========
- replace value of a record
> key
> value
> + xt

 append
========
- append value to a record
> key
> value
> + xt

 increment
===========
- add int value to a record (treated as int)
> key
> num - the number to add
> + orig - origin number, 0 if omitted, 'try' for INT64MIN, 'set' for INT64MAX
> + xt
< num - resulting value

 increment_double
==================
- add double value to a record (treated as double)
> key
> num
> + orig - origin number, 0 if omitted, 'try' for negative infinity, 'set' for positive infinity
> + xt

 cas
=====
- compare and swap (i.e. set the value of record to new value only if it still has the old value)
> key
> + oval - old value; if omitted, no record is meant
> + nval - new value; if omitted, the record is removed
> + xt

 seize
=======
- retrieve value of a record and remove it atomically
> key
< + value
< + xt

 remove
========
- remove a record
> key

 remove_bulk
=============
- remove multiple records at once
> + atomic - if present, attempt to store the records atomically
> + [input] - arbitrary records whose keys trail the character '_'
< num - number of removed records

 clear
==========
- remove all records in DB
Retrieved from "https://wiki.paskvil.com/index.php?title=Small_Kyoto_Cabinet_and_Kyoto_Tycoon_Notes&oldid=156"