Hibari DB¶

Why NOSQL?¶

The NOSQL “movement” is, first off, not an outright rejection of traditional relational database management systems (RDBMS) but rather a growing recognition that today’s data environment requires a diverse storage toolset that is “Not Only SQL (NOSQL)”. Relational and NOSQL data storage solutions should be viewed as complements, with each approach better suited toward different types of applications and services.

The main driver of NOSQL has been the proliferation of applications and services that must store and serve terabytes or petabytes of data, often while striving to guarantee “always-on” availability and low latencies for end users. Organizations in many market sectors are grappling with the advent of Big Data, including but not limited to:

• Web properties – coping with the massive data requirements of search, e-commerce, social media, and user-generated content.
• Telecoms – managing and analyzing network logs and call data records for multi-millions of subscribers.
• Utilities – managing and analyzing the enormous data volume associated with smart grids.
• Financial services – storing and mining customer history data in order to analyze and model risk.
• Retail analytics – click-stream analysis and micro-targeting.
• Biotech – genome analysis.

Organizations in these and other data-intensive environments have been challenged to build data storage systems of unprecedented scale. Many such organizations have found their needs ill-met by traditional data storage approaches that center around relational database management systems and specialized high-end hardware. In particular:

• Scaling up a single RDBMS instance doesn’t achieve nearly the scale required, no matter how high-end the systems or how great the expenditure.
• Scaling out by sharding the system over multiple RDBMS instances entails enormous costs and enormous operational complexity, while at the same time forfeiting much of the power of the relational model.

Wanting Big Data capacity without crippling cost and complexity, some innovative organizations have sought a better way to scale. At the same time, with an ever-expanding array of data usage scenarios, it’s become apparent that not all scenarios require the complex querying and management functionality associated with an RDBMS. For some applications and services, SQL-structuring and strict ACID properties are overkill. Worse, in some environments they’re expensive overkill that can potentially hamstring service offerings in highly competitive markets that demand flexibility and responsiveness.

In short, recent years have seen a proliferation of services that require more data, with less structure.

Not surprisingly, some of the leading web enterprises have been at the forefront of the NOSQL movement. In particular, Google with its http://labs.google.com/papers/bigtable.html[BigTable paper] in 2006 and Amazon with its http://s3.amazonaws.com/AllThingsDistributed/sosp/amazon-dynamo-sosp2007.pdf[Dynamopaper] in 2007 had a profound effect on the NOSQL market. A number of NOSQL solutions have drawn inspiration from either BigTable or Dynamo or both, and in the past couple years several solutions have been released into the open source community.

While NOSQL data storage solutions vary in their particulars, they have these basic traits in common:

• A simplified data model. Data models vary across specific solutions, and sometimes form the basis of a tripartite classification of NOSQL systems into 1) key-value data stores (such as Dynamo and Hibari); 2) column-oriented data stores (such as BigTable); and 3) document-oriented data stores (such as CouchDB). All variants, however, are simpler and more flexible in data model than the traditional RDBMS. That simplification tends to carry over to client APIs as well.
• Distribution across multiple nodes based on commodity PCs. Affordable Big Data capacity is achieved by scaling out across tens, hundreds, or even thousands of commodity PCs. Data partitioning schemes coupled with parallel processing of incoming requests deliver the needed high performance.
• Replication of data objects across multiple nodes, to ensure high availability in the event of component failures.

For much more on the history, merits, and design issues associated with NOSQL storage solutions, consult with your favorite search engine.

Engineered in Erlang¶

Erlang is a general purpose programming language and runtime environment designed specifically to support reliable, high-performance distributed systems. Originally developed by Ericsson in the 1980s for building advanced telecom networking systems, Erlang/OTP (Open Telecom Platform) was open-sourced in 1998. Hibari is written entirely in Erlang.

Erlang provides a range of benefits that make it the ideal foundation for a distributed key-value storage solution:

• Concurrency. Erlang has extremely lightweight processes that communicate by message passing and have no shared memory. Scheduling, memory management, and other concurrency-related services are managed by the Erlang VM, placing no requirements for concurrency on the host operating system.
• Distribution. Erlang is designed specifically for distributed environments. Passing messages transparently via TCP, Erlang processes on different nodes communicate with each other in exactly the same way as do processes on the same node. The simple and efficient design facilitates massive parallelism and scalability of the sort required by a high-performance distributed storage system. With its prowess for concurrency and distributed processing, it has been suggested that Erlang can be regarded as a first-of-its-kind http://www.oreillygmt.eu/open-sourcefree-software/erlang-the-ceos-view/[“application system”], analogous to an operating system except running across and coordinating multiple hosts.
• Robustness. Erlang processes are completely independent of each other, with no data sharing. While functionally isolated, Erlang processes are able to monitor each other and to detect and respond to crashed processes, even on remote nodes.
• Portability. The same Erlang VM can run on Linux, Unix, Windows, Macintosh, or VxWorks. Distributed Erlang processes can seamlessly communicate with each other regardless of the heterogeneity of their host operating systems. This OS portability is a valuable facilitator of storage system elasticity, as system managers may need to mix and match hosts in response to fluid demand environments.
• Hot code upgrades. Erlang-based applications like Hibari support hot code upgrades: upgrades can be applied without shutting down the system. During the change-over, old and new code can run simultaneously. This is a key benefit for environments that require “always-on” availability for end users.

Other features reinforce Erlang’s suitability for reliable distributed applications, including incremental garbage collection, single-assignment variables, and robust exception handling.

[[chain-replication]]

Chain Replication for High Availability and Strong Consistency¶

The Hibari distributed key-value store implements a version of the chain replication methodology first proposed by http://www.usenix.org/event/osdi04/tech/full_papers/renesse/renesse.pdf[van Renesse and Schneider] to achieve redundancy and high availability without sacrificing data consistency. At a high level, chain replication in a Hibari storage cluster works as follows:

• Through consistent hashing, the key space is divided across multiple storage “chains”.
• Each chain is composed of multiple logical storage “bricks”, with each brick running in its own Erlang VM instance.
• Within each chain, the member bricks have differentiated roles. Client-requested updates to key-value pairs are written first to the “head” brick, then automatically replicated downstream to one or more “middle” bricks and finally to the “tail” brick, which returns an update acknowledgement to the client. By contrast, read requests are directed to the tail brick, which returns the response to the client.

image:images/chain_replication.png[]

While most distributed storage systems are able to guarantee only weak or eventual data consistency across replicas – placing the burden on the client application (and the client application developer) to manage the potential inconsistencies – Hibari with its chain replication implementation guarantees strong consistency. Data updates are considered complete, and are acknowledged to clients, only when they have replicated through the chain to the tail; and read requests are processed only by the tail. Consequently, after an object update is acknowledged to a Hibari client, other clients are guaranteed to see only the newest version of that object. This strong consistency is valuable in environments where ‘eventual consistency’ is at odds with the service level expected by end users, or where system designers do not want to clutter client applications with the logic required to manage data inconsistency.

The “length” of a chain is configurable and can be based on your desired degree of replication and redundancy. For example, a chain of length four would have a head brick, two middle bricks, and a tail brick; while a three-brick chain would have a head, one middle, and a tail. A chain can also operate at length two (a head and tail, with no middle) and even at length one (one brick playing both the head role and the tail role).

Because chains can operate at any length, and because the system is able to detect failures within the chain and to adjust member brick roles accordingly, Hibari delivers high availability as well as strong data consistency. For example, if in a three-brick chain the head brick goes down, the middle brick automatically takes over the head brick role, allowing the chain to continue functioning normally:

image:images/automatic_failover.png[]

If the new head brick failed also, the lone remaining brick would then play both the head role and the tail role, processing all writes and reads itself as a single-brick “chain”.

While multiple logical bricks can run on a single physical node, for high availability it is of course desirable that a particular chain’s member bricks be deployed on separate machines. If you want to run multiple bricks per machine and also ensure high availability for each chain, an attractive deployment option is to “stripe” the chains across machines:

image:images/load_balanced_chains.png[]

Note also that because head bricks (receiving incoming write requests) and tail bricks (replying to write requests and processing read requests) bear more load than do middle bricks, load balancing across machines can be achieved in part by allocating the different brick roles evenly, as in the diagram above.

In the event of a physical node failure, bricks within each impacted chain automatically shift roles, and each chain continues to provide normal service to clients:

image:images/automatic_failover_2.png[]

For further information about chain replication, fail-over, and recovery in a Hibari storage system, and for information about Hibari’s redundantly structured cluster membership application called the Admin Server, see these sections of the Hibari System Administrator’s Guide:

• link:hibari-sysadmin-guide.en.html#hibari-architecture[Hibari Architecture]
• link:hibari-sysadmin-guide.en.html#life-of-brick[The Life of a (Logical) Brick]
• link:hibari-sysadmin-guide.en.html#dynamic-cluster-reconfiguration[Dynamic Cluster Reconfiguration]
• link:hibari-sysadmin-guide.en.html#admin-server-app[The Admin Server Application]

[[scalability]]

Easy, Affordable Scalability¶

Hibari provides Big Data scalability while minimizing the cost and operational complexity of cluster growth:

• Hibari scales horizontally by the addition of more chains, deployed on more physical nodes. The total storage and processing capacity of a Hibari cluster increases linearly as machines are added to the cluster.
• The system rebalances data storage distribution automatically as chains are added to (or removed from) the cluster, with no downtime. You can grow (or shrink) your Hibari storage cluster with no service interruption.
• Hibari runs on commodity PCs. Further, the system easily accommodates heterogeneous hardware resources. Bricks within the storage cluster can have different RAM and disk sizes, and different CPU speeds. You can tune Hibari’s consistent hash function to optimize your cluster’s utilization of mixed hardware. Each chain can be assigned a weighting factor that will increase or decrease that chain’s portion of the overall key space, relative to other chains.

