A newer version of this documentation is available.

View Latest

Backfill Support for N1QL

    +
    Configure the temporary working space for the N1QL engine and its embedded GSI client.

    (Introduced in Couchbase Server 5.5)

    Introduction

    When a query has an extremely large corresponding index scan, the indexer gsiClient buffers the results into the /tmp directory. Since this method has caused some high I/O and works differently on Windows, Couchbase Server 5.5 now lets the user configure the backfill directory via the UI, which will then pass the settings to the server.

    Prerequisites

    The user must have Cluster Admin privileges in order to be able to specify and configure the location for temporarily storing any transient-data during query processing per query-engine.

    Configuration

    In the Query Workbench > Settings page, click Advanced Query Settings to see: backfill QueryTempDiskPath circled

    In the Query Temp Disk Path textbox, enter the directory you want to use for your backfill file.

    In the Quota textbox, enter the number of megabytes for the maximum size of your backfill file.

    Your system administrator can read and modify the two REST backfill parameters:

    Setting Description Values Remarks

    query_tmpspace_dir

    The temp directory in which the indexer can create the scan_backfill file.

    Default value is /tmp

    Only absolute paths are allowed.

    query_tmpspace_limit

    The maximum limit in MB for the temporary file size.

    0 will disable backfill.

    -1 means the size is unlimited.

    The max size is limited only by your available disk space.

    Examples

    Example 1: Curl request to get the current "Advanced Query Settings".

    curl --GET -u Administrator:password http://localhost:8091/settings/querySettings

    Results:

    {"queryTmpSpaceDir":"/opt/couchbase/tmp","queryTmpSpaceSize":5120,"queryCurlWhitelist":{"all_access":false,"allowed_urls":["http://localhost:8091/settings/querySettings",""],"disallowed_urls":[""]}}

    Example 2: Curl request to change the temp file directory to tmp2 (after making a tmp2 directory).

    curl -X POST -u Administrator:password -d 'queryTmpSpaceDir=/opt/couchbase/tmp2'  http://localhost:8091/settings/querySettings

    Results:

    {"queryTmpSpaceDir":"/opt/couchbase/tmp2","queryTmpSpaceSize":5120,"queryCurlWhitelist":{"all_access":false,"allowed_urls":["http://localhost:8091/settings/querySettings",""],"disallowed_urls":[""]}}

    Example 3: Curl request to change the temp file size to 2048 MB.

    curl -X POST -u Administrator:password -d 'queryTmpSpaceDir=/opt/couchbase/tmp' -d 'queryTmpSpaceSize=2048' http://localhost:8091/settings/querySettings

    Results:

    {"queryTmpSpaceDir":"/opt/couchbase/tmp","queryTmpSpaceSize":2048,"queryCurlWhitelist":{"all_access":false,"allowed_urls":["http://localhost:8091/settings/querySettings",""],"disallowed_urls":[""]}}

    At the same time, the logs will contain messages for every change coming from both query and GSI, so after executing Example 3’s CURL statement:

    _time=2017-12-06T14:12:39.709-08:00 _level=INFO _msg=New settings received: {"query.settings.tmp_space_dir":"/opt/couchbase/tmp/","query.settings.tmp_space_size":2048}
    
    _time=2017-12-06T14:12:39.712-08:00 _level=INFO _msg=Settings notifier from metakv
    
    2017-12-06T14:12:39.715-08:00 [Info] GSIC - Setting config map[query_tmpspace_dir:/opt/couchbase/tmp/ query_tmpspace_limit:2048]
    
    _time=2017-12-06T14:12:39.715-08:00 _level=INFO _msg= Indexer settings have been updated map[query_tmpspace_dir:/opt/couchbase/tmp/ query_tmpspace_limit:2048]