Analytics Queries

class couchbase_core.analytics.AnalyticsQuery[source]
__init__(querystr, *args, **kwargs)[source]

Create an Analytics Query object. This may be passed as the params argument to AnalyticsRequest.

Parameters

  • querystr – The query string to execute

  • args – Positional placeholder arguments. These satisfy the placeholder values for positional placeholders in the query string, demarcated by ?.

  • kwargs – Named placeholder arguments. These satisfy named placeholders in the query string, such as $name, $email and so on. For the placeholder values, omit the leading dollar sign ($).

Use positional parameters:

q = AnalyticsQuery("SELECT VALUE bw FROM breweries "
                   "bw WHERE bw.name = ?", 'Kona Brewing')

for row in cb.analytics_query(q, "127.0.0.1"):
    print('Got {}'.format(str(row))

Use named parameters:

q = AnalyticsQuery("SELECT VALUE bw FROM breweries "
                   "bw WHERE bw.name = $brewery", brewery='Kona Brewing')
for row in cb.analytics_query(q, "127.0.0.1"):
    print('Got {}'.format(str(row))

When using placeholders, ensure that the placeholder value is the unserialized (i.e. native) Python value, not the JSON serialized value. For example the query SELECT VALUE bw FROM breweries bw WHERE bw.name IN ['Kona Brewing','21st Amendment Brewery Cafe'] can be rewritten using placeholders:

Correct:

AnalyticsQuery('SELECT VALUE bw FROM breweries bw WHERE bw.name IN ?',
          ['Kona Brewing', '21st Amendment Brewery Cafe'])

Incorrect:

AnalyticsQuery('SELECT VALUE bw FROM breweries bw WHERE bw.name IN ?',
          "[\"Kona Brewing\",\"21st Amendment Brewery Cafe\"]")

Since the placeholders are serialized to JSON internally anyway.

set_option(name, value)

Set a raw option in the query. This option is encoded as part of the query parameters without any client-side verification. Use this for settings not directly exposed by the Python client.

Parameters

  • name – The name of the option

  • value – The value of the option

consistent_with(state)

Indicate that the query should be consistent with one or more mutations.

Parameters

state (MutationState) – The state of the mutations it should be consistent with.

encoded

Get an encoded representation of the query.

This is used internally by the client, and can be useful to debug queries.

class couchbase_core.analytics.AnalyticsRequest[source]
__init__(params, host, parent)[source]

Object representing the execution of the request on the server.

Warning

You should typically not call this constructor by yourself, rather use the analytics_query() method (or one of its async derivatives).

Parameters

  • params – An AnalyticsQuery object.

  • host – the host to send the request to.

  • parent – The parent Bucket object

To actually receive results of the query, iterate over this object.

__iter__()
execute()

Execute the statement and raise an exception on failure.

This method is useful for statements which modify data or indexes, where the application does not need to extract any data, but merely determine success or failure.

meta
get_single_result()

Execute the statement and return its single result.

This should only be used on statements which are intended to return only a single result.

Returns

The single result, as encapsulated by the row_factory

class couchbase_core.analytics.DeferredAnalyticsQuery[source]
__init__(querystr, *args, **kwargs)[source]

Create a Deferred Analytics Query object. This may be passed as the params argument to DeferredAnalyticsRequest. Parameters are the same as an AnalyticsQuery.

Please note this is a volatile API, which is subject to change in future.

Parameters

  • querystr – The query string to execute

  • args – Positional placeholder arguments. These satisfy the placeholder values for positional placeholders in the query string, demarcated by ?.

  • kwargs – Named placeholder arguments. These satisfy named placeholders in the query string, such as $name, $email and so on. For the placeholder values, omit the leading dollar sign ($).

set_option(name, value)

Set a raw option in the query. This option is encoded as part of the query parameters without any client-side verification. Use this for settings not directly exposed by the Python client.

Parameters

  • name – The name of the option

  • value – The value of the option

encoded

Get an encoded representation of the query.

This is used internally by the client, and can be useful to debug queries.

class couchbase_core.analytics.DeferredAnalyticsRequest[source]
__init__(params, host, parent, timeout=None, interval=None)[source]

Object representing the execution of a deferred request on the server.

Please note this is a volatile API, which is subject to change in future.

Warning

You should typically not call this constructor by yourself, rather use the analytics_query() method (or one of its async derivatives).

Parameters

  • params – An DeferredAnalyticsQuery object.

  • host – the host to send the request to.

  • parent – The parent Bucket object.

  • timeout – Timeout in seconds.

  • interval – Interval in seconds for deferred polling.

To actually receive results of the query, iterate over this object.

__iter__()
execute()

Execute the statement and raise an exception on failure.

This method is useful for statements which modify data or indexes, where the application does not need to extract any data, but merely determine success or failure.

meta
get_single_result()

Execute the statement and return its single result.

This should only be used on statements which are intended to return only a single result.

Returns

The single result, as encapsulated by the row_factory

class couchbase_core.analytics_ingester.AnalyticsIngester[source]
__init__(id_generator=None, data_converter=<function AnalyticsIngester.<lambda>>, operation=<couchbase_core.analytics_ingester.BucketOperator object>)[source]

Initialise ingester.

Parameters

  • data_converter (DataConverter) – Single parameter Callable which takes a JSON input and returns a transformed JSON output.

  • id_generator (IdGenerator) – Callable that takes a JSON input and returns an ID string

  • operation (BucketOperator) – Callable that takes a bucket object, a key and a value and applies the key and value to the bucket (e.g. upsert/insert/replace)

__call__(bucket, query, host, ignore_ingest_error=False, *args, **kwargs)[source]

Run an analytics query, pass the results through the data converter, and the results of that into the id_generator, then apply the bucket operator to the bucket using the id generator result as the key, and the data converter result as the value.

Parameters

  • bucket (Bucket) – bucket to run query on

  • query (_GenericAlias[AnalyticsQuery, str]) – analytics query to run

  • host (str) – host to run it on

  • ignore_ingest_error (bool) – whether to suppress any exceptions raised during processing

  • args (Any) – positional args for analytics query

  • kwargs (Any) – named args for analytics query

Return type

None