In addition to supporting mixed hardware, Erlang-based Hibari can run on most any OS. With its easy adaptability to disparate hardware and operating systems, you can scale Hibari incrementally, with whatever resources you have available. It’s not necessary to buy all your resources at once, or all of the same kind.

For further information on resizing a Hibari cluster, see link:hibari-sysadmin-guide.en.html#dynamic-cluster-reconfiguration[Dynamic Cluster Reconfiguration] in the Hibari System Administrator’s Guide.

[[high-performance]]

High Performance, Especially for Reads and Large Values¶

Several features work in combination to drive high performance in a Hibari storage cluster, even at Big Data scale:

• The Erlang technology that underlies Hibari was specifically designed for and excels at distributed parallel processing.
• Hibari’s implementation of consistent hashing and chain replication partitions the key-space across multiple chains, enabling parallel simultaneous processing of requests incoming to individual chains. The distribution of data across chains is tunable to allow optimal utilization of heterogeneous hardware resources.
• Hibari’s chain replication implementation further aids performance by assigning storage bricks differentiated processing roles as head, middle, or tail. This division of labor particularly benefits read performance, as read requests are processed by “tail” bricks that do not bear the load of initial processing of write requests (since that work is done by “head” bricks).
• Hibari supports a number of performance-tuning options on a per-table basis. For example, while some distributed KVDBs support only disk-based storage or only RAM-based storage of value blobs, Hibari lets you choose RAM+disk-based or disk-only storage on a per-table basis, depending on your application needs. Whichever storage option you choose, all data changes are logged to disk to ensure data durability in the event of power failures. A batch commit technique is used to minimize disk I/O.

Leveraging this feature set, Hibari is able to deliver scalable high performance that is competitive with leading open source NOSQL storage systems, while also providing the data durability and strong consistency that many systems lack. Hibari’s performance relative to other NOSQL systems is particularly strong for reads and for large value (> 200KB) operations. Hibari’s consistently high performance even for large values distinguishes the system from solutions that are tailored toward small value operations.

As one example of real-world performance, in a multi-million user webmail deployment equipped with traditional HDDs (non SSDs), Hibari is processing about 2,200 transactions per second, with read latencies averaging between 1 and 20 milliseconds and write latencies averaging between 20 and 80 milliseconds.

[[simple-powerful-api]]

Simple But Powerful Client API¶

As a key-value store, Hibari’s core data model and client API model are simple by design: blob-based key-value pairs can be inserted, retrieved, and deleted from lexicographically sorted tables. While Hibari thus provides the flexibility and scalability associated with key-value stores, the system also provides distinctive features that enhance the power of client applications and developers:

• Clients can optionally assign per-object expiration times.
• Clients can optionally assign per-object custom flags. This flexible, custom meta-data can be updated with or without updating the associated value blob, and can be retrieved with or without the value blob.
• Objects are automatically timestamped each time they are updated. This timestamping mechanism facilitates “test-and-set” type operations: clients can specify that a requested operation be performed only if the target key’s timestamp matches the client’s expectations.
• Within key-prefix range limits (specifically, within individual chains but not across chains), Hibari’s client API supports atomic transactions. This support for “micro-transactions” sets Hibari apart from other open source KVDBs and can greatly simplify the creation of robust client applications.

Hibari supports multiple client API implementations including:

• Native Erlang
• Universal Binary Format (UBF)
• Thrift
• Amazon S3
• JSON-RPC

You can develop Hibari client applications in a variety of languages including Java, C/C++, Python, Ruby, and Erlang.

For further information about Hibari’s client API, see link:#client-api-erlang[Client API: Native Erlang] and the subsequent client API chapters in this guide.

[[production-proven]]

Production-Proven¶

While initial development work on Hibari was geared generally toward the data storage demands of the Tier 1 telecom sector, as the system evolved it needed to meet the requirements of a particular major Asian carrier that wished to launch a GB webmail service. This customer’s requirements for Hibari included the following:

• Several million users from the start.
• Several billion stored messages within a few months of launch.
• Hundreds of TB storage capacity.
• Elasticity to support continual growth.
• Low system costs, particularly since the service would employ the “freemium” model.
• Individual messages could range in size from a few bytes to many MB with attachments.
• Support for per-object meta-data required.
• Strong consistency required, for interactive sessions.
• Data durability required – loss of messages or meta-data unacceptable.
• High availability – an “always on”, branded service.
• Low latency, with < 1 second response times for end user transactions.

Hibari was built to meet these rigorous requirements, was hardened through extensive testing and trials, and went live in support of this large-scale webmail system at the beginning of 2010. The system now stores billions of messages on behalf of millions of end users, while meeting customer requirements for availability, latency, consistency, durability, and affordability.

Coinciding with Hibari’s development and fine tuning for this GB webmail service, the system was also deployed as a storage solution for two major Asian carriers’ mobile social networking services. In this context, Hibari stores user profile data as well as digital goods of varying types and sizes.

[[hibari-benefits-by-user]]

Hibari Benefits for Developers, System Administrators, and Businesses¶

For application developers, Hibari offers a distinctive set of benefits not often found in distributed key-value stores:

• Strong data consistency guarantees that relieve client applications of the burden of managing potential inconsistencies.
• Micro-transaction support that simplifies the creation of powerful applications.
• Per-object custom flags that facilitate flexible, service-specific application design.
• Support for a variety of API implementations and development languages.

For system administrators, Hibari provides valuable operational automations that simplify data management in a dynamic storage environment:

• Automatic data replication.
• Automatic failover when a node goes down.
• Automatic repair when a failed node comes back up.
• Automatic rebalancing of data as a cluster grows or shrinks.

For businesses as a whole, Hibari offers affordable Big Data scalability while delivering the high availability and low latencies that service users demand. Hibari is an appropriate storage solution for a range of data-intensive service scenarios including but not limited to large-scale messaging, social media, and archiving. Hibari offers particular value in environments that require strong data consistency and/or high performance across a variety of object types and sizes.

System Requirements¶

Hibari will run on any OS that the Erlang VM supports, which includes most Unix and Unix-like systems, Windows, and Mac OS X. See Implementation and Ports of Erlang from the official Erlang documentation for further information.

For guidance on hardware requirements in a production environment, see link:hibari-sysadmin-guide.en.html#brick-hardware[Notes on Brick Hardware] in the Hibari System Administrator’s Guide.

[[required-software]]

Required Third-Party Software¶

Hibari’s requirements for third party software depend on whether you’re doing a single-node installation or a multi-node installation.

Downloading Hibari¶

Hibari is not yet available as a pre-built release. In the meanwhile, you can build Hibari from source. Follow the instructions in <<HibariBuildingSource>>, and then return to this section to continue the set-up process.

When you build Hibari your output is two files that you will later use in the set-up process:

• A tarball package hibari-X.Y.Z-DIST-ARCH-WORDSIZE.tgz
• An md5sum file hibari-X.Y.Z-DIST-ARCH-WORDSIZE-md5sum.txt

X.Y.Z is the release version, DIST is the release distribution, ARCH is the release architecture, and WORDSIZE is the release wordsize.

[[installing-single-node]]

Installing a Single-Node Hibari System¶

A single-node Hibari system will not provide data replication and redundancy in the way that a multi-node Hibari cluster will. However, you may wish to deploy a simple single-node Hibari system for testing and development purposes.

1. Create a directory for running Hibari:

   $ mkdir running-directory
   

2. Untar the Hibari tarball package that you created when you built Hibari from source:

   $ tar -C running-directory -xvf hibari-X.Y.Z-DIST-ARCH-WORDSIZE.tgz
   

[[starting-single-node]]

Starting and Stopping Hibari on a Single Node¶

$ running-directory/hibari/bin/hibari stop

Installing a Multi-Node Hibari Cluster¶

Before you install Hibari on to the target nodes you must complete these preparation steps:

• Set up required user privileges on the installer node and on the target Hibari nodes.
• Download the Cluster installer tool.
• Configure the Cluster installer tool.

$ visudo
Defaults    requiretty

$ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev1
$ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev2
$ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev3

ADMIN_NODES=(dev1 dev2 dev3)
BRICK_NODES=(dev1 dev2 dev3)
BRICKS_PER_CHAIN=2

ALL_NODES=(dev1 dev2 dev3)
ALL_NETA_ADDRS=("10.181.165.230" "10.181.165.231" "10.181.165.232")
ALL_NETB_ADDRS=("10.181.165.230" "10.181.165.231" "10.181.165.232")
ALL_NETA_BCAST="10.181.165.255"
ALL_NETB_BCAST="10.181.165.255"
ALL_NETA_TIEBREAKER="10.181.165.1"

ALL_HEART_UDP_PORT="63099"
ALL_HEART_XMIT_UDP_PORT="63100"

$ cd working-directory
$ ./clus/priv/clus-hibari.sh -f stop hibari hibari.config
ok
ok
ok
hibari@dev1
hibari@dev2
hibari@dev3

Creating New Tables¶

The simplest way to create a new table is via the Admin Server’s GUI. Open http://localhost:23080/ and click the “Add a table” link. In addition to the GUI, the hibari-admin tool can also be used to create a new table. See the hibari-admin tool for usage details.

When adding a table through the GUI, you have these table configuration options:

• Local
  • Boolean. If true, all bricks for storing the new table’s data will be created on the local node, i.e. the node that’s running the Admin Server. If false, then the “NodeList” field is used to specify which cluster nodes the new bricks should use.
• BigData
  • Boolean. If true, value blobs will be stored on disk.
• DiskLogging
  • Boolean. If true, all updates will be written to the write-ahead log for persistence. If false, bricks will run faster but at the expense of data loss in a cluster-wide power failure.
• SyncWrites
  • Boolean. If true, all writes to the write-ahead log will be flushed to stable storage via the fsync(2) system call. If false, bricks will run faster but at the expense of data loss in a cluster-wide power failure.
• VarPrefix
  • Boolean. If true, then a variable-length prefix of the key will be used as input for the consistent hashing function. If false, the entire key will be used.

Many applications can benefit from using a variable-length or fixed-length prefix hashing scheme. As an example, consider an application that maintains state for various users. The app wishes to use micro-transactions to update various keys (in the same table) related to that user. The table can be created to use VarPrefix=true, together with VarPrefixSeparator=47 (ASCII 47 is the forward slash character) and VarPrefixNumSeparator=2, to create a hashing scheme that will guarantee that keys /FooUser/summary and /FooUser/thing1 and /FooUser/thing9 are all stored by the same chain.

• VarPrefixSeparator
  • Integer. Define the character used for variable-length key prefix calculation. Note that the default value of ASCII 47 (the “/” character), or any other character, does not imply any UNIX/POSIX style file or directory semantics.
• VarPrefixNumSeparators
  • Integer. Define the number of VarPrefixSeparator bytes, and all bytes in between, used for consistent hashing. If VarPrefixSeparator=47 and VarPrefixNumSeparators=3, then for a key such as /foo/bar/baz, the prefix used for consistent hashing will be /foo/bar/.
• Bricks
  • Integer. If Local=true (see above), then this integer defines the total number of logical bricks that will be created on the local node. This value is ignored if Local=false.
• BPC
  • Integer. Define the number of bricks per chain.

The algorithm used for creating chain -> brick mapping is based on a “striping” principle: enough chains are laid across bricks in a stripe-wise manner so that all nodes (aka physical bricks) will have the same number of logical bricks in head, middle, and tail roles. See the example in the Hibari System Administrator’s Guide of link:hibari-sysadmin-guide.en.html#3-chains-striped-across-3-bricks[3 chains striped across three nodes].

The Erlang API must be used to create tables with other chain layout patterns.

• NodeList
  • Comma-separated string. If Local=false, specify the list of nodes that will run logical bricks for the new table. Each node in the comma-separated list should take the form NodeName@HostName. For example, use hibari1@machine-a, hibari1@machine-b, hibari1@machine-c to specify three nodes.
• NumNodesPerBlock
  • Integer. If Local=false, then this integer will affect the striping behavior of the default chain striping algorithm. This value must be zero (i.e. this parameter is ignored) or a multiple of the BPC parameter.

For example, if NodeList contains nodes A, B, C, D, E, and F, then the following striping patterns would be used:

• NumNodesPerBlock=0 would stripe across all 6 nodes for 6 chains total.
• NumNodesPerBlock=2 and BPC=2 would stripe 2 chains across nodes A & B, 2 chains across C & D, and 2 chains across E & F.
• NumNodesPerBlock=3 and BPC=3 would stripe 3 chains across nodes A & B & C and 3 chains across D & E & F.
• BlockMultFactor
  • Integer. If Local=false, then this integer will affect the striping behavior of the default chain striping algorithm. This value must be zero (i.e. this parameter is ignored) or greater than zero.

For example, if NodeList contains nodes A, B, C, D, E, and F, then the following striping patterns would be used:

• NumNodesPerBlock=0 and BlockMultFactor=0 would stripe across all 6 nodes for 6 chains total.
• NumNodesPerBlock=2 and BlockMultFactor=5 and BPC=2 would stripe 2*5=10 chains across nodes A & B, 2*5=10 chains across C & D, and 2*5=10 chains across E & F, for a total of 30 chains.
• NumNodesPerBlock=3 and BlockMultFactor=4 and BPC=3 would stripe 3*4=12 chains across nodes A & B & C and 3*4=12 chains across D & E & F, for a total of 24 chains.

Supported Operations¶

Hibari’s client API supports the operations listed below.

> brick_simple:add(tab1, <<"foo">>, <<"Hello, world!">>).
{ok,1271542959131192}

> brick_simple:add(tab1, <<"foo">>, <<"Goodbye, world!">>).
{key_exists,1271542959131192}

> brick_simple:rename(tab1, <<"my/foo">>, <<"my/bar">>).
{ok,1271543165272987}

> brick_simple:rename(tab1, <<"my/foo">>, <<"her/foo">>).
...

Check and Swap (CAS)¶

If desired, clients can apply a “check and swap” (or “test and set”) logic to data insertion, retrieval, and deletion operations so that the operation will be executed only if the target key has the exact timestamp specified in the request.

Micro-Transaction¶

TODO

Data Insertion¶

• Add a key-value pair that does not yet exist, along with optional flags:

  • link:#brick-simple-add[brick_simple:add/6]

• Assign a new value and/or new flags to a key that already exists:

  • link:#brick-simple-replace[brick_simple:replace/6]

• Rename a key that already exists:

  • link:#brick-simple-rename[brick_simple:rename/6]

• Set a key-value pair and optional flags regardless of whether the key yet exists:

  • link:#brick-simple-set[brick_simple:set/6]

Data Retrieval¶

• Retrieve a key and optionally its associated value and flags:
  • link:#brick-simple-get[brick_simple:get/4]
• Retrieve multiple lexicographically contiguous keys and optionally their associated values and flags:
  • link:#brick-simple-get-many[brick_simple:get_many/5]

Data Deletion¶

• Delete a key-value pair and associated flags:
  • link:#brick-simple-delete[brick_simple:delete/4]

Compound Operations¶

• Execute a specified list of operations, optionally as an atomic transaction (micro-transaction):
  • link:#brick-simple-do[brick_simple:do/4]

If desired, clients can apply a “test ‘n set” logic to data insertion, retrieval, and deletion operations so that the operation will be executed only if the target key has the exact timestamp specified in the request.

Fold Operations¶

• Implement a fold operation across all keys in a table:
  • link:#brick-simple-fold-table[brick_simple:fold_table/7]
• Implement a fold operation across all keys having a specified prefix:
  • link:#brick-simple-fold-key[brick_simple:fold_key_prefix/9]

brick_simple:add/6¶

Adds Key and Value pair (and optional Flags) to the table Table if the key does not already exist. The operation will fail if Key already exists.

brick_simple:add(Table, Key, Value)¶

brick_simple:add(Table, Key, Value, Flags)¶

brick_simple:add(Table, Key, Value, Timeout)

brick_simple:add(Table, Key, Value, ExpTime, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table to which to add the key-value pair -type table() :: atom() Key (key()) – Key to add to the table, in association with a paired value -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution. The same is true of Value.

Parameters:

Value (val()) – Value to associate with the key -type val() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()] ExpTime (exp_time()) – Time at which the key will expire, expressed as a Unix time_t(). Optional; defaults to 0 (no expiration). -type exp_time() :: time_t() -type time_t() :: integer() Flags (flags_list()) – List of operational flags to apply to the add operation, and/or custom property flags to associate with the key-value pair in the database. Heavy use of custom property flags is discouraged due to RAM-based storage Optional; defaults to empty list -type flags_list() :: [do_op_flag() | property()] -type do_op_flag() :: 'value_in_ram' Store the value blob in RAM, overriding the default storage location of the brick Note 'value_in_ram' flag have not been extensively tested -type property() :: atom() | {term(), term()} Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{'ok', timestamp()}

Error returns

Return type:	{'key_exists', timestamp()} The operation failed because the key already exists. -type timestamp() :: integer()
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:add(tab1, <<"foo">>, <<"Hello, world!">>).
{ok,1271542959131192}

> brick_simple:add(tab1, <<"foo">>, <<"Goodbye, world!">>).
{key_exists,1271542959131192}

> brick_simple:add(tab1, "foo1", "this is value1", ['value_in_ram']).
{ok,1271542959131192}

> brick_simple:add(tab1, "foo2", "this is value2", 20000).
{ok,1271542959131192}

brick_simple:replace/6¶

Replace Key and Value pair (and optional Flags) in the table Table if the key already exists. The operation will fail if Key does not already exist

brick_simple:replace(Table, Key, Value)¶

brick_simple:replace(Table, Key, Value, Flags)¶

brick_simple:replace(Table, Key, Value, Timeout)

brick_simple:replace(Table, Key, Value, ExpTime, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table in which to replace the key-value pair. -type table() :: atom() Key – Key to replace in the table, in association with a new paired value -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution. The same is true of Value.

Parameters:

Value (val()) – Value to associate with the key -type val() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()] ExpTime (exp_time()) – Time at which the key will expire, expressed as a Unix time_t(). Optional; defaults to 0 (no expiration). -type exp_time() :: time_t() -type time_t() :: integer() Flags (flags_list()) – List of operational flags to apply to the replace operation, and/or custom property flags to associate with the key-value pair in the database. Heavy use of custom property flags is discouraged due to RAM-based storage Optional; defaults to empty list -type flags_list() :: [do_op_flag() | property()] -type do_op_flag() :: {'testset', timestamp()} | 'value_in_ram' {'exp_time_directive', 'keep' | 'replace'} | {'attrib_directive', 'keep' | 'replace'} -type timestamp() = integer() -type property() :: atom() | {term(), term()} Operational flag usage {'testset', timestamp()} Fail the operation if the existing key’s timestamp is not exactly equal to timestamp(). If used inside a link:#brick-simple-do[micro-transaction], abort the transaction if the key’s timestamp is not exactly equal to timestamp() {'exp_time_directive', 'keep' | 'replace'} Default to 'replace' Specifies whether the ExpTime is kept from the old key value pair or replaced with the ExpTime provided in the replace operation {'attrib_directive', 'keep' | 'replace'} Default to 'replace' Specifies whether the custom properties are kept from the old key value pair or replaced with the custom properties provided in the replace operation If kept, the custom properties remain unchanged. If you specify custom properties explicitly in the replace operation, Hibari adds them to the resulting key value pair If replaced, all original custom properties are deleted, and then Hibari adds the custom properties in the replace operation to the resulting key value pair 'value_in_ram' Store the value blob in RAM, overriding the default storage location of the brick Note 'value_in_ram' flag have not been extensively tested Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{'ok', timestamp()}

