Analytics using the PHP SDK

    +
    Parallel data management for complex queries over many records, using a familiar N1QL-like syntax.

    For complex and long-running queries, involving large ad hoc join, set, aggregation, and grouping operations, Couchbase Data Platform offers the Couchbase Analytics Service (CBAS). This is the analytic counterpart to our operational data focussed Query Service. The analytics service is available in Couchbase Data Platform 6.0 and later (developer preview in 5.5).

    Getting Started

    After familiarizing yourself with our introductory primer, in particular creating a dataset and linking it to a bucket to shadow the operational data, try Couchbase Analytics using the PHP SDK. Intentionally, the API for analytics is very similar to that of the query service. In these examples we will be using an airports dataset created on the travel-sample bucket.

    $options = new \Couchbase\AnalyticsQueryOptions();
    $result = $cluster->analyticsQuery('SELECT "hello" as greeting;', $options);
    
    foreach($result->rows() as $row) {
        printf("result: %s\n", $row["greeting"]);
    }

    Queries

    A query can either be simple or be parameterized. If parameters are used, they can either be positional or named. Here is one example of each:

    $options = new \Couchbase\AnalyticsQueryOptions();
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = "France";', $options);

    The query may be performed with positional parameters:

    $options = new \Couchbase\AnalyticsQueryOptions();
    $options->positionalParameters(["France"]);
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = $1;', $options);

    Alternatively, the query may be performed with named parameters:

    $options = new \Couchbase\AnalyticsQueryOptions();
    $options->namedParameters(['$country' => "France"]);
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = $country;', $options);
    As timeouts are propagated to the server by the client, a timeout set on the client side may be used to stop the processing of a request, in order to save system resources. See example in the next section.

    Options

    Additional parameters may be sent as part of the query.

    • Server Side Timeout, customizes the timeout sent to the server. Does not usually have to be set, as the client sets it based on the timeout on the operation. Uses timeout(long), and defaults to the Analytics timeout set on the client (75s). This can be adjusted at the cluster global config level.

    Here, we set a custom, server-side timeout value:

    $options = new \Couchbase\AnalyticsQueryOptions();
    $options->timeout(100);
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = "France";', $options);

    Handling the Response

    The analytics query result may contain various sorts of data and metadata, depending upon the nature of the query, as you will have seen when working through our introductory primer.

    $options = new \Couchbase\AnalyticsQueryOptions();
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = "France";', $options);
    
    foreach($result->rows() as $row) {
    printf("Name: %s, Country: %s\n", $row["name"], $row["country"]);
    }

    Common errors are listed in our Errors Reference doc, with errors caused by resource unavailability (such as timeouts and Operation cannot be performed during rebalance messages) leading to an automatic retry by the SDK.

    MetaData

    The metadata object contains useful metadata, such as Metrics and ClientContextID. Here is a snippet using several items of metadata

    $options = new \Couchbase\AnalyticsQueryOptions();
    $result = $cluster->analyticsQuery('SELECT airportname, country FROM airports WHERE country = "France";', $options);
    
    $metadata = $result->metadata();
    $metrics = $metadata->metrics();
    printf("Elapsed time: %d\n", $metrics["elapsedTime"]);
    printf("Execution time: %d\n", $metrics["executionTime"]);
    printf("Result count: %d\n", $metrics["resultCount"]);

    For a listing of available Metrics in MetaData, see the Understanding Analytics SDK doc.