\CouchbaseN1qlQuery

Represents a N1QL query

Summary

Methods
Properties
Constants
fromString()
adhoc()
crossBucket()
positionalParams()
namedParams()
rawParam()
consistency()
profile()
consistentWith()
readonly()
scanCap()
pipelineBatch()
pipelineCap()
maxParallelism()
No public properties found
NOT_BOUNDED
REQUEST_PLUS
STATEMENT_PLUS
PROFILE_NONE
PROFILE_PHASES
PROFILE_TIMINGS
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

NOT_BOUNDED

NOT_BOUNDED

This is the default (for single-statement requests).

No timestamp vector is used in the index scan. This is also the fastest mode, because we avoid the cost of obtaining the vector, and we also avoid any wait for the index to catch up to the vector.

REQUEST_PLUS

REQUEST_PLUS

This implements strong consistency per request.

Before processing the request, a current vector is obtained. The vector is used as a lower bound for the statements in the request. If there are DML statements in the request, RYOW is also applied within the request.

STATEMENT_PLUS

STATEMENT_PLUS

This implements strong consistency per statement.

Before processing each statement, a current vector is obtained and used as a lower bound for that statement.

PROFILE_NONE

PROFILE_NONE

Disables profiling. This is the default

PROFILE_PHASES

PROFILE_PHASES

Enables phase profiling.

PROFILE_TIMINGS

PROFILE_TIMINGS

Enables general timing profiling.

Methods

fromString()

fromString(string  $statement) : \Couchbase\N1qlQuery

Creates new N1qlQuery instance directly from the N1QL string.

Parameters

string $statement

N1QL string

Returns

\Couchbase\N1qlQuery

adhoc()

adhoc(boolean  $adhoc) : \Couchbase\N1qlQuery

Allows to specify if this query is adhoc or not.

If it is not adhoc (so performed often), the client will try to perform optimizations transparently based on the server capabilities, like preparing the statement and then executing a query plan instead of the raw query.

Parameters

boolean $adhoc

if query is adhoc, default is true (plain execution)

Returns

\Couchbase\N1qlQuery

crossBucket()

crossBucket(boolean  $crossBucket) : \Couchbase\N1qlQuery

Allows to pull credentials from the Authenticator

Parameters

boolean $crossBucket

if query includes joins for multiple buckets (default is false)

Returns

\Couchbase\N1qlQuery

Examples

Cross-bucket N1QL query
<?php
$authenticator = new \Couchbase\ClassicAuthenticator();
$authenticator->bucket('people', 'secret');
$authenticator->bucket('orders', '123456');

$cluster = new \Couchbase\Cluster("couchbase://localhost");
$cluster->authenticate($authenticator);

$bucket = $cluster->openBucket('orders');

$query = \Couchbase\N1qlQuery::fromString(
    "SELECT * FROM `orders` JOIN `people` ON KEYS `orders`.person_id ORDER BY `orders`.name");
$query->consistency(\Couchbase\N1qlQuery::REQUEST_PLUS);
$query->crossBucket(true);

$res = $bucket->query($query);
// $res inludes rows from orders and people buckets

positionalParams()

positionalParams(array  $params) : \Couchbase\N1qlQuery

Specify array of positional parameters

Previously specified positional parameters will be replaced. Note: carefully choose type of quotes for the query string, because PHP also uses $ (dollar sign) for variable interpolation. If you are using double quotes, make sure that N1QL parameters properly escaped.

Parameters

array $params

Returns

\Couchbase\N1qlQuery

Examples

<?php
$query = CouchbaseN1qlQuery::fromString('SELECT airportname FROM `travel-sample` WHERE city=$1 AND type=$2');
$query->positionalParams(["Los Angeles", "airport"]);

namedParams()

namedParams(array  $params) : \Couchbase\N1qlQuery

Specify associative array of named parameters

The supplied array of key/value pairs will be merged with already existing named parameters. Note: carefully choose type of quotes for the query string, because PHP also uses $ (dollar sign) for variable interpolation. If you are using double quotes, make sure that N1QL parameters properly escaped.

Parameters

array $params

Returns

\Couchbase\N1qlQuery

Examples

<?php
$query = CouchbaseN1qlQuery::fromString('SELECT airportname FROM `travel-sample` WHERE city=$city AND type=$airport');
$query->namedParams(['city' => "Los Angeles", 'type' => "airport"]);

rawParam()

rawParam(string  $key,   $value) : \Couchbase\AnalyticsQuery

Specify custom parameter for query

This function exists as escape hatch for cases when the Server has implemented some new query feature, while the SDK hasn't yet exposed the API on query object yet. The key must be a string, and param is JSON-serializable object.

Parameters

string $key
$value

Returns

\Couchbase\AnalyticsQuery

consistency()

consistency(integer  $consistency) : \Couchbase\N1qlQuery

Specifies the consistency level for this query

Parameters

integer $consistency

consistency level

Returns

\Couchbase\N1qlQuery

profile()

profile(string  $profileType) 

Controls the profiling mode used during query execution

Parameters

string $profileType

consistentWith()

consistentWith(\Couchbase\MutationState  $state) : \Couchbase\N1qlQuery

Sets mutation state the query should be consistent with

Parameters

\Couchbase\MutationState $state

the container of mutation tokens

Returns

\Couchbase\N1qlQuery

Examples

<?php
$cluster = new \Couchbase\Cluster('couchbase://localhost?fetch_mutation_tokens=true');
$bucket = $cluster->openBucket('default');

$doc = $bucket->upsert("foo", ['answer' => 42]);
$mutationState = \Couchbase\MutationState::from($doc);

$query = \Couchbase\N1qlQuery::fromString("SELECT * FROM `default` WHERE answer=42");
$result = $query->consistentWith($mutationState);
// the $result should contain information from "foo"

readonly()

readonly(boolean  $readonly) : \Couchbase\N1qlQuery

If set to true, it will signal the query engine on the server that only non-data modifying requests are allowed. Note that this rule is enforced on the server and not the SDK side.

Controls whether a query can change a resulting record set.

If readonly is true, then the following statements are not allowed:

  • CREATE INDEX
  • DROP INDEX
  • INSERT
  • MERGE
  • UPDATE
  • UPSERT
  • DELETE

Parameters

boolean $readonly

true if readonly should be forced, false is the default and will use the server side default.

Returns

\Couchbase\N1qlQuery

scanCap()

scanCap(integer  $scanCap) : \Couchbase\N1qlQuery

Advanced: Maximum buffered channel size between the indexer client and the query service for index scans.

This parameter controls when to use scan backfill. Use 0 or a negative number to disable.

Parameters

integer $scanCap

the scan_cap param, use 0 or negative number to disable.

Returns

\Couchbase\N1qlQuery

pipelineBatch()

pipelineBatch(integer  $pipelineBatch) : \Couchbase\N1qlQuery

Advanced: Controls the number of items execution operators can batch for Fetch from the KV.

Parameters

integer $pipelineBatch

the pipeline_batch param.

Returns

\Couchbase\N1qlQuery

pipelineCap()

pipelineCap(integer  $pipelineCap) : \Couchbase\N1qlQuery

Advanced: Maximum number of items each execution operator can buffer between various operators.

Parameters

integer $pipelineCap

the pipeline_cap param.

Returns

\Couchbase\N1qlQuery

maxParallelism()

maxParallelism(integer  $maxParallelism) : \Couchbase\N1qlQuery

Allows to override the default maximum parallelism for the query execution on the server side.

Parameters

integer $maxParallelism

the maximum parallelism for this query, 0 or negative values disable it.

Returns

\Couchbase\N1qlQuery