Error returns

Return type:	'key_not_exists' The operation failed because the key does not exist -type timestamp() :: integer()
Return type:	{'ts_error', timestamp()} The operation failed because the {'testset', timestamp()} flag was used and there was a timestamp mismatch. The timestamp() in the return is the current value of the existing key’s timestamp. timestamp() = integer()
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:replace(tab1, <<"foo">>, <<"Goodbye, world!">>).
{ok,1271543165272987}

> brick_simple:replace(tab1, <<"key3">>, <<"new and improved value">>).
key_not_exist

> brick_simple:replace(tab1, "foo", "You again, world!", ['value_in_ram']).
{ok,1271543165272987}

> brick_simple:replace(tab1, "foo", "Whole new value", [{'testset', 12345}]).
{ts_error,1271543165272987}

> brick_simple:replace(tab1, "foo", "Whole new value", [{'testset', 1271543165272987}]).
{ok,1271543165272988}

> brick_simple:replace(tab1, "foo", "Foo again?", 30000).
{ok,1271543165272989}

brick_simple:set/6¶

Set Key and Value pair (and optional Flags) in the table Table, regardless of whether or not the key already exists.

brick_simple:set(Table, Key, Value)¶

brick_simple:set(Table, Key, Value, Flags)¶

brick_simple:set(Table, Key, Value, Timeout)

brick_simple:set(Table, Key, Value, ExpTime, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table to which to set the key-value pair -type table() :: atom() Key (key()) – Key to set in to the table, in association with a paired value -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution. The same is true of Value.

Parameters:

Value – Value to associate with the key -type val() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()] ExpTime (exp_time()) – Time at which the key will expire, expressed as a Unix time_t(). Optional; defaults to 0 (no expiration). -type exp_time() :: time_t() -type time_t() :: integer() Flags (flags_list()) – List of operational flags to apply to the set operation, and/or custom property flags to associate with the key-value pair in the database. Heavy use of custom property flags is discouraged due to RAM-based storage Optional; defaults to empty list -type flags_list() :: [do_op_flag() | property()] -type do_op_flag() :: {'testset', timestamp()} | 'value_in_ram' | {'exp_time_directive', 'keep' | 'replace'} | {'attrib_directive', 'keep' | 'replace'} -type timestamp() :: integer() -type property() :: atom() | {term(), term()} Operational flag usage {'testset', timestamp()} Fail the operation if the existing key’s timestamp is not exactly equal to timestamp(). If used inside a link:#brick-simple-do[micro-transaction], abort the transaction if the key’s timestamp is not exactly equal to timestamp(). Using this flag with set will result in an error if the key does not already exist or if the key exists but has a non-matching timestamp. {'exp_time_directive', 'keep' | 'replace'} Default to 'replace' Specifies whether the ExpTime is kept from the old key value pair or replaced with the ExpTime provided in the replace operation {'attrib_directive', 'keep' | 'replace'} Default to 'replace' Specifies whether the custom properties are kept from the old key value pair or replaced with the custom properties provided in the set operation If kept, the custom properties remain unchanged. If you specify custom properties explicitly in the set operation, Hibari adds them to the resulting key value pair If replaced, all original custom properties are deleted, and then Hibari adds the custom properties in the set operation to the resulting key value pair 'value_in_ram' Store the value blob in RAM, overriding the default storage location of the brick Note 'value_in_ram' flag have not been extensively tested Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{'ok', timestamp()}

Error returns

Return type:	'key_not_exists' The operation failed because the {'testset', timestamp()} flag was used and key does not exist -type timestamp() :: integer()
Return type:	{'ts_error', timestamp()} The operation failed because the {'testset', timestamp()} flag was used and there was a timestamp mismatch. The timestamp() in the return is the current value of the existing key’s timestamp. timestamp() = integer()
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:set(tab1, <<"key4">>, <<"cool value">>).
{ok,1271542959131192}

> brick_simple:set(tab1, "goo", "value6", ['value_in_ram']).
{ok,1271542959131193}

> brick_simple:set(tab1, "boo", "hoo", [{'testset', 1271543165272987}]).
key_not_exist

> brick_simple:set(tab1, "goo", "value7", [{'testset', 1271543165272432}]).
{ok,1271543165272433}

brick_simple:rename/6¶

Rename Key, Value pair, and Flags to NewKey in the table Table if the key already exists. The operation will fail if:

• Key does not already exist
• ... or Key and NewKey do not share a common key prefix. (See TODO (Creating New Table - VarPrefix) for more details)

brick_simple:rename(Table, Key, NewKey)¶

brick_simple:rename(Table, Key, NewKey, Flags)¶

brick_simple:rename(Table, Key, NewKey, Timeout)

brick_simple:rename(Table, Key, NewKey, ExpTime, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table to which to rename the key-value pair -type table() :: atom() Key (key()) – Key to rename in to the table, in association with a paired value -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution. The same is true of NewKey

Parameters:

NewKey – NewKey in the table, in association with an existing paired value -type val() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()] ExpTime (exp_time()) – Time at which the key will expire, expressed as a Unix time_t(). Optional; defaults to 0 (no expiration). -type exp_time() :: time_t() -type time_t() :: integer() Flags (flags_list()) – List of operational flags to apply to the rename operation, and/or custom property flags to associate with the key-value pair in the database. Heavy use of custom property flags is discouraged due to RAM-based storage Optional; defaults to empty list -type flags_list() :: [do_op_flag() | property()] -type do_op_flag() :: {'testset', timestamp()} | 'value_in_ram' | {'exp_time_directive', 'keep' | 'replace'} | {'attrib_directive', 'keep' | 'replace'} -type timestamp() :: integer() -type property() :: atom() | {term(), term()} Operational flag usage {'testset', timestamp()} Fail the operation if the existing key’s timestamp is not exactly equal to timestamp(). If used inside a link:#brick-simple-do[micro-transaction], abort the transaction if the key’s timestamp is not exactly equal to timestamp(). {'exp_time_directive', 'keep' | 'replace'} Default to 'keep' Specifies whether the ExpTime is kept from the old key value pair or replaced with the ExpTime provided in the rename operation {'attrib_directive', 'keep' | 'replace'} Default to 'keep' Specifies whether the custom properties are kept from the old key value pair or replaced with the custom properties provided in the rename operation If kept, the custom properties remain unchanged. If you specify custom properties explicitly in the rename operation, Hibari adds them to the resulting key value pair If replaced, all original custom properties are deleted, and then Hibari adds the custom properties in the rename operation to the resulting key value pair 'value_in_ram' Store the value blob in RAM, overriding the default storage location of the brick Note 'value_in_ram' flag have not been extensively tested Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{'ok', timestamp()}

Error returns

Return type:	'key_not_exists' The operation failed because the key does not exist or because key and the new key are equal -type timestamp() :: integer()
Return type:	{'ts_error', timestamp()} The operation failed because the {'testset', timestamp()} flag was used and there was a timestamp mismatch. The timestamp() in the return is the current value of the existing key’s timestamp. timestamp() = integer()
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key and the new key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:rename(tab1, <<"foo">>, <<"bar">>).
{ok,1271543165272987}

> brick_simple:rename(tab1, <<"key3">>, <<"bar">>).
key_not_exist

> brick_simple:rename(tab1, "foo", "bar", ['value_in_ram']).
{ok,1271543165272987}

> brick_simple:rename(tab1, "foo", "bar", [{'testset', 12345}]).
{ts_error,1271543165272987}

> brick_simple:rename(tab1, "foo", "bar", [{'testset', 1271543165272987}]).
{ok,1271543165272988}

> brick_simple:rename(tab1, "foo", "bar", 30000).
{ok,1271543165272989}

brick_simple:get/4¶

From table Table, retrieve Key and specified attributes of the key (as determined by Flags).

brick_simple:get(Table, Key)¶

brick_simple:get(Table, Key, Flags)¶

brick_simple:get(Table, Key, Timeout)

brick_simple:get(Table, Key, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table from which to retrieve the key-value pair -type table() :: atom() Key (key()) – Key to retrieve from to the table -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution

Parameters:

Flags (flags_list()) – List of operational flags to apply to the get operation. Optional; defaults to empty list -type flags_list() :: [do_op_flag()] -type do_op_flag() :: 'get_all_attribs' | 'witness' | {'testset', timestamp()} | 'must_exist' | 'must_not_exist' -type timestamp() :: integer() Operational flag usage 'get_all_attribs' Return all attributes of the key. May be used in combination with the witness flag 'witness' Do not return the value blob in the result. This flag will guarantee that the brick does not require disk access to satisfy this request {'testset', timestamp()} Fail the operation if the key’s timestamp is not exactly equal to timestamp(). If used inside a link:#brick-simple-do[micro-transaction], abort the transaction if the key’s timestamp is not exactly equal to timestamp(). This flag has priority over the 'must_exist' and 'must_not_exist' flags 'must_exist' For use inside a link:#brick-simple-do[micro-transaction]: abort the transaction if the key does not exist 'must_not_exist' For use inside a link:#brick-simple-do[micro-transaction]: abort the transaction if the key exists. This flag may be useful when the relationship between two or more keys is important to the client application Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success returns

Return type:	{'ok', timestamp(), val()} Success return when the get request uses neither the 'witness' flag nor the 'get_all_attribs' flag -type timestamp() :: integer() -type val() :: iodata() -type iodata() :: iolist() | binary() -type iolist()  :: [char() | binary() | iolist()]
Return type:	{'ok', timestamp()} Success return when the get uses 'witness' but not 'get_all_attribs'
Return type:	{'ok', timestamp(), exp_time(), proplist()} Success return when the get uses both 'witness' and 'get_all_attribs' -type exp_time() :: time_t() -type proplist() :: [property()] -type property() :: atom() | {term(), term()}
Return type:	{'ok', timestamp(), val(), exp_time(), proplist()} Success return when the get uses 'get_all_attribs' but not 'witness' -type exp_time() :: time_t()

Note

When a proplist() is returned, one of the properties in the list will always be {val_len, Size::integer()}, where Size is the size of the value blob in bytes

Error returns

Return type:	'key_not_exist' The operation failed because the key does not exist.
Return type:	{'ts_error', timestamp()} The operation failed because the {'testset', timestamp()} flag was used and there was a timestamp mismatch. The timestamp() in the return is the current value of the existing key’s timestamp.
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:get(tab1, "goo").
{ok,1271543165272432,<<"value7">>}

> brick_simple:get(tab1, "goo", ['witness']).
{ok,1271543165272432}

> brick_simple:get(tab1, "moo").
key_not_exist

brick_simple:get_many/5¶

Get many keys from a single chain in the table Table, up to a maximum of MaxNum keys. Keys are returned in lexicographic sorting order starting with the first key _after_ the key specified by the Key argument. The return list includes a boolean value indicating whether or not there are more keys after the last key of the return results.

brick_simple:get_many(Table, Key, MaxNum)¶

brick_simple:get_many(Table, Key, MaxNum, Flags)¶

brick_simple:get_many(Table, Key, MaxNum, Timeout)

brick_simple:get_many(Table, Key, MaxNum, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table to which to retrieve the key-value pair -type table() :: atom() Key (key()) – Key after which to start the get_many retrieval, proceeding in lexicographic order with the first key after the specified Key -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution

Parameters:

MaxNum (integer()) – Maximum number of keys to return Flags – List of operational flags to apply to the get_many operation. Optional; defaults to empty list -type flags_list() :: [do_op_flag()] -type do_op_flag() :: 'get_all_attribs' | 'witness' | {'binary_prefix', binary()} | {'max_bytes', integer()} | {'max_num', integer()} -type timestamp() :: integer() -type property() :: atom() | {term(), term()} Operational flag usage Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success returns

Return type:	{ok, {[{key(), timestamp(), val()}], boolean()}} Success return when the get_many request uses neither the 'witness' flag nor the 'get_all_attribs' flag -type timestamp() :: integer() -type val() :: iodata() -type iodata() :: iolist() | binary() iolist() :: [char() | binary() | iolist()]
Return type:	{ok, {[{key(), timestamp()}], boolean()}} Success return when the get_many uses 'witness' but not 'get_all_attribs'
Return type:	{ok, {[{key(), timestamp(), exp_time(), proplist()}], boolean()}} Success return when the get_many uses both 'witness' and 'get_all_attribs' -type exp_time() :: time_t() -type proplist() :: [property()] property() :: atom() | {term(), term()}
Trype:	{ok, {[{key(), timestamp(), val(), exp_time(), proplist()}], boolean()}} Success return when the get_many uses 'get_all_attribs' but not 'witness' exp_time() :: time_t()

Note

The boolean at the end of the success return indicates whether or not the chain has more keys lexicographically after the last key in the return (true for yes, false for no). When a proplist() is returned, one of the properties in the list will always be {val_len, Size::integer()}, where Size is the size of the value blob in bytes.

Error returns

Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:get_many(tab1, "", 5).
{ok,{[{<<"another">>,1271543102911775,<<"yes!">>},
      {<<"foo">>,1271543165272987,<<"Foo again?">>}],
     false}}

> brick_simple:get_many(tab1, "", 5, ['witness']).
{ok,{[{<<"another">>,1271543102911775},
      {<<"foo">>,1271543165272987}],
     false}}

> brick_simple:get_many(tab1, "", 5).
{ok,{[{<<"another">>,1271543102911775,<<"yes!">>,0,[{val_len,4}]},
      {<<"foo">>,1271543165272987,<<"Foo again?">>,0,[{val_len,6}]}],
     false}}

brick_simple:delete/4¶

Delete key Key from the table Table. The operation will fail if Key does not already exist

brick_simple:delete(Table, Key)¶

brick_simple:delete(Table, Key, Flags)¶

brick_simple:delete(Table, Key, Timeout)

brick_simple:delete(Table, Key, Flags, Timeout)¶

Parameters:	Table (table()) – Name of the table from which to delete the key-value pair -type table() :: atom() Key (key()) – Key to delete from the table -type key() :: iodata() -type iodata() :: iolist() | binary() -type iolist() :: [char() | binary() | iolist()]

Note

While the Key may be specified as either iolist() or binary(), it will be converted into binary before operation execution

Parameters:

Flags (flags_list()) – List of operational flags to apply to the delete operation. Optional; defaults to empty list -type flags_list() :: [do_op_flag()] -type do_op_flag() :: {'testset', timestamp()} | 'must_exist' | 'must_not_exist' -type timestamp() :: integer() Operational flag usage {'testset', timestamp()} Fail the operation if the existing key’s timestamp is not exactly equal to timestamp(). If used inside a link:#brick-simple-do[micro-transaction], abort the transaction if the key’s timestamp is not exactly equal to timestamp(). This flag has priority over the 'must_exist' and 'must_not_exist' flags 'must_exist' For use inside a link:#brick-simple-do[micro-transaction]: abort the transaction if the key does not exist 'must_not_exist' For use inside a link:#brick-simple-do[micro-transaction]: abort the transaction if the key exists. This flag may be useful when the relationship between two or more keys is important to the client application Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	'ok'

Error returns

Return type:	'key_not_exist' The operation failed because the key does not exist
Return type:	{'ts_error', timestamp()} The operation failed because the {'testset', timestamp()} flag was used and there was a timestamp mismatch. The timestamp() in the return is the current value of the existing key’s timestamp. timestamp() = integer()
Return type:	'invalid_flag_present' The operation failed because an invalid do_op_flag() was found in the Flags argument.
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable.
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain. -type node() :: atom()

> brick_simple:delete(tab1, <<"foo">>).
ok

> brick_simple:delete(tab1, "key6").
key_not_exist

> brick_simple:delete(tab1, "goo", [{'testset', 12345}]).
{ts_error,1271543165272987}

> brick_simple:delete(tab1, "goo", [{'testset', 1271543165272987}]).
ok

> brick_simple:delete(tab1, "key3", 30000).
ok

brick_simple:do/4¶

Send a list of primitive operations to the table Table. They will be executed at the same time by a Hibari brick. If the first item in the OpList is brick_server:make_txn() then the list of operations is executed in the context of a micro-transaction: either all operations will be executed successfully or none will be executed.

We term these “micro”-transactions because they are subject to certain limitations that apply to all operations that use the brick_simple:do() API:

• All impacted keys must be in the same table.
• All impacted keys must be in the same chain.
• All operations in the transaction must be sent in a single brick_simple:do() call. Unlike some other databases, it is not possible to request a transaction handle and to add operations to that transaction in an one-by-one, “ad hoc” manner.

For further information about micro-transactions, see link:hibari-sysadmin-guide.en.html#micro-transactions[Hibari System Administrator’s Guide, “Micro-Transactions” section].

brick_simple:do(Table, OpList)¶

brick_simple:do(Table, OpList, Timeout)¶

brick_simple:do(Table, OpList, OpFlags, Timeout)¶

Parameters:

Table (table()) – Name of the table in which to perform the operations -type table() :: atom() OpList (do_op_list()) – List of primitive operations to perform. Each primitive is invoked using the brick_server:make_*() API -type do_op_list() :: [do1_op()] -type do1_op() :: brick_server:make_add(Key, Value, ExpTime, Flags) brick_server:make_replace(Key, Value, ExpTime, Flags) brick_server:make_set(Key, Value, ExpTime, Flags) brick_server:make_rename(Key, NewKey, ExpTime, Flags) brick_server:make_get(Key, Flags) brick_server:make_get_many(Key, Flags) brick_server:make_delete(Key, Flags) brick_server:make_txn() Include brick_server:make_txn() as the first item in your OpList if you want the do operation to be executed as an atomic transaction Note that the arguments for each primitive are the same as those for the primitives when they are executed on their own, with the exclusion of the Tab and Timeout arguments, both of which serve as arguments to the overall do operation rather than as arguments to the primitives. For example, an add on its own is brick_simple:add(Tab, Key, Value, ExpTime, Flags, Timeout), whereas in the context of a do operation an add primitive is brick_server:make_add(Key, Value, ExpTime, Flags) For further information about each primitive, see link:#brick-simple-add[brick_simple:add/6], link:#brick-simple-replace[brick_simple:replace/6], link:#brick-simple-set[brick_simple:set/6], link:#brick-simple-rename[brick_simple:rename/6], link:#brick-simple-get[brick_simple:get/4], link:#brick-simple-get-many[brick_simple:get_many/5], and link:#brick-simple-delete[brick_simple:delete/4] OpFlags (do_flags_list()) – List of operational flags to apply to the overall do operation. Optional; defaults to empty list -type do_flags_list() :: [do_flag()] -type do_flag() :: 'fail_if_wrong_role' | 'ignore_role' Operational flag usage 'fail_if_wrong_role' If the ‘do’ operation is sent to the wrong brick in the target chain (e.g. a ‘read’ request mistakenly sent to the ‘head’ brick or a ‘write’ request mistakenly sent to the ‘tail’ brick), fail the transaction immediately. If this flag is not used, the default behavior is for the incorrect brick to forward the request to the correct brick 'ignore_role' If this flag is used, then whichever brick receives the request will reply to the request directly, regardless of the brick’s assigned role Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:

[do1_res_ok] List of do1_res_ok, one for each primitive operation specified in the do request. Return list order corresponds to the order in which primitive operations are listed in the request’s OpList. Note that if the do request does not use transaction semantics, then some individual primitive operations may fail without the overall do operation failing Within the return list, possible do1_res_ok returns to each individual primitive operation are the same as the possible returns that the primitive operation type could generate if it were executed on its own. For example, within the do operation’s success return list, the possible returns for a primitive add operation are the same as the returns described in the link:#brick-simple-add[brick_simple:add/6] section; potential returns to a primitive replace operation are the same as those described in the link:#brick-simple-replace[brick_simple:replace/6] section; and likewise for link:#brick-simple-set[set], likewise for link:#brick-simple-rename[rename], link:#brick-simple-get[get], link:#brick-simple-get-many[get_many], and link:#brick-simple-delete[delete].

Error returns

Return type:	{txn_fail, [{integer(), do1_res_fail()}]} Operation failed because transaction semantics were used in the do request and one or more primitive operations within the transaction failed. The integer() identifies the failed primitive operation by its position within the request’s OpList. For example, a 2 indicates that the second primitive listed in the request’s OpList failed. Note that this position identifier does not count the txn() specifier at the start of the OpList. do1_res_fail() indicates the type of failure for the failed primitive operation. Possibilities are: {'key_exists', timestamp()} -type timestamp() :: integer() 'key_not_exist' {'ts_error', timestamp()} 'invalid_flag_present'
Return type:	'invalid_flag_present' The operation failed because an invalid do_flag() was found in the do request’s OpFlags argument. Note this is a different error than an invalid flag being found within an individual primitive
Return type:	'brick_not_available' The operation failed because the chain that is responsible for this key is currently length zero and therefore unavailable
Return type:	{{'nodedown',node()},{'gen_server','call',term()}} The operation failed because the server brick handling the request has crashed or else a network partition has occurred between the client and server. The client should resend the query after a short delay, on the assumption that the Admin Server will have detected the failure and taken steps to repair the chain -type node() :: atom()

> brick_simple:do(tab1, [brick_server:make_add("foo3", "bar3"),
                         brick_server:make_add("foo4", "bar4")]).
[ok,ok]

> Do1 = brick_server:make_get("foo").
{get,<<"foo">>,[]}
> Do2 = brick_server:make_get("foo2").
{get,<<"foo2">>,[]}
> brick_simple:do(tab1, [Do1, Do2]).
[{ok,1271543102911775,<<"Foo again?">>},key_not_exist]

> Do1b = brick_server:make_get("foo").
{get,<<"foo">>,[]}
> Do2b = brick_server:make_get("foo2", [must_exist]).
{get,<<"foo2">>,[must_exist]}
> brick_simple:do(tab1, [brick_server:make_txn(), Do1b, Do2b]).
{txn_fail,[{2,key_not_exist}]}

brick_simple:fold_table/7¶

Attempt a fold operation across all keys in a table. For general information about the Erlang fold function that underlies this operations, see http://www.erlang.org/doc/man/lists.html#foldl-3.

brick_simple:fold_table(Table, Fun, Acc, NumItems, Flags)¶

brick_simple:fold_table(Table, Fun, Acc, NumItems, Flags, MaxParallel)¶

brick_simple:fold_table(Table, Fun, Acc, NumItems, Flags, MaxParallel, Timeout)¶

Parameters:

Table (table()) – Name of the table across which to perform the fold operation -type table() :: atom() Fun (fun_arity_2()) – Function to apply to successive elements of the list -type fun_arity_2() :: fun(({ChainName, TupleFromGetMany}, Acc) -> Acc) TupleFromGetMany is a single result tuple from a link:#brick-simple-get-many[brick_simple:get_many()] result. Its format can vary according to the Flags argument, which is passed as-is to a get_many() call. For example, if Flags = [], then TupleFromGetMany will match {Key, TS, Value}. If Flags = [witness], then TupleFromGetMany will match {Key, TS} Acc The accumulator term Acc (term()) – Initial value of the accumulator term NumItems (integer()) – Batch size used for get_many operations used by the fold function Flags (flags_list()) – List of operational flags to apply to the fold_table operation, The supported flags are the same as those for link:#brick-simple-get-many[brick_simple:get_many()] -type flags_list() :: [do_op_flag() | property()] -type do_op_flag() :: 'get_all_attribs' | 'witness' {'binary_prefix', binary()} | {'max_bytes', integer()} -type property() :: atom() | {term(), term()} Operational flag usage 'get_all_attribs' Return all attributes of each key. May be used in combination with the witness flag 'witness' Do not return the value blobs in the result. This flag will guarantee that the brick does not require disk access to satisfy this request {'binary_prefix', binary()} Return only keys that have a binary prefix that is exactly equal to binary() {'max_bytes', integer()} Return only as many keys as the sum of the sizes of their corresponding value blobs does not exceed integer() bytes MaxParallel (integer()) – If MaxParallel = 0, a true fold will be performed. If MaxParallel >= 1, then an independent fold will be performed on each chain, with up to MaxParallel number of folds running in parallel. The result from each chain fold will be returned to the caller as-is, i.e. will not be combined like in a “reduce” phase of a map-reduce cycle Optional; defaults to 0 Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{ok, Acc::term(), Iterations::integer()}

Error return

Return type:	{error, Error::term(), Acc::term(), Iterations::integer()}

brick_simple:fold_key_prefix/9¶

For a binary key prefix Prefix, fold over all keys in table Table starting with StartKey, sleeping for SleepTime milliseconds between iterations and using Flags and NumItems as arguments to link:#brick-simple-get-many[brick_simple:get_many()]. For general information about the Erlang fold function that underlies this operations, see http://www.erlang.org/doc/man/lists.html#foldl-3.

brick_simple:fold_key_prefix(Table, Prefix, Fun, Acc, Flags)¶

brick_simple:fold_key_prefix(Table, Prefix, StartKey, Fun, Acc, Flags, NumItems, SleepTime, Timeout)¶

Parameters:

Table (table()) – Name of the table in which to perform the fold operation -type table() :: atom() Prefix (binary()) – Key prefix for which to perform the fold operation StartKey (binary()) – Key at which to initiate the fold operation Optional; defaults to equal your specified Prefix Fun (fun_arity_2()) – Function to apply to successive elements of the list -type fun_arity_2() :: fun(({ChainName, TupleFromGetMany}, Acc) -> Acc) TupleFromGetMany is a single result tuple from a link:#brick-simple-get-many[brick_simple:get_many()] result. Its format can vary according to the Flags argument, which is passed as-is to a get_many() call. For example, if Flags = [], then TupleFromGetMany will match {Key, TS, Value}. If Flags = [witness], then TupleFromGetMany will match {Key, TS} Acc The accumulator term Acc (term()) – Initial value of the accumulator term Flags (flags_list()) – List of operational flags to apply to the fold_key_prefix operation. The supported flags are the same as those for link:#brick-simple-get-many[brick_simple:get_many()], excluding the {'binary_prefix', binary()} flag. This flag is inappropriate since the key prefix is passed directly through the Prefix argument of brick_simple:fold_key_prefix() -type flags_list() :: ['get_all_attribs' | 'witness' | {'max_bytes', integer()}] Operational flag usage 'get_all_attribs' Return all attributes of each key. May be used in combination with the witness flag 'witness' Do not return the value blobs in the result. This flag will guarantee that the brick does not require disk access to satisfy this request {'max_bytes', integer()} Return only as many keys as the sum of the sizes of their corresponding value blobs does not exceed integer() bytes NumItems (integer()) – Batch size used for get_many operations used by the fold function SleepTime (integer()) – Sleep time between interations, in milliseconds Optional; defaults to 0 Timeout (timeout()) – Operation timeout in milliseconds Optional; defaults to 15000 -type timeout() :: integer() | 'infinity'

Success return

Return type:	{ok, Acc::term(), Iterations::integer()}

Error return

Return type:	{error, Error::term(), Acc::term(), Iterations::integer()}

The Hibari Server’s Implementation of the UBF Protocol Stack¶

UBF representation of strings vs. binaries¶

The Erlang language does not have a data type specifically for strings. Instead, strings are typically represented as lists of integers (ASCII byte values) and/or binaries.

A UBF contract makes a distinction between a string, list, and binary. In the case of a string, UBF(A) encodes a string using the notation {'#S', "Hello, world!"} to represent the string “Hello, world!”.

This string encoding is cumbersome to use for developers; in Erlang, the ubf.hrl header file includes a macro ?S("Hello, world!") as a slightly less ugly shortcut. When using other languages, the 2-tuple and the atom '#S' would be created as any other 2-tuple and atom.

Fortunately, there is only one case where the string type is necessary: using the startSession metaprotocol command to start using the Hibari data server contract. An example will be shown below.

[[using-ubf-in-any-language]]

Steps for Using a UBF-based Protocol in Any Language¶

The steps to use a UBF-based protocol are the same in any language.

1. Create a connection to the UBF server.
   • ... or the EBF server, or the JSON-RPC server, or the Thrift server, or the ....
2. Use the UBF metaprotocol to start using the gdss contract, i.e. the Hibari server contract.
3. Send one or more Hibari server queries and decode the respective server responses.
4. Close the connection to the UBF server.

[[the-hibari-ubf-protocol-contract]]

The Hibari UBF Protocol Contract¶

The Hibari UBF Protocol contract can be found in the file ubf_gdss_plugin.con.

The names of the UBF types specified in the contract may differ slightly from the names of the types used in this document’s xref:client-api-erlang[]. For example, the UBF contract calls the key expiration time time exp_time(), while the type system in this document calls it expiry(). However, in all cases of slightly different names, the fundamental data type that both names use is the same: e.g. integer() for expiration time.

For each command, the UBF contract uses the following naming conventions:

• CommandName_req() for the request sent from client -> server, e.g. set_req() for the set command.
• CommandName_res() for the response sent from server -> client, e.g. set_res() for the set response.

The general form of a UBF RPC call is a tuple. The first element in the tuple is the name of the command, and the following elements are arguments for that command. The response can be any Erlang term, but the Hibari contract will only return the atom or tuple types.

The following is a mapping of UBF client request type to its Erlang API function, in alphabetical order.:

• add_req() -> brick_simple:add(), see xref:brick-simple-add[].
• delete_req() -> brick_simple:delete(), see xref:brick-simple-delete[].
• do_req() -> brick_simple:do(), see xref:brick-simple-do[].
• get_req() -> brick_simple:get(), see xref:brick-simple-get[].
• get_many_req() -> brick_simple:get_many(), see xref:brick-simple-get-many[].
• replace_req() -> brick_simple:replace(), see xref:brick-simple-replace[].
• set_req() -> brick_simple:set(), see xref:brick-simple-set[].
• rename_req() -> brick_simple:rename(), see xref:brick-simple-rename[].

[[using-ubf-erlang-client]]

Using the UBF Client Library for Erlang¶

As outlined in xref:using-ubf-in-any-language[], the first step is to create a connection to a Hibari server. If the Hibari cluster has multiple nodes, then it doesn’t matter which one that you connect to: all nodes can handle any UBF request and will route the query to the proper brick.

1. Create a connection to the UBF server (on “localhost” TCP port 7581):

   (asdf@bb3)54> {ok, P1, _} = ubf_client:connect("localhost", 7581, [{proto, ubf}], 5000).
   {ok,<0.139.0>,{'#S', "gdss_meta_server"}}
   

   The second step is to use the UBF metaprotocol to select the Hibari server, contract, called “gdss”, for all further commands for this connection.

   Tip

   The Hibari server contract is “stateless”. All replies terms from the ubf_client:rpc/2 function use the form {reply,ServerReply,UBF_StateName}. Because the Hibari server contract is stateless, the UBF_StateName will always be the atom none.

2. Use the UBF metaprotocol to request the “gdss” contract:

   (asdf@bb3)55> ubf_client:rpc(P1, {startSession, {'#S', "gdss"}, []}).
   {reply,{ok,ok},none}
   

   Now that the UBF connection is set up, we can use it to set a key “foo”.

3. Set the key “foo” in table tab1 with the value “foo val”, no expiration time, no flags, and a timeout of 5 seconds:

   (asdf@bb3)59> ubf_client:rpc(P1, {set, tab1, <<"foo">>, <<"foo val">>, 0, [], 5000}).
   {reply,ok,none}
   

   Note

   Note that the return value of both the set_req() (in the example above) and get_req() (in the example below) return the same types described in the xref:brick-simple-set[] and xref:brick-simple-get[], respectively.

   The only difference is that the ubf_client:rpc/2 function wraps the server’s reply in a 3-tuple: {reply,ServerReply,none}.

4. Get the key “foo” in table tab1, timeout in 5 seconds:

   (asdf@bb3)66> ubf_client:rpc(P1, {get, tab1, <<"foo">>, [], 5000}).
   {reply,{ok,1273009092549799,<<"foo val">>},none}
   

   If the client sends a request that violates the contract, the server will tell you, as in this example.

5. Send a contract-violating request:

   (asdf@bb3)89> ubf_client:rpc(P1, {bbb, 3000}).
   {reply,{clientBrokeContract,{bbb,3000},[]},none}
   

   When you are done with the connection, it is polite to close the connection explicitly. The server will quietly clean up its side of the connection if the client forgets to call or cannot call stop/1.

6. Close the UBF connection:

   (asdf@bb3)92> ubf_client:stop(P1).
   ok
   

[[using-ubf-java-client]]

Using the UBF Client Library for Java¶

The source code for the UBF client library for Java is included in the UBF source repository at link:http://github.com/ubf/ubf[http://github.com/ubf/ubf], in the priv/java subdirectory.

public class HibariTest {

    public static void main(String[] args) throws Exception {
        Socket sock = null;
        UBFClient ubf = null;

        try {
            sock = new Socket(args[0], 7581);
            ubf = UBFClient.new_via_sock(new UBFString("gdss"), new UBFList(),
                    new FooHandler(), sock);
        } catch (Exception e) {
            System.out.println(e);
            System.exit(1);
        }

        test_hibari_basics(ubf);

        ubf.stopSession();
        System.out.println("Success, it works");
        System.exit(0);
    }
    /* ... */
 }

public static class FooHandler implements UBFEventHandler {
    public FooHandler() {
    }
    public void handleEvent(UBFClient client, UBFObject event) {
        System.out.println("Hey, got an event: " + event.toString());
    }
    public void connectionClosed(UBFClient client) {
        System.out.println("Hey, connection closed, ignoring it\n");
    }
}

Using the EBF Client Library for Python¶

The source code for the EBF client library for Python is included in the UBF source repository at link:http://github.com/ubf/ubf[http://github.com/ubf/ubf], in the priv/python subdirectory.

NOTE: Recall that the EBF protocol is very closely related to UBF. The only significant difference is the “layer 5” session protocol layer: instead of using the UBF(A) protocol, the EBF (Erlang Binary Format) protocol is used instead. See xref:hibari-server-impl-of-ubf-proto-stack[] for more details.

In addition, you will need the “py_interface” package, developed by Tomas Abrahamsson and others. “py-interface” is distributed under the link:http://www.fsf.org/licensing/education/licenses/lgpl.html[GNU Library General Public License]. A git repository is hosted at repo.or.cz. To clone it and build it, use:

$ git clone git://repo.or.cz/py_interface.git
$ cd py_interface
$ autoconf
$ ./configure
$ make
$ pwd

Use the output of the last command, pwd, to remember the full directory path to the “py-interface” library. The example below assumes that path is /tmp/py-interface.

The pyebf.py file contains a small unit test that makes several calls to the Hibari UBF contract’s do_req() command. The results of (almost) every command are verified using the assert function.

env PYTHONPATH=/path/to/py_interface python pyebf.py

1. Connect to the Hibari server on “localhost” TCP port 7580 and use the UBF metaprotocol to switch to the gdss contract:

   ## login
   ebf.login('gdss', 'gdss_meta_server')
   

2. Delete the key 'foo' from table tab1:

   ## setup
   req0 = (Atom('do'), Atom('tab1'), [(Atom('delete'), 'foo', [])], [], 1000)
   res0 = ebf.rpc('gdss', req0)
   

3. Get the key 'foo' from table tab1:

   ## get - ng
   req1 = (Atom('do'), Atom('tab1'), [(Atom('get'), 'foo', [])], [], 1000)
   res1 = ebf.rpc('gdss', req1)
   assert res1[0] == 'key_not_exist'
   

4. Add the key 'foo' to table tab1. The do_req() interface requires managing the timestamp integers explicitly by the client; the timestamp 1 is used here:

   ## add - ok
   req2 = (Atom('do'), Atom('tab1'),
           [(Atom('add'), 'foo', 1, 'bar', 0, [])], [], 1000)
   res2 = ebf.rpc('gdss', req2)
   assert res2[0] == 'ok'
   

5. Add the key 'foo' to table tab1:

   ## add - ng
   req3 = (Atom('do'), Atom('tab1'),
           [(Atom('add'), 'foo', 1, 'bar', 0, [])], [], 1000)
   res3 = ebf.rpc('gdss', req3)
   assert res3[0][0] == 'key_exists'
   assert res3[0][1] == 1
   

6. Get the key 'foo' from table tab1, verifying that the timestamp is still 1 and value is still 'bar':

   ## get - ok
   req4 = (Atom('do'), Atom('tab1'), [(Atom('get'), 'foo', [])], [], 1000)
   res4 = ebf.rpc('gdss', req4)
   assert res4[0][0] == 'ok'
   assert res4[0][1] == 1
   assert res4[0][2] == 'bar'
   

7. Set the key 'foo' from table tab1, using a new timestamp 2:

   ## set - ok
   req5 = (Atom('do'), Atom('tab1'),
           [(Atom('set'), 'foo', 2, 'baz', 0, [])], [], 1000)
   res5 = ebf.rpc('gdss', req5)
   assert res5[0] == 'ok'
   

8. Get the key 'foo' from table tab1, verifying both the new timestamp and new value:

   ## get - ok
   req6 = (Atom('do'), Atom('tab1'), [(Atom('get'), 'foo', [])], [], 1000)
   res6 = ebf.rpc('gdss', req6)
   assert res6[0][0] == 'ok'
   assert res6[0][1] == 2
   assert res6[0][2] == 'baz'
   

The Hibari Thrift API¶

The Hibari Thrift API is defined as Hibari Service in link:./misc-codes/hibari.thrift[hibari.thrift]. At the time this API was developed, only Thrift 0.4.0 is available to us. This version is our first attempt to adopt Thrift. Some of the functions and options are not yet supported.

service Hibari {

   /**
    * Check connection availability / keepalive
    */
   oneway void keepalive()

   /**
    * Hibari Server Info
    */
   string info()

   /**
    * Hibari Description
    */
   string description()

   /**
    * Hibari Contract
    */
   string contract()

   /**
    * Add
    */
   HibariResponse Add(1: Add request)
       throws (1:HibariException ouch)

   /**
    * Replace
    */
   HibariResponse Replace(1: Replace request)
       throws (1:HibariException ouch)

   /**
    * Set
    */
   HibariResponse Set(1: Set request)
       throws (1:HibariException ouch)

   /**
    * Rename
    */
   HibariResponse Rename(1: Rename request)
       throws (1:HibariException ouch)

   /**
    * Delete
    */
   HibariResponse Delete(1: Delete request)
       throws (1:HibariException ouch)

   /**
    * Get
    */
   HibariResponse Get(1: Get request)
       throws (1:HibariException ouch)
   }

For each primitive utility function, it has exactly one input parameter. The parameter is an object that has a name matching its function. The object carries all mandatory and optional parameters to Hibari. This object could also be used to implement micro-transactions in the future.

Mapping UBF Contract Types to Thrift Types¶

You can find more details of the UBF / Thrift type conversion in (link:https://github.com/ubf/ubf-thrift[UBF-Thrift]).

Mapping UBF Contract to Thrift Service¶

Mapping UBF types to thrift primitives is different from mapping UBF contracts to service. Thrift mainly uses 2 different types to compose a request (struct and field).

If you are using Thrift to generate client code, you probably don’t need to worry about how the request being constructed. Visit link:http://wiki.apache.org/thrift/ThriftGeneration[Thrift Wiki] for the instruction to install Thrift and to generate client code. You will also need link:./misc-codes/hibari.thrift[hibari.thrift] to get started.

If you are interested in the UBF contract, the Hibari NTBF contract can be found in the file of ntbf_gdss_plugin.con.

Examples of using a Thrift client¶

Once you get the generated code, connecting to Hibari is easy. For example, adding the key 'fookey' to table tab1 with a value of 'Hello, world!' in the following 3 languages.

In Erlang:

-include("hibari_thrift.hrl").

% init
{ok, Client} = thrift_client:start_link("127.0.0.1", 7600, hibari_thrift),

% create the input parameter object
Request = #add{table=<<"tab1">>, key=<<"fookey">>, value=<<"Hello, world!">},

% send request
try
  HibariResponse = thrift_client:call(Client, 'Add', [Request]),
catch
  HibariException ->
    HibariException
end,

ok = thrift_client:close(Client).

In Java:

import com.hibari.rpc.*;

// init
TTransport transport = new TSocket("127.0.0.1", 7600);
TProtocol proto = new TBinaryProtocol(transport);
Hibari.Client client = new Hibari.Client(proto);
transport.open();

// create the input parameter object
Add request = new Add("tab1", ByteBuffer.wrap("fookey".getBytes()),
  ByteBuffer.wrap("Hello, world!".getBytes())))

// send request
try {
  HibariResponse response = client.Add(request);
} catch (HibariException e) {
  // ...
}

transport.close();

In python:

from hibari import Hibari

# init
transport = TSocket.TSocket('localhost', 7600)
transport.setTimeout(None)
transport = TTransport.TBufferedTransport(transport)
protocol = TBinaryProtocol.TBinaryProtocol(transport)
client = Hibari.Client(protocol)
transport.open()

# create the input parameter object
request = Add()
request.table = "tab1"
request.key = b"fookey"
request.value = b"Hello, world!"

# send request
response = client.Add(request)

transport.close()

Mapping TBF Contract Responses From Thrift Client¶

TBF only responses one of two generic types to all functions in Hibari Thrift API, HibariResponse or HibariException. One could expect a HibariResponse in an any successful cases. Otherwise a HibariException should be thrown.

Required Third Party Software¶

Before getting started, review this checklist of tools and software. Please install and set up as needed.

Downloading Hibari¶

Follow these steps to download the Hibari repositories from GitHub.

1. Create a working directory and retrieve the Hibari manifest files:

   $ mkdir working-directory
   $ cd working-directory
   $ repo init -u git://github.com/hibari/manifests.git -m hibari-default.xml
   

   Note

   Your “Git” identity is needed during the repo init step. Please enter the name and email of your GitHub account if you have one. Team members having read-write access should use repo init -u git@github.com:hibari/manifests.git -m hibari-default-rw.xml.

   Tip

   If you want to checkout the latest development version of Hibari, please append `` -b dev`` to the repo init command.

2. Download Hibari’s Git repositories:

   $ Repo sync
   

   After the repo sync, your working directory has the following structure:

   <working-directory>
    |- hibari/
      |- .git/
      |- .gitignore
      |- Makefile
      |- dialyze-ignore-warnings.txt
      |- dialyze-nospec-ignore-warnings.txt
      |- lib/                             <1>
        |- <application_name>/
          |- .git/
          |- .gitignore
          |- ebin/
          |- include/
            |- *.hrl
          |- priv/
          |- rebar.config
          |- src/
            |- <application_name>.app.src
            |- *.erl
          |- test/
            |- eunit/
              |- *.erl
            |- eqc/
              |- *.erl
        :
      |- rebar
      |- rebar.config
      |- rel/                             <2>
        |- files/
          |- app.config
          |- erl
          |- hibari
          |- hibari-admin
          |- nodetool
          |- nodetool-admin
          |- vm.args
        |- hibari/
          :
          |- releases/
            |- <release_vsn>/
              :
            :
          :
        |- reltool.config
    |- hibari-doc/                        <3>
      :
    |- manifests/                         <4>
      :
    |- patches/                           <5>
      :
    |- rebar/                             <6>
      :
    |- .repo/
      :
   

<1> Applications <2> Releases <3> Documentation <4> Manifests <5> Patches <6> Rebar

Building the Hibari Release Package¶

Follow these steps to build a Hibari release package.

1. Building basic recipe:

   $ cd working-directory/hibari
   $ make
   

1. Release packaging basic recipe:

   $ cd working-directory/hibari
   $ make package
   

[[HibariAsciiDoc]]

Building Hibari’s Documentation¶

Follow these steps to build Hibari’s documentation.

1. Building Hibari’s “Guides” basic recipe:

   $ cd working-directory/hibari-doc/src/hibari
   $ make clean -OR- make realclean
   $ make
   

2. Building Hibari’s “Website” basic recipe:

   $ cd working-directory/hibari-doc/src/hibari/website
   $ make clean -OR- make realclean
   $ make
   

Hibari’s documentation is authored using AsciiDoc and a few auxillary tools:

• ImageMagick
• dblatex
• Dia
• Graphviz
• Mscgen
• w3m

Hibari’s documentation is generated with AsciiDoc and a manually modified version of the a2x tool. A fake lang-ja.conf file can be easily created by making a symlink to the lang-en.conf file.

diff -r -u 8.6.4-orig/bin/a2x.py 8.6.4/bin/a2x.py
--- 8.6.4-orig/bin/a2x.py    2011-04-24 00:50:26.000000000 +0900
+++ 8.6.4/bin/a2x.py 2011-04-24 00:35:55.000000000 +0900
@@ -156,7 +156,10 @@
  def shell_copy(src, dst):
    verbose('copying "%s" to "%s"' % (src,dst))
      if not OPTIONS.dry_run:
-        shutil.copy(src, dst)
+        try:
+            shutil.copy(src, dst)
+        except shutil.Error:
+            return

  def shell_rm(path):
      if not os.path.exists(path):
 Only in 8.6.4/etc/asciidoc: lang-ja.conf

[[ErlangOTP]]

Building and Installing Erlang/OTP¶

Follow these steps to download and build Erlang/OTP from source, and to install the system. These steps provide a basic recipe; not all options are addressed.

1. Download the source code for your Erlang/OTP system:

   $ cd working-directory
   $ wget http://www.erlang.org/download/otp_src_R14B01.tar.gz
   

2. Untar the source code for your Erlang/OTP system:

   $ tar -xzf otp_src_R14B01.tar.gz
   

3. Configure Erlang/OTP:

   $ cd working-directory/otp_src_R14B01
   $ ./configure --prefix=otp-installing-directory-name
   

4. Build Erlang/OTP:

   $ make
   

5. Install Erlang/OTP:

   $ sudo make install
   

GitHub, Git, and Repo¶

to be added

List the working directories for all of Hibari’s “projects”:

$ repo forall -c "pwd"

Start a new topic (e.g. new-topic-name) branch:

$ repo start new-topic-name `repo forall -c "pwd" | xargs echo`

Abandon an existing topic (e.g. topic-name) branch:

$ repo abandon topic-name `repo forall -c "pwd" | xargs echo`

Track and checkout the master branch:

$ repo forall -c "git branch --track master github/master"
$ repo forall -c "git checkout master"

Track and checkout the dev (i.e. Development) branch:

$ repo forall -c "git branch --track dev github/dev"
$ repo forall -c "git checkout dev"

Code, Branch, and Version Management¶

to be added

Documentation¶

to be added

Submitting Patches¶

to be added