Import Filter Configuration

Pre-3.0 Legacy Configuration Equivalents

This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

Introduction

Using an import filter improves efficiency when working with large datasets:

You define import filters at the collection level to retrieve only the relevant documents you need rather than the entire dataset. The import filter determines which documents Sync Gateway can import, evaluating the application’s requirements and applying these criteria to all future changes.
By reducing the amount of data to process, an import filter improves the performance of your queries and analysis. Sync Gateway imports all documents by default, so use an import filter unless you have specific requirements otherwise.

For more information, see Import filter.

Set database import filter

Configure an import filter to control which documents are imported from Couchbase Server to Sync Gateway.

For complete endpoint details, including header parameters (such as If-Match for optimistic concurrency control) and body parameters, see /{keyspace}/_config/import_filter in the Admin REST API.

Provisioning Methods

You can provision an import filter using:

Admin REST API (Sync Gateway 3.0+): Use the /{keyspace}/_config/import_filter endpoint with the application/javascript mime type.
Legacy Configuration: Include the import filter in your configuration file. For more information, see import-filter.

Configuration Structure

Custom scopes and collections require Couchbase Lite 3.1 or later and Sync Gateway 3.1 or later.
Capella App Services and Sync Gateway releases earlier than version 3.1 do not support custom scopes and collections. When using Couchbase Lite 3.1 or later with earlier Sync Gateway versions, use the default collection as an alternative.

The configuration settings described here are provisioned through the Database Configuration endpoints.

{
  "scopes": {
      "scopename...": {
         "collections": {
            "collectionname...": {
               "import_filter": "function(doc) { if (doc.type != 'mobile') { return false } return true }",
            }
         }
      }
   },
   // other configuration
}

For more information, see Database Configuration Schema.

Property	Description
scopename	Represents the name of each scope
collections	Contains different collections within each scope
collectionname	Represents the name of each collection within a scope.
import_filter	Determines whether to import a document. The function checks the document’s type property. If it’s not 'mobile', the function returns false, otherwise it returns true.

Property

Description

scopename

Represents the name of each scope

collections

Contains different collections within each scope

collectionname

Represents the name of each collection within a scope.

import_filter

Determines whether to import a document. The function checks the document’s type property. If it’s not 'mobile', the function returns false, otherwise it returns true.

Example

Example 1. Configure import filter

This example demonstrates how to configure an import filter for a Sync Gateway database.

Admin REST API
Legacy Configuration

curl -X PUT "http://localhost:4985/froglist/_config/import_filter" \
-H "accept: application/json" \
-H "Content-Type: application/javascript" \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
-d "\"function(doc) {\ if (doc.type != 'mobile') {\ return false\ }\ return true\}\\\""

  {
    "databases": {
      "getting-started-db": {
        "bucket": "getting-started-bucket",
        "import_docs": true,
        "num_index_replicas": 0,
        // ... other config as required
        "import_filter": `
        function(doc) {
          if (doc.type != "mobile") {
            return false
          }
          return true
          }`,
        }
      }
  }

Schema

This section describes Sync Gateway’s import filter configuration in schema format to assist with constructing JSON models for use with the Admin REST API.

The configuration settings are provisioned through the Database Configuration endpoints.

Import Filter Model

The import_filter determines whether to make a document written to the Couchbase Server bucket available to Couchbase Mobile clients (whether to import it).

You should provision the filter as a JavaScript function in the request body of a call to the Admin Rest API endpoint PUT {db}/_config/import_filter.

Set the header’s content type to content-Type: application/javascript.

The function takes the document body as parameter and returns a boolean to indicate whether to import the document.

If you do not provide a filter function, Sync Gateway imports all documents.

Type: string

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials