Skip to content

Latest commit

 

History

History
218 lines (164 loc) · 6.36 KB

client.rst

File metadata and controls

218 lines (164 loc) · 6.36 KB
Raw

Client & Connections

To connect to a Riak cluster, you must create a :py~riak.client.RiakClient object. The default configuration connects to a single Riak node on localhost with the default ports. The below instantiation statements are all equivalent:

from riak import RiakClient, RiakNode

RiakClient()
RiakClient(protocol='http', host='127.0.0.1', http_port=8098)
RiakClient(nodes=[{'host':'127.0.0.1','http_port':8098}])
RiakClient(protocol='http', nodes=[RiakNode()])

Note

Connections are not established until you attempt to perform an operation. If the host or port are incorrect, you will not get an error raised immediately.

The client maintains a connection pool behind the scenes, one for each protocol. Connections are opened as-needed; a random node is selected when a new connection is requested.

Client objects

riak.client

RiakClient

PROTOCOLS

Prior to Riak 2.0 the 'https' protocol was also an option, but now secure connections are handled by the security-label feature.

protocol

client_id

resolver

nodes

The list of nodes <riak.node.RiakNode> that this client will connect to. It is best not to modify this property directly, as it is not thread-safe.

Nodes

The nodes <RiakClient.nodes> attribute of RiakClient objects is a list of RiakNode objects. If you include multiple host specifications in the RiakClient constructor, they will be turned into this type.

riak.node.RiakNode

Retry logic

Some operations that fail because of network errors or Riak node failure may be safely retried on another node, and the client will do so automatically. The items below can be used to configure this behavior.

RiakClient.retries

RiakClient.retry_count

riak.client.transport.DEFAULT_RETRY_COUNT

Client-level Operations

Some operations are not scoped by buckets or bucket types and can be performed on the client directly:

RiakClient.ping

RiakClient.get_buckets

RiakClient.stream_buckets

Accessing Bucket Types and Buckets

Most client operations are on :pybucket type objects <riak.bucket.BucketType>, the :pybucket objects <riak.bucket.RiakBucket> they contain or keys within those buckets. Use the bucket_type or bucket methods for creating bucket types and buckets that will proxy operations to the called client.

RiakClient.bucket_type

RiakClient.bucket

Bucket Type Operations

RiakClient.get_bucket_type_props

RiakClient.set_bucket_type_props

Bucket Operations

RiakClient.get_bucket_props

RiakClient.set_bucket_props

RiakClient.clear_bucket_props

RiakClient.get_keys

RiakClient.stream_keys

Key-level Operations

RiakClient.get

RiakClient.put

RiakClient.delete

RiakClient.multiget

RiakClient.fetch_datatype

RiakClient.update_datatype

--------------------Timeseries Operations --------------------

RiakClient.ts_describe

RiakClient.ts_get

RiakClient.ts_put

RiakClient.ts_delete

RiakClient.ts_query

RiakClient.ts_stream_keys

Query Operations

RiakClient.mapred

RiakClient.stream_mapred

RiakClient.get_index

RiakClient.stream_index

RiakClient.fulltext_search

RiakClient.paginate_index

RiakClient.paginate_stream_index

Search Maintenance Operations

RiakClient.create_search_schema

RiakClient.get_search_schema

RiakClient.create_search_index

RiakClient.get_search_index

RiakClient.delete_search_index

RiakClient.list_search_indexes

Serialization

The client supports automatic transformation of Riak responses into Python types if encoders and decoders are registered for the media-types. Supported by default are application/json and text/plain.

default_encoder

RiakClient.get_encoder

RiakClient.set_encoder

RiakClient.get_decoder

RiakClient.set_decoder

Deprecated Features

Full-text search

The original version of Riak Search has been replaced by yz-label, which is full-blown Solr integration with Riak.

If Riak Search 1.0 is enabled, you can query an index via the bucket's ~riak.bucket.RiakBucket.search method:

bucket.enable_search()
bucket.new("one", data={'value':'one'},
           content_type="application/json").store()

bucket.search('value=one')

To manually add and remove documents from an index (without an associated key), use the ~riak.client.RiakClient ~riak.client.RiakClient.fulltext_add and ~riak.client.RiakClient.fulltext_delete methods directly.

RiakClient.fulltext_add

RiakClient.fulltext_delete

Legacy Counters

The first Data Type introduced in Riak 1.4 were counters. These pre-date Bucket Types <bucket_types> and the current implementation. Rather than returning objects, the counter operations act directly on the value of the counter. Legacy counters are deprecated as of Riak 2.0. Please use :py~riak.datatypes.Counter instead.

Warning

Legacy counters are incompatible with Bucket Types.

RiakClient.get_counter

RiakClient.update_counter