CData Python Connector for Couchbase

Build 26.0.9655

CData Python Connector for Couchbase

Overview

The CData Python Connector for Couchbase allows developers to write Python scripts with connectivity to Couchbase. The connector wraps the complexity of accessing Couchbase data in an interface commonly used by Python connectors to common database systems.

Key Features

  • WHL installation packages that enable installation with "pip install".
  • Supported for Python 3.10 or newer on Windows, Linux, and macOS.
  • Write and execute SQL queries to fetch and update data in Couchbase.
  • Custom dialect class that enables SQLAlchemy 1.3 and 1.4 to use this connector.

Getting Started

See Getting Started to install the connector to your Python distribution and to create a basic connection to Couchbase.

Using the Python Connector/Using from Tools

See Using the Connector for examples of executing basic SELECT, INSERT, UPDATE, DELETE, and EXECUTE queries with the module's provided classes.

See Using from Tools to connect Couchbase data to tools such as Pandas or Petl.

SQLAlchemy ORM

SQLAlchemy can be leveraged to model the tables in Couchbase with mapped classes. See From SQLAlchemy for instructions for configuring the Python connector with SQLAlchemy.

Pandas

Pandas' DataFrames can be used alongside the connector to generate analytical graphics. See From Pandas for a guide.

Schema Discovery

See Schema Discovery to query the provided system tables, which allows users to discover the available tables, views, and stored procedure, alongside additional information about their columns or parameters.

Advanced Features

Advanced Features details additional features supported by the connector, such as defining user defined views, ssl configuration, remoting, caching, firewall/proxy settings, and advanced logging.

SQL Compliance

See SQL Compliance for a syntax reference and code examples outlining the supported SQL.

Data Model

See Data Model for the available database objects. This section also provides more detailed information on querying specific Couchbase entities.

Connection String Options

The Connection properties describe the various options that can be used to establish a connection.

CData Python Connector for Couchbase

Getting Started

Connecting to Couchbase

For information on the available WHL files for supported environments, and how to install the appropriate file for your Python distribution, see Package Installation.

For information on the module to import, and how to configure the necessary connection properties in a connection string, see Establishing a Connection.

Other available connection properties can be used to configure other aspects of the connector capabilities.

Python Version Support

The CData Python Connector for Couchbase can be installed and used in Python 3.10 or newer.

Couchbase Version Support

The CData Python Connector for Couchbase models Couchbase documents in a bucket as tables in a relational database; connect to Couchbase Server versions 4.0 and up, Enterprise Edition or Community Edition.

See Also

  • Using the Connector: Establish connections and query Couchbase through Python code.
  • From SQLAlchemy: Use SQLAlchemy to establish a connection with dialect URL, and interact with Couchbase data using mapped classes and Sessions.

CData Python Connector for Couchbase

Package Installation

Dependencies

The Python connectors require that Python 3.10 or newer be installed.

Installation

The CData Python Connector for Couchbase is available as a WHL file for Windows, Linux, and Mac. Each connector is built using the Python 3.10 Stable ABI (indicated by the abi3 tag in the filename), so a single wheel supports any Python 3.10 or newer installation — there is no need to match your exact Python minor version. Use the "pip install" command with the appropriate WHL file for your platform.

Windows:

pip install cdata_couchbase_connector-26.0.9655-cp310-abi3-win_amd64.whl

Linux:

pip install cdata_couchbase_connector-26.0.9655-cp310-abi3-linux_x86_64.whl

macOS:

pip install cdata_couchbase_connector-26.0.9655-cp310-abi3-macosx_12_0_arm64.whl

The macOS wheel supports arm64 (Apple Silicon) architectures only on macOS 12 and newer.

Regardless of the environment, certain distributions might require that the "pip3 install" command be used instead, to differentiate from a Python 2 distribution that might exist already. After installation, confirm whether the connector is successfully installed by running the "pip list" command. If "cdata_couchbase_connector" is present in the list output by the command, then the installation was successful.

Upgrading

When upgrading, "pip install" does not automatically clean up old JRE files. To avoid leftover files that could cause JVM errors, uninstall the previous version before installing the new one.

Licensing

After the installation is complete, a separate step is needed to activate a license for the connector. Among the CData assets in the distribution's site packages, there is an install-license tool that activates this license. From within the distribution's site-packages folder, after navigating to the "cdata/installlic_couchbase" folder, simply use a command like the below to activate the license. Omitting the <key> argument activates a trial license:

  • Windows:
    ./install-license.exe <key>
  • Linux / Mac:
    ./install-license.sh <key>

Sometimes, file access issues may cause pip to install the connector in a fallback file path that is not the python distribution's main or primary site-packages location. This can make it difficult to find where the connector was installed, and from there, the license activator. In that event, this python script below will print out the full file path of the connector's native file. This file will be stored in the mentioned cdata folder, from which the installlic_couchbase folder is trivial to find:

import os
import cdata.couchbase
path = os.path.abspath(cdata.couchbase.__file__)
print(path)

Uninstallation

If the connector needs to be uninstalled for any reason, do so by running the pip uninstall command, as in the example below:

pip uninstall cdata-couchbase-connector

CData Python Connector for Couchbase

Establishing a Connection

The objects available within our connector are accessible from the "cdata.couchbase" module. To use the module's objects directly:

  1. Import the module as follows:
    import cdata.couchbase as mod
  2. To establish a connection string, call the connect() method from the connector object using an appropriate connection string, such as:
    mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")

Connecting to Couchbase

To connect to data, set the Server property to the hostname or IP address of the Couchbase server(s) you are authenticating to.

If your Couchbase server is configured to use SSL, you can enable it either by using an https URL for Server (like https://couchbase.server), or by setting the UseSSL property to True.

Couchbase Analytics

By default, the connector connects to the N1QL Query service. In order to connect to the Couchbase Analytics service, you will also need to set the CouchbaseService property to Analytics.

Couchbase Cloud

Set the following to connect to Couchbase Cloud:

  • AuthScheme: Set this to Basic.
  • ConnectionMode: Set this to Cloud.
  • DNSServer: Set this to a DNS server. In most cases, this should be a public DNS service like 1.1.1.1 or 8.8.8.8.
  • SSLServerCert: Set this to the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected. Alternatively, set "*" to accept all certificates.

Authenticating to Couchbase

The connector supports several forms of authentication. Couchbase Cloud only accepts Standard authentication, while Couchbase Server accepts Standard authentication, client certificates, and credentials files.

Standard Authentication

To authenticate with standard authentication, set the following:

  • AuthScheme: Set this to Basic.
  • User: The user authenticating to Couchbase.
  • Password: The password of the user authenticating to Couchbase.

Client Certificates

The connector supports authenticating with client certificates when SSL is enabled. To use client certificate authentication, set the following properties:

Credentials File

You can also authenticate using using a credentials file containing multiple logins. This is included for legacy use and is not recommended when connecting to a Couchbase Server that supports role-based authentication.

CData Python Connector for Couchbase

Configuring JNI

Java Native Interface (JNI) is a standard programming interface for writing Java native methods and embedding the Java virtual machine into native applications.

The connector leverages the JNI for improved performance on Mac and Linux.

Configure the Config INI File

The Linux and Mac editions of the Couchbase python connector are configured with an ini file. This file is used to set several parameters, including JNI behavior. This file is to be located in:

{path_to_distribution_site-packages}/cdata/config.ini

Ensure that any configuration properties you set in the ini file fall under the following section name (adjust the 311 number if you are using an different python version from 3.11):

  • For Linux:
    [couchbase.cpython-311-x86_64-linux-gnu.so]
  • For Mac:
    [couchbase.cpython-311-darwin.so]

Configure the JNI connector's behavior by editing the properties in the connector's config.ini file. The connector can be configured as follows:

  • LOGFILE: Set this the same way as the CDATA_LOGFILE envrionment variable below.
  • JAVA_HOME: Configure the path to the JVM library location used to launch the JVM.
  • CLASS_PATH: Use a colon-separated list to configure the paths to the third-party jar libraries.

Configure Environment Variables

Additionally, set the following environment variables:

  • CDATA_JAVA_HOME: Configure the path to the JVM library location used to launch the JVM.
  • CDATA_JVM_OPTIONS: Place JVM options here.
  • CDATA_LOGFILE: Set this in the following scheme: <SCHEME>://<TAG>[|<LEVEL>]

    • SCHEME: The options are STDOUT, FILE.
      • STDOUT: Both the native wrapper and odbc core log into stdout. The Logfile and Verbosity properties can override the behavior of ODBC core.
      • FILE: The native wrapper logs into <FILENAME> while the odbc core logs into <FILENAME>.driver.log. The Logfile and Verbosity properties can override the behavior of ODBC core.
    • TAG
      • For STDOUT, set this to 1. For FILE, set this to the filename.
    • LEVEL
      • Set to one of: FATAL | ERROR | WARNING | INFO | DEBUG

The following are some examples of this syntax:

  • STDOUT://1|DEBUG
  • FILE:///tmp/my_py.log|DEBUG

Custom Logger

The Python connector supports a custom logging mechanism for redirecting log output to any destination, such as a cloud storage service or logging framework. Use setCustomLoggerFactory() to register a factory function that creates a logger instance for each connection.

The factory function receives the context string from the Logfile connection property (the portion after CUSTOM://) and must return an object with a writeLog(verbosity, message) method.

To enable custom logging:

  1. Call setCustomLoggerFactory() with your factory function before opening connections.
  2. Set Logfile to CUSTOM:// followed by a context string to identify the connection.
  3. Set Verbosity to the desired log level.

The following example demonstrates a custom logger factory that creates a separate logger instance per connection:

import cdata.couchbase as mod
import time

class MyLogger:
    def __init__(self, loggerId):
        self.loggerId = loggerId
    def writeLog(self, verbosity, message):
        print("[MyLogger " + self.loggerId + "] " + message)

def createLogger(context):
    return MyLogger(context[len("MyLoggerId="):])

mod.setCustomLoggerFactory(createLogger)

conn1 = mod.connect("...;Logfile=CUSTOM://MyLoggerId=1;Verbosity=2;")
# do something with conn1
time.sleep(1)  # Wait for logs to flush from conn1

conn2 = mod.connect("...;Logfile=CUSTOM://MyLoggerId=2;Verbosity=2;")
# do something with conn2
time.sleep(1)  # Wait for logs to flush from conn2

CData Python Connector for Couchbase

Schema Discovery and Indexe

Schema Detection and Indexes

The connector provides different modes for determining schemas and indexes. Below are some example configurations.

TableSupport=None

Disables all queries that find tables and discover columns. The only tables reported will be the ones defined in schema files. TypeDetectionScheme is ignored. The driver will only use the schema files found in the Location directory. Using this option without schema files will result in no tables being available.

TableSupport=Basic


 SELECT `bucket`, `scope`, name FROM system:keyspaces

The driver will discover the available buckets, but will not look inside of them for child tables. This is recommended for cases where you either want to reduce the time that schema detection takes, or if your buckets do not have primary indexes.

TableSupport=Full


 SELECT `travel-sample`.* FROM `travel-sample` LIMIT 100

The driver will discover the available buckets, and look inside of each of those buckets for child tables. This provides the most flexible way to access nested data, but requires that each bucket on your server have primary indexes.

TypeDetectionScheme=None

The driver does not do any flavor detection or column type detection. Columns are always reported as VARCHAR. Child tables are still scanned depending on TableSupport setting.

TypeDetectionScheme=RowScan

The driver reads a sample of documnets from a bucket and determines the data type. It does not do any flavor detection.

TypeDetectionScheme=Infer

This uses the NQ1QL INFER statement to determine what tables and columns exist. This does more felxible flavor detection than DocType, but is only available for Couchbase Enterprise.

TypeDetectionScheme=DocType


 SELECT META(`travel-sample`).id AS `Document.Id`, `travel-sample`.* FROM `travel-sample`

This discovers tables by checking at each bucket and looking for different values of the "docType" field in the documents. For Example, if the bucket beer-sample contains documents with "docType" = 'brewery' and "docType" = 'beer', this will generage three tables:bee-sample, beer-sample.brewery, and beer-sample.beer. Like RowScan, this will scan a sample of the documents in each flavor and determine the data type for each field.

CData Python Connector for Couchbase

Changelog

General Changes

DateVersionSourceCategoryTypeDescription
2026-05-2726.0.9643GeneralConnectionRemoved
  • Removed the deprecated ReplaceInvalidTypesWithNull connection property. Use the ReplaceInvalidValuesWithNull property instead.
2026-05-2226.0.9638PythonRemoved
  • Remove support for Intel x64 architecture on macOS
2026-05-0726.0.9623GeneralData ModelAdded
  • Added the ColumnCapabilities column to the sys_tablecolumns system table. This column is a bit mask denoting the column's write capabilities.
2026-05-0726.0.9623PythonChanged
  • Updated embedded JRE to jre-17.0.19+10 (Linux x64 / MacOs x64).
2026-05-0626.0.9622CouchbaseConnectionRemoved
  • Removed the "Auto" option from the AuthScheme connection property.
2026-04-1526.0.9601GeneralQuery ExecChanged
  • String comparisons using GREATER, LESS, and CONTAINS operators are now case-insensitive by default.
2026-01-1325.0.9509GeneralAdded
  • Added support for the REGEXP_REPLACE() string function.
2025-12-2125.0.9486PythonAdded
  • Added support for custom loggers in Python connectors on Linux and macOS.
2025-12-0525.0.9470GeneralAdded
  • Added support for the INSERT INTO SELECT statement, with driver-side execution for providers that do not support the operation natively.
2025-10-3025.0.9434PythonChanged
  • Updated embedded JRE to jre-17.0.17+10 (Linux x64 / MacOs x64).
2025-10-0625.0.9410GeneralAdded
  • Support for parsing datetime formats using ".S" and ",S" for milliseconds and nanoseconds.
2025-09-1225.0.9386GeneralAdded
  • Added the IsInsertable, IsUpdateable, and IsDeleteable columns to the sys_tables table.
2025-09-1025.0.9384GeneralChanged
  • All columns in statically defined Views are now reported as read-only.
2025-09-0325.0.9377GeneralChanged
  • Corrected the behavior when IN criteria with NULL values are used in the projection part. It now returns NULL instead of 0. For example, "NULL IN (1,2)" returns "NULL".
2025-09-0125.0.9375GeneralAdded
  • Added support for using the CAST function with infinity values. This function can cast "inf" and "-inf" to DOUBLE, FLOAT, or REAL.
2025-08-2125.0.9364GeneralChanged
  • Report behavior change:
    • Fixed inconsistent string value comparisons in non-table queries.
    • For example, "SELECT 'A' = 'a'" previously returned false, but it now returns true.
2025-08-1325.0.9356GeneralChanged
  • Changed the maximum number of pages held in memory from 15 to 5 for the page providers to decrease heap usage.
2025-07-0725.0.9319PythonRemoved
  • Removed the 32-bit version of Windows Python.
2025-07-0225.0.9314PythonRemoved
  • Removed support for Python 3.9.
2025-06-2525.0.9307GeneralRemoved
  • Removed the "ADLS Gen 1" value from the ConnectionType property.
2025-06-2525.0.9307PythonAdded
  • Added support for Python 3.13 in Windows, Linux, and Mac editions.
2025-06-2525.0.9307PythonRemoved
  • Removed support for Python 3.8 as it is no longer supported.
2025-06-2025.0.9302GeneralAdded
  • Created the following functions:
    • TEXT_ENCODE: encodes a string into a different charset (UTF8 → UTF7 and returns a binary array as the result).
    • TEXT_DECODE: takes a binary array and decodes it back into a string when provided the charset.
    • BASE64_ENCODE: takes a binary array and encodes it as a base64 string (varchar).
    • BASE64_DECODE: takes a base 64-encoded string and decodes it into a binary array.
2025-06-1825.0.9300GeneralChanged
  • The internal code for exception handling has been refactored. Exception messages returned during certain error conditions may now have different wording or formatting.
2025-05-2725.0.9278GeneralRemoved
  • Removed the "Proprietary" enum option from ProxyAuthscheme.
2025-05-1225.0.9263PythonChanged
  • Updated embedded JRE to jre-17.0.15+6 (Linux x64 / MacOS x64) and jre-17.0.15+6 (MacOS aarch64).
2025-02-1524.0.9177GeneralAdded
  • Added support for converting unsigned integer types to the nearest signed data type that has enough precision to hold the unsigned value.This is done for JDBC only because it does not have support for unsigned data types.
2024-11-2724.0.9097GeneralAdded
  • Added ThreadId to LogModule output. Logfile lines now include the Thread ID associated with the action being performed.
2024-08-0524.0.8983CouchbaseAdded
  • Added a new authentication scheme, JWT, to support JWT authentication.
  • Added 10 new connection properties to support JWT authentication: - JWTToken - JWTSubject - JWTIssuer - JWTAlgorithm - JWTExpiration - JWTKey - JWTKeyType - JWTClaims - JWTHeaders - CredentialsFileLocation
2024-06-0524.0.8922PythonAdded
  • Added support for Python 3.12.
2024-05-0924.0.8895GeneralChanged
  • The ROUND function previously did not accept negative precision values. That feature has now been restored.
2024-03-1523.0.8840GeneralAdded
  • Created a new SQL function called STRING_COMPARE that provides java's String.compare() ability to SQL queries. Returns a number representative of the compared value of two strings
2023-11-2923.0.8733GeneralChanged
  • The ROUND function doesn't accept the negative precision values anymore.
2023-11-2923.0.8733GeneralChanged
  • The returning types of the FDMonth, FDQuarter, FDWeek, LDMonth, LDQuarter, LDWeek functions are changed from Timestamp to Date.
  • The return type of the ABS function will be consistent with the parameter value type.
2023-11-2823.0.8732GeneralAdded
  • Added the HMACSHA256 formatter to allow for secrets to be decoded if it is in base64 format
2023-08-2923.0.8641PythonAdded
  • Added support for SQLAlchemy 2.0.
2023-06-2023.0.8571GeneralAdded
  • Added the new sys_lastresultinfo system table.
2023-05-1923.0.8539PythonAdded
  • Added support for Python 3.11 on Windows, Linux and Mac.
2023-05-1623.0.8536PythonRemoved
  • Removed support for Python 3.7 on Windows and Linux
2023-05-1523.0.8535CouchbaseAdded
  • Added support for parallelizing batch INSERT and UPSERT operations. MaxThreads determines the number of worker threads that the driver spawns when executing a batch operation. Parallelism happens within a single batch so for best results the batch size should be as large as possible.
2023-04-2523.0.8515GeneralRemoved
  • Removed support for the SELECT INTO CSV statement. The core code doesn't support it anymore.
2023-02-2122.0.8452CouchbaseAdded
  • Added support for Analytics views and tabular Analytics views. Tabular Analytics views use the metadata provided as part of the `CREATE ANALYTICS VIEW` DDL statement instead of performing rowscan. Supported column metadata includes column names, types, nullability, primary keys, and foreign keys. Both types of views have similar limitations to external Analytics collections (they do not support Document.Id or Document.TTL, and are not scanned for child tables).
2022-12-1422.0.8383GeneralChanged
  • Added the Default column to the sys_procedureparameters table.
2022-11-1522.0.8354PythonChanged
  • Updated embedded JRE to jre8u345-b01(Linux x64 / MacOS x64) and jre-17.0.5+8(MacOS aarch64).
2022-09-3022.0.8308GeneralChanged
  • Added the IsPath column to the sys_procedureparameters table.
2022-05-1822.0.8173PythonAdded
  • Added support for Python 3.10 on Windows, Linux, and Mac
  • Added support for Python 3.9 on Mac
  • Added support for Mac M1
2022-05-1822.0.8173PythonRemoved
  • Removed support for Python 3.6 on Windows and Linux
2022-01-1021.0.8045CouchbaseAdded
  • Added support for the NATIVEQUERY table function. This function can be used after a FROM to execute a query using Couchbase-native N1QL instead of SQL. For example, `SELECT * FROM NATIVEQUERY('SELECT META(a).id, b.rowdata FROM abucket AS a UNNEST a.rows AS b')` will execute the inner query directly on Couchbase and return the results. This will work even in tools which are not normally compatible with QueryPassthrough=true.
2021-12-2021.0.8024CouchbaseAdded
  • Added support for UpdateNullValues. This provides control over whether NULL values written to doucments via UPDATE are stored as NULL in Couchbase, or are removed from the document.
2021-10-2621.0.7969CouchbaseAdded
  • Added support for N1Q transactions. They apply to all N1QL queries that are not triggered by metadata or stored procedures. They can be either disabled entirely (the default), enabled for explicit use only (like **setAutoCommit(false)** or **BeginTransaction()**), or for implicit use where a one-statement transaction is used when no explicit transaction is active on the connection. Connection properties were also added to control transaction durability and lifetime requirements.
  • Added the corresponding connection properties, UseTransactions, TransactionDurability, and TransactionTimeout.
2021-09-1321.0.7926CouchbaseAdded
  • Added support for calling user-defined functions in N1QL and Analytics. Global functions may be called using their unscoped names (**to_meters("geo.lat")**) or their scoped names (**"Default.to_meters"("geo.lat")**). Scoped functions must be called using their fully qualified names, which are two-parts or three-parts in Analytics (**"experiments.to_meters"**) or three-parts only in N1QL (**"experiments.units.to_meters"**).
2021-09-0221.0.7915GeneralAdded
  • Added support for the STRING_SPLIT table-valued function in the CROSS APPLY clause.
2021-08-0721.0.7889GeneralChanged
  • Added the KeySeq column to the sys_foreignkeys table.
2021-08-0621.0.7888GeneralChanged
  • Added the new sys_primarykeys system table.
2021-07-2321.0.7874GeneralChanged
  • Updated the Literal Function Names for relative date/datetime functions. Previously, relative date/datetime functions resolved to a different value when used in the projection as opposed to the predicate. For example: SELECT LAST_MONTH() AS lm, Col FROM Table WHERE Col > LAST_MONTH(). Formerly, the two LAST_MONTH() methods would resolve to different datetimes. Now, they will match.
  • As a replacement for the previous behavior, the relative date/datetime functions in the criteria may have an 'L' appended to them. For example: WHERE col > L_LAST_MONTH(). This will continue to resolve to the same values that were previously calculated in the criteria. Note that the "L_" prefix will only work in the predicate - it not available for the projection.
2021-07-1421.0.7865CouchbaseAdded
  • Added support for performing DML on nested child tables in NewChildJoinsMode, which completes our new relational model. You can now INSERT, UPDATE, and DELETE on every table exposed by the provider when NCJM is enabled.
  • Added support for creating collections via DDL. When the hidden UseCollectionsForDDL property is enabled, CREATE TABLE "abucket.ascope.acollection"(...) will create the bucket, scope and collection which correspond to the table's name.
2021-05-1221.0.7802CouchbaseAdded
  • Added support for creating collections via DDL. When the hidden UseCollectionsForDDL property is enabled, CREATE TABLE "abucket.ascope.acollection"(...) will create the bucket, scope and collection which correspond to the table's name.
2021-04-2521.0.7785GeneralAdded
  • Added support for handling client side formulas during insert / update. For example: UPDATE Table SET Col1 = CONCAT(Col1, " - ", Col2) WHERE Col2 LIKE 'A%'
2021-04-2321.0.7783GeneralChanged
  • Updated how display sizes are determined for varchar primary key and foreign key columns so they will match the reported length of the column.
2021-04-1621.0.7776GeneralAdded
  • Non-conditional updates between two columns is now available to all drivers. For example: UPDATE Table SET Col1=Col2
2021-04-1621.0.7776GeneralChanged
  • Reduced the length to 255 for varchar primary key and foreign key columns.
2021-04-1621.0.7776GeneralChanged
  • Updated implicit and metadata caching to improve performance and support for multiple connections. Old metadata caches are not compatible - you need to generate new metadata caches if you are currently using CacheMetadata.
2021-04-1621.0.7776GeneralChanged
  • Updated index naming convention to avoid duplicates.
2021-04-1221.0.7772CouchbaseAdded
  • Added support for the USE KEYS query construct. When executing an N1QL query, the driver will attempt to determine if it contains any eligible filters on Document.Id - if there are any they are removed from the WHERE clause and migrated to the USE KEYS clause. When this transformation is applied the resulting query can avoid index scans, which allows for more queries to be run without a primary index and improves execution speed.
2021-03-1221.0.7741CouchbaseChanged
  • Updated AddDocuments and ManageIndices so the interface no longer operates based on **column#1** values. AddDocuments now accepts either a single ID and Document or a SourceTable that refers to a #TEMP table (analogus to a normal bulk insert), while ManageIndices accepts JSON arrays for multiple values since these are mostly typed by hand and have very few elements.
2021-01-1920.0.7689CouchbaseAdded
  • Added support for collections and scopes within Couchbase v7. This touches on a lot of the driver but here are the main aspects:
    • Tables are now generated for collections as well as buckets/datasets in both N1Ql and Analytics. They have dotted names similar to Analytics datasets. The only exceptions are N1QL default collections which just use the bucket name (the server calls them **_default**) and Analytics legacy dataverses (which have the same two-level hierarchy)
    • Queries can now use data from collections in all the usual ways (flavors, UNNEST, etc), and collection tables can now be used with DROP TABLE. Buckets still work with DROP TABLE as well but only in limited contexts to prevent users from deleting data outside the default collection.
    • Added new stored procedures for creating and dropping scopes/collections, and updated index management stored predures to report information about scopes/collections.
    • The Dataverse option now expects to follow SQL quoting rules, and can be either a single SQL identifier (**foo**) for legacy dataverses, or a two-level qualified identifier (**foo**.**bar**) for Analytics dataverses/scopes

CData Python Connector for Couchbase

NoSQL Database

Couchbase is a schema-free document database that provides high performance, availability, and scalability. These features are not necessarily incompatible with a standards-compliant query language like SQL-92.

The connector models the schema-free Couchbase objects into relational tables and translates SQL queries into N1QL or SQL++ (Analytics) queries to get the requested data. In this section we will show various schemes that the connector offers to bridge the gap with relational SQL and a document database.

Automatic Schema Discovery

When the connector first connects to Couchbase, it opens each bucket and scans a configurable number of rows from that bucket. It uses those rows to determine the columns in that bucket and their data types, as well as how to build flavored and child tables for any arrays within those documents. For Couchbase Enterprise version 4.5.1 and later, the connector may can also be configured to use the INFER command when TypeDetectionScheme is set to INFER. This allows the connector to get a more accurate column listing for the bucket, and to detect more complex flavors.

When using the Analytics service, the connector only does column and child table detection. Flavored tables are provided by Couchbase itself using shadow datasets. Also, Analytics mode does not currently have INFER support, so only row scan is supported.

For more details, refer to Automatic Schema Discovery to see how flavored tables and child tables are modelled from Couchbase data. Setting NumericStrings is also recommended as it can avoid type detection issues with certain kinds of text data.

Custom Schema Definitions

Optionally, you can use Custom Schema Definitions to project your chosen relational structure on top of a Couchbase object. This allows you to define your chosen column names, their data types, and the locations of their values in the Couchbase document.

Query Mapping

See Query Mapping for more details on how various N1QL and SQL++ operations are represented as SQL.

Vertical Flattening

See Vertical Flattening for more details on how arrays and objects are mapped into fields.

JSON Functions

See JSON Functions for more details on how to extract data from raw JSON strings.

CData Python Connector for Couchbase

Automatic Schema Discovery

Child Tables

If the documents within a bucket contain fields with arrays, then the connector will expose those fields as their own tables in addition to exposing them as JSON aggregates on the main table. The structure of these child tables depends upon whether the array contains objects or primitive values.

Array Child Tables

If the arrays contain primitive values like numbers or strings, the child table will have only two columns: one called "Document.Id" which is the primary key of the document containing the array, and one called "value" which contains the value within the array. For example, if the bucket "Games" contains these documents:

/* Primary key "1" */
{
  "scores": [1,2,3]
}

/* Primary key "2" */
{
  "scores": [4,5,6]
}

The connector will build a table called "Games_scores" containing these rows:

Document.Id value
1 1
1 2
1 3
2 4
2 5
2 6

Object Child Tables

If the arrays contain objects, the child table will have a column for each field that occurs within the objects, as well as a "Document.Id" column which contains the primary key of the document containing the array. For example, if the bucket "Games" contains these documents:

/* Primary key "1" */
{
  "moves": [
    {"piece": "pawn", "square": "c3"},
    {"piece": "rook", "square": "d5"}
  ]
}

/* Primary key "2" */
{
  "moves": [
    {"piece": "knight", "square": "f1"},
    {"piece": "bishop", "square": "e4"}
  ]
}

The connector will build a table called "Games_moves" containing these rows:

Document.Id piece square
1 pawn c3
1 rook d5
2 knight f1
2 biship e4

NewChildJoinsMode

Note that the above data model is not fully relational, which has important limitations for use-cases that involve complex JOINs or DML operations on child tables. The NewChildJoinsMode connection property exposes an alternative data model which avoids these limitations. Please refer to its page in the connection property section of the documentation for more details.

Flavored Tables

The connector can also detect when there are multiple types of documents within the same bucket, as long as TypeDetectionScheme is set to Infer or DocType and CouchbaseService is set to N1QL. These different types of documents are exposed as their own tables containing only the appropriate rows.

For example, the bucket "Games" contains documents which have a "type" value of either "chess" or "football":

/* Primary key "1" */
{
  "type": "chess",
  "result": "stalemate"
}

/* Primary key "2" */
{
  "type": "chess",
  "result": "black win"
}

/* Primary key "3" */
{
  "type": "football",
  "score": 23
}

/* Primary key "4" */
{
  "type": "football",
  "score": 18
}

The connector will create three tables for this bucket: one called "Games" which contains all the documents:

Document.Id result score type
1 stalemate NULL chess
2 black win NULL chess
3 NULL 23 football
4 NULL 18 football

One called "Games.chess" which contains only documents where the type is "chess":

Document.Id result type
1 stalemate chess
2 black win chess

And one called "Games.football" which contains only documents where the type is "football":

Document.Id score type
3 23 football
4 18 football

Note that the connector will not include columns in a flavored table that are not defined on the documents in that flavor. For example, even though both the "result" and "score" columns are included on the base table, "Games.chess" only includes "result" and "Games.football" only includes "score".

Flavored Child Tables

It is also possible for a flavored table to contain arrays, which will become their own child tables. For example, if the bucket "Games" contains these documents:
/* Primary key "1" */
{
  "type": "chess",
  "results": ["stalemate", "white win"]
}

/* Primary key "2" */
{
  "type": "chess",
  "results": ["black win", "stalemate"]
}

/* Primary key "3" */
{
  "type": "football",
  "scores": [23, 12]
}

/* Primary key "4" */
{
  "type": "football",
  "scores": [18, 36]
}
Then the connector will generate these tables:

Table Name Child Field Flavor Condition
Games
Games_results results
Games_scores scores
Games.chess "type" = "chess"
Games.chess_results results "type" = "chess"
Games.football "type" = "football"
Games.football_scores scores "type" = "football"

CData Python Connector for Couchbase

Query Mapping

The connector maps SQL-92-compliant queries into corresponding N1QL or SQL++ queries. Although the mapping below is not complete, it should help you get a sense for the common patterns the connector uses during this transformation.

SELECT Queries

The SELECT statements are translated to the appropriate N1QL SELECT query as shown below. Due to the similarities between SQL-92 and N1QL, many queries will simply be direct translations.

One major difference is that when the schema for a given Couchbase bucket exists in the connector, a SELECT * query will be translated to directly select the individual fields in the bucket. The connector will also automatically create a Document.Id column based on the primary key of each document in the bucket.

SQL Query N1QL Query
SELECT * FROM users SELECT META(`users`).id AS `id`, ... FROM `users`
SELECT [Document.Id], status FROM users SELECT META(`users`).id AS `Document.Id`, `users`.`status` FROM `users`
SELECT * FROM users WHERE status = 'A' OR age = 50 SELECT META(`users`).id AS `id`, ... FROM `users` WHERE TOSTRING(`users`.`status`) = "A" OR TONUMBER(`users`.`age`) = 50
SELECT * FROM users WHERE name LIKE 'A%' SELECT META(`users`).id AS `id`, ... FROM `users` WHERE TOSTRING(`users`.`name`) LIKE "A%"
SELECT * FROM users WHERE status = 'A' ORDER BY [Document.Id] DESC SELECT META(`users`).id AS `id`, ... FROM `users` WHERE TOSTRING(`users`.`status`) = "A" ORDER BY META(`users`).id DESC
SELECT * FROM users WHERE status IN ('A', 'B') SELECT META(`users`).id, ... FROM `users` WHERE TOSTRING(`users`.`status`) IN ["A", "B"]

Note that conditions can include extra type functions if the connector detects that a type conversion may be necessary. You can disable these type conversions using the StrictComparison property. For clarity, the rest of the N1QL samples are shown without these extra conversion functions.

USE KEYS Optimizations

When a query has either equals or IN clause that targets the Document.Id column, and there is no OR clause to override it, the connector will convert the Document.Id filter into a USE KEYS clause. This avoids the overhead of scanning an index because the document keys are already known to the N1QL engine (this optimization does not apply to the Analytics CouchbaseService).

SQL Query N1QL Query
SELECT * FROM users WHERE [Document.Id] = '1'SELECT ... FROM `users` USE KEYS ["1"]
SELECT * FROM users WHERE [Document.Id] IN ('2', '3') SELECT ... FROM `users` USE KEYS ["2", "3"]
SELECT * FROM users WHERE [Document.Id] = '4' OR [Document.Id] = '5' SELECT ... FROM `users` USE KEYS ["4", "5"]
SELECT * FROM users WHERE [Document.Id] = '6' AND status = 'A' SELECT ... FROM `users` USE KEYS ["6"] WHERE `status` = "A"

In addition to being used for SELECT queries, the same optimization is performed for DML operations as shown below.

Child Tables

As long as all the child tables in a query share the same parent, and they are combined using INNER JOINs on their Document.Id columns, the connector will combine the JOINs into a single UNNEST expression. Unlike N1QL UNNEST queries, you must explicitly JOIN with the base table if you want to access its fields.

SQL Query N1QL Query
SELECT * FROM users_posts SELECT META(`users`).id, `users_posts`.`text`, ... FROM `users` UNNEST `users`.`posts` AS `users_posts`
SELECT * FROM users INNER JOIN users_posts ON users.[Document.Id] = users_posts.[Document.Id] SELECT META(`users`).id, `users`.`name`, ..., `users_posts`.`text`, ... FROM `users` UNNEST `users`.`posts` AS `users_posts`
SELECT * FROM users INNER JOIN users_posts ... INNER JOIN users_comments ON ... SELECT ... FROM `users` UNNEST `users`.`posts` AS `users_posts` UNNEST `users`.`comments` AS `users_comments`

Flavor Tables

Flavored tables always have the appropriate condition included when you query, so that only documents from the flavor will be returned:

SQL Query N1QL Query
SELECT * FROM [users.subscriber] SELECT ... FROM `users` WHERE `docType` = "subscriber"
SELECT * FROM [users.subscriber] WHERE age > 50 SELECT ... FROM `users` WHERE `docType` = "subscriber" AND `age` > 50

Aggregate Queries

N1QL has several built-in aggregate functions. The connector makes extensive use of this for various aggregate queries. See some examples below:

SQL QueryN1QL Query
SELECT Count(*) As Count FROM OrdersSELECT Count(*) AS `count` FROM `Orders`
SELECT Sum(price) As total FROM OrdersSELECT Sum(`price`) As `total` FROM `Orders`
SELECT cust_id, Sum(price) As total FROM Orders GROUP BY cust_id ORDER BY totalSELECT `cust_id`, Sum(`price`) As `total` FROM `Orders` GROUP BY `cust_id` ORDER BY `total`
SELECT cust_id, ord_date, Sum(price) As total FROM Orders GROUP BY cust_id, ord_date Having total > 250SELECT `cust_id`, `ord_date`, Sum(`price`) As `total` FROM `Orders` GROUP BY `cust_id`, `ord_date` Having `total` > 250

INSERT Statements

The SQL INSERT statement is mapped to the N1QL INSERT statement as shown below. This works the same for both top-level fields as well as fields produced by Vertical Flattening:

SQL QueryN1QL Query
INSERT INTO users ([Document.Id], age, status) VALUES ('bcd001', 45, 'A') INSERT INTO `users` (KEY, VALUE) VALUES ('bcd001', { "age" : 45, "status" : "A" })
INSERT INTO users ([Document.Id], [metrics.posts]) VALUES ('bcd002', 0) INSERT INTO `users` (KEY, VALUE) VALUES ('bcd002', {"metrics': {"posts": 0}})

Child Table Inserts

Inserts on child tables are converted internally into N1QL UPDATEs using array operations. Since that this does not create the top-level document, the Document.Id provided must refer to a document that already exists.

Another limitation of child table INSERTs is that multi-valued INSERTs must all use the same Document.Id. The provider will verify this before modifying any data and raise an error if this constraint is violated.

SQL Query N1QL Query
INSERT INTO users_ratings ([Document.Id], value) VALUES ('bcd001', 4.8), ('bcd001', 3.2) UPDATE `users` USE KEYS "bcd001" SET `ratings` = ARRAY_PUT(`ratings`, 4.8, 3.2)
INSERT INTO users_reviews ([Document.Id], score) VALUES ('bcd002', 'Great'), ('bcd002', 'Lacking') UPDATE `users` USE KEYS "bcd001" SET `ratings` = ARRAY_PUT(`ratings`, {"score": "Great"}, {"score": "Lacking"})

Bulk INSERT Statements

Bulk INSERTs are also supported. The SQL Bulk INSERT is converted as shown below:

INSERT INTO users#TEMP ([Document.Id], KEY, VALUE) VALUES ('bcd001', 45, "A")
INSERT INTO users#TEMP ([Document.Id], KEY, VALUE) VALUES ('bcd002', 24, "B")
INSERT INTO users SELECT * FROM users#TEMP
is converted to:
INSERT INTO `users` (KEY, VALUE) VALUES
  ('bcd001', {"age": 45, "status": "A"}),
  ('bcd002', {"age": 24, "status": "B"})

Like multi-valued INSERTs on child tables, all the rows in a bulk INSERT must also have the same Document.Id.

Update Statements

The SQL UPDATE statement is mapped to the N1SQL UPDATE statement as shown below:

SQL QueryN1QL Query
UPDATE users SET status = 'C' WHERE [Document.Id] = 'bcd001' UPDATE `users` USE KEYS ["bcd001"] SET `status` = "C"
UPDATE users SET status = 'C' WHERE age > 45 UPDATE `users` SET `status` = "C" WHERE `age` > 45

Child Table Updates

When updating a child table, the SQL query is converted to an UPDATE query using either a "FOR" expression or an "ARRAY" expression:

SQL Query N1QL Query
UPDATE users_ratings SET value = 5.0 WHERE value > 5.0 UPDATE `users` SET `ratings` = ARRAY CASE WHEN `value` > 5.0 THEN 5 ELSE `value` END FOR `value` IN `ratings` END
UPDATE users_reviews SET score = 'Unknown' WHERE score = '' UPDATE `users` SET `$child`.`score` = 'Unknown' FOR `$child` IN `reviews` WHEN `$child`.`score` = "" END

Flavor Table Updates

Like flavor table SELECTs, UPDATEs on flavor tables always include the appropriate condition, so only docments belonging to the flavor are affected:

SQL Query N1QL Query
UPDATE [users.subscriber] SET status = 'C' WHERE age > 45 UPDATE `users` SET `status` = "C" WHERE `docType` = "subscriber" AND `age` > 45

Delete Statements

The SQL DELETE statement is mapped to the N1QL DELETE statement as shown below:

SQL QueryN1QL Query
DELETE FROM users WHERE [Document.Id] = 'bcd001' DELETE FROM `users` USE KEYS ["bcd001"]
DELETE FROM users WHERE status = 'inactive' DELETE FROM `users` WHERE `status` = "inactive"

Child Table Deletes

When deleting from a child table, the SQL query is converted to an UPDATE query using an "ARRAY" expression:

SQL Query N1QL Query
DELETE FROM users_ratings WHERE value < 0 UPDATE `users` SET `ratings` = ARRAY `value` FOR `value` IN `ratings` WHEN NOT (`value` < 0) END
DELETE FROM users_reviews WHERE score = '' UPDATE `users` SET `reviews` = ARRAY `$child` FOR `$child` IN `reviews` WHEN NOT (`$child`.`score` = "") END

Flavor Tables Deletes

Like flavor table SELECTs, DELETEs on flavor tables always include the appropriate condition, so only docments belonging to the flavor are affected:

SQL Query N1QL Query
DELETE FROM [users.subscriber] WHERE status = 'inactive' DELETE FROM `users` WHERE `docType` = "subscriber" AND status = "inactive"

CData Python Connector for Couchbase

Vertical Flattening

Example Document


/* Primary key "1" */
{
  "address" : {
    "building" : "1007",
    "coord" : [-73.856077, 40.848447],
    "street" : "Morris Park Ave",
    "zipcode" : "10462"
  },
  "borough" : "Bronx",
  "cuisine" : "Bakery",
  "grades" : [{
      "date" : "2014-03-03T00:00:00Z",
      "grade" : "A",
      "score" : 2
    }, {
      "date" : "2013-09-11T00:00:00Z",
      "grade" : "A",
      "score" : 6
    }, {
      "date" : "2013-01-24T00:00:00Z",
      "grade" : "A",
      "score" : 10
    }, {
      "date" : "2011-11-23T00:00:00Z",
      "grade" : "A",
      "score" : 9
    }, {
      "date" : "2011-03-10T00:00:00Z",
      "grade" : "B",
      "score" : 14
    }],
  "name" : "Morris Park Bake Shop",
  "restaurant_id" : "30075445"
}

Selecting Values In Objects

If the FlattenObjects property is configured to allow object flattening, then the connector will traverse objects and map the fields inside them as columns. For example, this query:
SELECT [address.building], [address.street] FROM restaurants
Would return this resultset:

address.building addres.street
1007 Morris Park Ave

Selecting Values In Arrays

If the FlattenArrays property is configured to allow array flattening, then the connector will traverse arrays and map their individual values as columns. For example, if Flatten Arrays were set to "2", then this query:
SELECT [address.coord.0], [address.coord.1] FROM restaurants
Would return this resultset:

address.coord.0 address.coord.1
-73.856077 40.838447

Note that array flattening should only be used in cases where you know the number of array items in advance, such as with "address.coord" which will always contain two items. For arrays like "grades" which can contain arbitrary numbers of items, consider using the child tables described in Automatic Schema Discovery instead, since they will allow you to read all of the values within the array.

CData Python Connector for Couchbase

User-Defined Functions

User-defined functions are a new feature provided by Couchbase 7 and up. They can be used with the connector like normal functions but with a special naming convention for using scoped functions. Normally the connector requires that functions already exist before they are used, to define them refer to the Couchbase documentation on CREATE FUNCTION queries. These may be run at the Couchbase console or with the connector in QueryPassthrough mode.

Couchbase has support for both scalar functions as well as functions that return results from subqueries. The connector supports scalar functions within its SQL dialect but subquery functions can only be used when QueryPassthrough is enabled. The rest of this section covers the connector's SQL dialect and assums that QueryPassthrough is disabled.

Global Functions

In both N1QL and Analytics mode, global user-defined functions can be accessed using either their simple names or their qualified names. The simple name is just the name of the function:

SELECT ageInYears(birthdate) FROM users

Global functions may also be invoked by qualifying them with the default namespace. Qualified names are quoted names that contain internal separators, which by default is a period though this can be changed using the DataverseSeparator property. In both N1QL and Analytics the global namespace is called Default:

SELECT [Default.ageInYears](birthdate) FROM users

Calling global functions using simple names is recommended. While the default qualfier is supported, its only intended use is for when a UDF clashes with a standard SQL function that the connector would otherwise translate.

Scoped Functions

Both N1QL and Analytics also allow functions to be defined outside of a global context. In Analytics functions can be attached to both dataverses and scopes which are called using two-part and three-part names respectively. In N1QL functions may only be attached to scopes so only three-part names may be used.

/* N1QL AND Analytics */
SELECT [socialNetwork.accounts.ageInYears](birthdate) FROM [socialNetwork.accounts.users]

/* Analytics only */
SELECT [socailNetwork.ageInYears](birthdate) FROM [socialNetwork.accounts.users]

CData Python Connector for Couchbase

JSON Functions

The connector can return JSON structures as column values. The connector enables you to use standard SQL functions to work with these JSON structures. The examples in this section use the following array:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

JSON_EXTRACT

The JSON_EXTRACT function can extract individual values from a JSON object. The following query returns the values shown below based on the JSON path passed as the second argument to the function:
SELECT Name, JSON_EXTRACT(grades,'[0].grade') AS Grade, JSON_EXTRACT(grades,'[0].score') AS Score FROM Students;

Column NameExample Value
GradeA
Score2

JSON_COUNT

The JSON_COUNT function returns the number of elements in a JSON array within a JSON object. The following query returns the number of elements specified by the JSON path passed as the second argument to the function:
SELECT Name, JSON_COUNT(grades,'[x]') AS NumberOfGrades FROM Students;

Column NameExample Value
NumberOfGrades5

JSON_SUM

The JSON_SUM function returns the sum of the numeric values of a JSON array within a JSON object. The following query returns the total of the values specified by the JSON path passed as the second argument to the function:
SELECT Name, JSON_SUM(score,'[x].score') AS TotalScore FROM Students;

Column NameExample Value
TotalScore 41

JSON_MIN

The JSON_MIN function returns the lowest numeric value of a JSON array within a JSON object. The following query returns the minimum value specified by the JSON path passed as the second argument to the function:
SELECT Name, JSON_MIN(score,'[x].score') AS LowestScore FROM Students;

Column NameExample Value
LowestScore2

JSON_MAX

The JSON_MAX function returns the highest numeric value of a JSON array within a JSON object. The following query returns the maximum value specified by the JSON path passed as the second argument to the function:
SELECT Name, JSON_MAX(score,'[x].score') AS HighestScore FROM Students;

Column NameExample Value
HighestScore14

DOCUMENT

The DOCUMENT function can be used to return an document as a JSON string. DOCUMENT(*) can be used with any type of SELECT query, including queries including other columns, queries including just DOCUMENT(*), and even more complex queries like JOINs.
SELECT [Document.Id], grade, score, DOCUMENT(*) FROM grades
For example, that query would return:

Document.Id grade score DOCUMENT
1 A 6 {"document.id":1,"grade":"A","score":6}
2 A 10 {"document.id":1,"grade":"A","score":10}
3 A 9 {"document.id":1,"grade":"A","score":9}
4 B 14 {"document.id":1,"grade":"B","score":14}

When used alone, DOCUMENT(*) returns the structure directly from Couchbase as if a N1QL or SQL++ SELECT * query were used. This means that no Document.Id value will be present since Couchbase does not include it automatically.

SELECT DOCUMENT(*) FROM grades
This query would return:

DOCUMENT
{"grades":{"grade":"A","score":6"}}
{"grades":{"grade":"A","score":10"}}
{"grades":{"grade":"A","score":9"}}
{"grades":{"grade":"B","score":14"}}

CData Python Connector for Couchbase

Custom Schema Definitions

In addition to Automatic Schema Discovery the connector also allows you to statically define the schema for your Couchbase object. Schemas are defined in text-based configuration files, which makes them easy to extend. You can call the CreateSchema stored procedure to generate a schema file; see Automatic Schema Discovery for more information.

Set the Location property to the file directory that will contain the schema file. The following sections show how to extend the resulting schema or write your own.

Example Document

Let's consider the document below and extract out the nested properties as their own columns:

/* Primary key "1" */
{
  "id": 12,
  "name": "Lohia Manufacturers Inc.",
  "homeaddress": {"street": "Main "Street", "city": "Chapel Hill", "state": "NC"},
  "workaddress": {"street": "10th "Street", "city": "Chapel Hill", "state": "NC"}
  "offices": ["Chapel Hill", "London", "New York"]
  "annual_revenue": 35600000
}
/* Primary key "2" */
{
  "id": 15,
  "name": "Piago Industries",
  "homeaddress": {street": "Main Street", "city": "San Francisco", "state": "CA"},
  "workaddress": {street": "10th Street", "city": "San Francisco", "state": "CA"}
  "offices": ["Durham", "San Francisco"]
  "annual_revenue": 42600000
}

Custom Schema Definition


<rsb:info title="Customers" description="Customers" other:dataverse="" other:bucket=customers"" other:flavorexpr="" other:flavorvalue="" other:isarray="false" other:pathspec="" other:childpath="">
  <attr name="document.id"        xs:type="string"  key="true" other:iskey="true" other:pathspec=""  />
  <attr name="annual_revenue"     xs:type="integer" other:iskey="false"           other:pathspec=""  other:field="annual_revenue" />
  <attr name="homeaddress.city"   xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.city" />
  <attr name="homeaddress.state"  xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.state" />
  <attr name="homeaddress.street" xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.street" />
  <attr name="name"               xs:type="string"  other:iskey="false"           other:pathspec=""  other:field="name" />
  <attr name="id"                 xs:type="integer" other:iskey="false"           other:pathspec=""  other:field="id" />
  <attr name="offices"            xs:type="string"  other:iskey="false"           other:pathspec=""  other:field="offices" />
  <attr name="offices.0"          xs:type="string"  other:iskey="false"           other:pathspec="[" other:field="offices.0" />
  <attr name="offices.1"          xs:type="string"  other:iskey="false"           other:pathspec="[" other:field="offices.1" />
  <attr name="workaddress.city"   xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.city" />
  <attr name="workaddress.state"  xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.state" />
  <attr name="workaddress.street" xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.street" />
</rsb:info>
In Custom Schema Example, you will find the complete schema that contains the example above.

Table Properties

The schema above uses the following properties to define specific qualities for the whole table. All of them are required:

Property Meaning
other:dataverse The name of the dataverse the dataset belongs to. Empty if not an Analytics view.
other:bucket The name of the bucket or dataset within Couchbase
other:flavorexpr The URL encoded condition in a flavored table. For example, "%60docType%60%20%3D%20%22chess%22".
other:flavorvalue The name of the flavor in a flavored table. For example, "chess".
other:isarray Whether the table is an array child table.
other:pathspec This is used to interpret the separators within other:childpath. See Column Properties for more details.
other:childpath The path to the attribute that is used to UNNEST the child table. Empty if not a child table.

Column Properties

The schema above uses the following properties to define specific qualities for each column:

Property Meaning
name Required. The name of the column, lower-cased.
key Used to mark the primary key. Required for Document.Id but optional for other columns.
xs:type Required. The type of the column within the connector.
other:iskey Required. Must be the same value as key, or "false" if key is not included.
other:pathspec Required. This is used to interpret the separators within other:field.
other:field Required. The path to the field in Couchbase.

Note that the fields which are produced by vertical flattening use the same syntax for separating array values and field values. This introduces a potential ambiguity in cases like the following, where the connector exposes the columns "numeric_object.0" and "array.0":

{
  "numeric_object": {
    "0": 0
  },
  "array": [
    0
  ]
}
To ensure that the connector can distinguish between field and array accesses, the pathspec is used to determine whether each "." in the field is an array or an object. Each "{" represents a field access, while each "[" represents an array access.

For example, with a field of "a.0.b.1" and a "pathspec" of "[{[", the N1QL expression "a[0].b[1]" would be generated. If instead the "pathspec" were "{{{", then the N1QL expression "a.`0`.b.`1`" would be generated.

CData Python Connector for Couchbase

Custom Schema Example

This section contains a complete schema. Set the Location property to the file directory that will contain the schema file. The info section enables a relational view of a Couchbase object. For more details, see Custom Schema Definitions. The table below allows the SELECT, INSERT, UPDATE, and DELETE commands as implemented in the GET, POST, MERGE, and DELETE sections of the schema below. The operations, such as couchbaseadoSysData, are internal implementations.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">  
  <rsb:info title="Customers" description="Customers" other:dataverse="" other:bucket=customers"" other:flavorexpr="" other:flavorvalue="" other:isarray="false" other:pathspec="" other:childpath="">
    <attr name="document.id"        xs:type="string"  key="true" other:iskey="true" other:pathspec=""  />
    <attr name="annual_revenue"     xs:type="integer" other:iskey="false"           other:pathspec=""  other:field="annual_revenue" />
    <attr name="homeaddress.city"   xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.city" />
    <attr name="homeaddress.state"  xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.state" />
    <attr name="homeaddress.street" xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="homeaddress.street" />
    <attr name="name"               xs:type="string"  other:iskey="false"           other:pathspec=""  other:field="name" />
    <attr name="id"                 xs:type="integer" other:iskey="false"           other:pathspec=""  other:field="id" />
    <attr name="offices"            xs:type="string"  other:iskey="false"           other:pathspec=""  other:field="offices" />
    <attr name="offices.0"          xs:type="string"  other:iskey="false"           other:pathspec="[" other:field="offices.0" />
    <attr name="offices.1"          xs:type="string"  other:iskey="false"           other:pathspec="[" other:field="offices.1" />
    <attr name="workaddress.city"   xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.city" />
    <attr name="workaddress.state"  xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.state" />
    <attr name="workaddress.street" xs:type="string"  other:iskey="false"           other:pathspec="{" other:field="workaddress.street" />
  </rsb:info>
</rsb:script>

CData Python Connector for Couchbase

Using the Connector

This section provides a walk-through for writing Couchbase data access code in Python script.

For more information on the available data source entities and how to query them with SQL, see Data Model. For the SQL syntax, see SQL Compliance.

Connecting from Code

For information on how to deploy the connector and configure the connection to Couchbase, see Package Installation and Establishing a Connection.

For information on how to connect with the couchbase.connector module and its related classes, see Connecting.

Executing SQL

The connection's cursor object is used to directly execute SQL queries. For information on how to execute SELECT statements and process the returned result sets, see Querying Data. For information on to modify the data in Couchbase with INSERT, UPDATE, and DELETE statements, see Modifying Data .

Executing Stored Procedures

You can call stored procedures by using the EXECUTE statement. For further information, see Calling Stored Procedures.

CData Python Connector for Couchbase

Connecting

Connecting with the cdata.couchbase Module:

The connector's module is used directly to establish a connection with the data source. It does this by using a connection string as its argument. For example:
import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")

Once the connection is created, you can use it to execute subsequent SQL queries.

CData Python Connector for Couchbase

Querying Data

After connecting as described in Connecting, you can use the open connection to execute SQL statements.

Executing Queries

To execute SQL statements that return data, use the execute() method. Once a query is executed, the result set is fetched from the cursor. This result set can then be iterated over to process the records individually.

For example:

cur = conn.execute("SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer]")
rs = cur.fetchall()
for row in rs:
	print(row)

Parameterized Queries

Various Python collections, such as arrays and tuples, can act as additional arguments for the execute() method. This enables you to parameterize the queries executed and help to prevent SQL Injection.

For example:

cmd = "SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = ?"
params = ["12345"]
cur = conn.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

CData Python Connector for Couchbase

Modifying Data

The connection is also used to issue INSERT, UPDATE, and DELETE commands to the data source. Parameters can be used with these statements if desired.

Note that the connector does not support transactions. As with normal write operations, all SQL statements executed by this connector affect the data source immediately. Call the connection's commit() method following the execution.

Insert

The following example adds a new record to the table:
cmd = "INSERT INTO [MyBucket].[MyScope].[Customer] (Name, TotalDue) VALUES (?, ?)"
params = ["Jon Doe", "John"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

Update

The following example modifies an existing record in the table:
cmd = "UPDATE [MyBucket].[MyScope].[Customer] SET TotalDue = ? WHERE Id = ?"
params = ["John", "1"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

Delete

The following example removes an existing record from the table:

cmd = "DELETE FROM [MyBucket].[MyScope].[Customer] WHERE Id = ?"
params = ["1"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

CData Python Connector for Couchbase

Calling Stored Procedures

You can execute stored procedures using either the execute() or callproc() method of the connection.

Calling Stored Procedures Using Execute()

When you call stored procedures by issuing EXECUTE commands, the stored procedure arguments are parameterized. For example:
cmd = "EXECUTE SelectEntries ObjectName = ?"
params = ["Account"]
conn.execute(cmd, params)

Calling Stored Procedures Using Callproc()

When you call stored procedured by issuing the callproc() method, the stored procedure arguments are a procedure name and a list of parameters. For example:
cur = conn.cursor()
params = ["Account"]
cur.callproc("SelectEntries", params)

CData Python Connector for Couchbase

Using from Tools

The connector is integrated with other tools and packages within Python.

Python Integration Guides

The following sections show how to create and use connections with the connector in common packages in Python:

Complete List of Couchbase Integration Quickstarts

For information on connecting from other applications, see Couchbase integration guides.

CData Python Connector for Couchbase

From SQLAlchemy

The CData Python Connector for Couchbase includes a Dialect class that enables integration with SQLAlchemy. Bear in mind that several aspects of connector functionality are not currently supported in SQLAlchemy 2.0 or above. If necessary, downgrade SQLAlchemy to version 1.4 or 1.3 before using this connector.

The following sections detail various aspects of this integration:

Connecting From SQLAlchemy

To construct a URL with which SQLAlchemy loads and uses the appropriate connector automatically, see Connecting

Reflecting Metadata With SQLAlchemy

To learn how to model Couchbase tables with mapped classes, see Reflecting Metadata.

Querying Data From SQLAlchemy

To learn how to use mapped classes to query the associated tables, see Querying Data.

Modifying Data From SQLAlchemy

The connector provides INSERT/UPDATE/DELETE functionality in SQLAlchemy. To learn how to call the session's execute() method to affect the data in the data source, see Modifying Data.

CData Python Connector for Couchbase

Connecting

Connecting With a Dialect URL

Establishing a connection using SQLAlchemy requires a specific URL format. For this connector, you can create the engine using either of the following URL formats:

Format 1


from sqlalchemy import create_engine
engine = create_engine("couchbase:///?User='myusername';Password='mypassword';Server='http://couchbase40'")

Format 2


from sqlalchemy import create_engine
engine = create_engine("couchbase://myusername:mypassword@couchbase40")

For SQLAlchemy 2.0, the dialect name is couchbase_2. To establish a connection, use the following URL format:

from sqlalchemy import create_engine
engine = create_engine("couchbase_2:///?User='myusername';Password='mypassword';Server='http://couchbase40'")

CData Python Connector for Couchbase

Reflecting Metadata

SQLAlchemy can act as an Object-relational Map (ORM). This enables you to treat records of a database table as instantiable records. To leverage this functionality, you must reflect the underlying metadata in one of the following ways.

Note: The following examples employ SQLAlchemy 1.4.

Modeling Data Using a Mapping Class

Use "sqlalchemy.ext.declarative.declarative_base" to declare a mapping class for the table you wish to model in the ORM. A known table in the data model is modeled either partially or completely, as shown in the following example:
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
class [MyBucket].[MyScope].[Customer](Base):
	__tablename__ = "[MyBucket].[MyScope].[Customer]"
	Id = Column(String, primary_key=True)
	Name = Column(String)
	TotalDue = Column(String)

Automatically Reflecting Metadata

Rather than mapping tables manually, SQLAlchemy can discover the metadata for one or more tables automatically. To accomplish this across the entire data model, use automap_base:
from sqlalchemy import MetaData
from sqlalchemy.ext.automap import automap_base
meta = MetaData()
abase = automap_base(metadata=meta)
abase.prepare(autoload_with=engine)
[MyBucket].[MyScope].[Customer] = abase.classes.[MyBucket].[MyScope].[Customer]

You can also reflect a single table with an inspector. When reflecting this way, providing a list of specific columns to map is optional:

from sqlalchemy import MetaData, Table
from sqlalchemy import inspect
meta = MetaData()
insp = inspect(engine)
[MyBucket].[MyScope].[Customer]_table = Table("[MyBucket].[MyScope].[Customer]", meta)
insp.reflect_table([MyBucket].[MyScope].[Customer]_table, ["Id","TotalDue"])

CData Python Connector for Couchbase

Querying Data

After you use the steps in Connecting to connect, and use one of the methods in Reflecting Metadata to reflect some of the metadata, you can use a session object to query data.

Querying Data Using the Query Method

If the mapping class has been prepared, use it with a session object to query the data source. After binding the engine to the session, provide the mapping class to the session's query method.

For example:

engine = create_engine("couchbase:///?User='myusername';Password='mypassword';Server='http://couchbase40'")
factory = sessionmaker(bind=engine)
session = factory()
for instance in session.query([MyBucket].[MyScope].[Customer]).filter_by(CustomerId="12345"):
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	print("TotalDue: ", instance.TotalDue)
	print("---------")

Querying Data Using the Execute Method

The session object can also run the query with the execute() method alongside the appropriate Table object. Assuming you have an active session, the following is just as viable:
[MyBucket].[MyScope].[Customer]_table = [MyBucket].[MyScope].[Customer].metadata.tables["[MyBucket].[MyScope].[Customer]"]
for instance in session.execute([MyBucket].[MyScope].[Customer]_table.select().where([MyBucket].[MyScope].[Customer]_table.c.CustomerId == "12345")):
	print("Id: ", instance.Id)
	print("FullName: ", instance.Name)
	print("City: ", instance.BillingCity)
	print("---------")

CData Python Connector for Couchbase

Executing JOINs

Implicit Joining

If mapped classes of related Couchbase objects have a singular foreign key relationship, the classes are implicitly joined. After importing the necessary objects, a relationship is established between your two mapped classes, as in the example below:
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, String, Integer, DateTime, ForeignKey
from sqlalchemy.orm import sessionmaker, relationship

Base = declarative_base()
class Contact(Base):
	__tablename__ = "Contact"
	Id = Column(Integer, primary_key=True)
	Name = Column(String)
	Email = Column(String)
	BirthDate = Column(DateTime)
	AccountId = Column(String, ForeignKey("Account.Id"))
	Account_Link = relationship("Account", back_populates="Contact_Link")

class Account(Base):
	__tablename__ = "Account"
	Id = Column(String, primary_key=True)
	Name = Column(String)
	BillingCity = Column(String)
	NumberOfEmployees = Column(Integer)
	Contact_Link = relationship("Contact", order_by=Contact.Id, back_populates="Account_Link")

Once the relationship is established, the tables are queried simultaneously using the session's query() method. For example:

rs = session.query(Account, Contact).filter(Account.Id == Contact.AccountId)
for Ac, Ct in rs:
  print("AccountId: ", Ac.Id)
  print("AccountName: ", Ac.Name)
  print("ContactId: ", Ct.Id)
  print("ContactName: ", Ct.Name)

Other Join Forms

In situations where mapped classes have either no foreign keys or multiple foreign keys, you may need different forms of the JOIN query to accommodate them. Using the earlier classes as examples, the following JOIN queries are possible as well:
  • Explicit condition (necessary if there are no foreign keys in your mapped classes):
    rs = session.query(Account, Contact).join(Contact, Account.Id == Contact.AccountId)
    for Ac, Ct in rs:
  • Left-to-right relationship:
    rs = session.query(Account, Contact).join(Account.Contact_Link)
    for Ac, Ct in rs:
  • Left-to-right relationship with explicit target:
    rs = session.query(Account, Contact).join(Contact, Account.Contact_Link)
    for Ac, Ct in rs:
  • String form of a left-to-right relationship:
    rs = session.query(Account, Contact).join("Contact_Link")
    for Ac, Ct in rs:

CData Python Connector for Couchbase

Other SQL Clauses

SQLAlchemy ORM also exposes support for other clauses in SQL, such as ORDER BY, GROUP BY, LIMIT, and OFFSET. All of these are supported by this connector:

ORDER BY

The following example sorts by a specified column using the session object's query() method:
rs = session.query([MyBucket].[MyScope].[Customer]).order_by([MyBucket].[MyScope].[Customer].AnnualRevenue)
for instance in rs:
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	print("TotalDue: ", instance.TotalDue)
	print("---------")

You can also use the session object's execute() method perform an ORDER BY. For example:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().order_by([MyBucket].[MyScope].[Customer]_table.c.AnnualRevenue))
for instance in rs:

GROUP BY

The following example uses the session object's query() method to group records with a specified column:
rs = session.query(func.count([MyBucket].[MyScope].[Customer].Id).label("CustomCount"), [MyBucket].[MyScope].[Customer].Name).group_by([MyBucket].[MyScope].[Customer].Name)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Name: ", instance.Name)
	print("---------")

You can also use the session object's execute() method to perform a GROUP BY:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().with_only_columns([func.count([MyBucket].[MyScope].[Customer]_table.c.Id).label("CustomCount"), [MyBucket].[MyScope].[Customer]_table.c.Name]).group_by([MyBucket].[MyScope].[Customer]_table.c.Name))
for instance in rs:

LIMIT and OFFSET

The following example uses the session object's query() method to skip the first 100 records and fetch the following 25:
rs = session.query([MyBucket].[MyScope].[Customer]).limit(25).offset(100)
for instance in rs:
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	print("TotalDue: ", instance.TotalDue)
	print("---------")

You can also use the session object's execute() method to set a LIMIT or OFFSET:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().limit(25).offset(100))
for instance in rs:

CData Python Connector for Couchbase

Aggregate Functions

Certain aggregate functions can also be used within SQLAlchemy by using the func module.

To import this module, execute:

from sqlalchemy.sql import func

Once func is imported, the following aggregate functions are available:

COUNT

The following example counts the number of records in a set of groups using the session object's query() method.
rs = session.query(func.count([MyBucket].[MyScope].[Customer].Id).label("CustomCount"), [MyBucket].[MyScope].[Customer].Name).group_by([MyBucket].[MyScope].[Customer].Name)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Name: ", instance.Name)
	print("---------")

You can also execute COUNT using the session object's execute() method:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().with_only_columns([func.count([MyBucket].[MyScope].[Customer]_table.c.Id).label("CustomCount"), [MyBucket].[MyScope].[Customer]_table.c.Name])group_by([MyBucket].[MyScope].[Customer]_table.c.Name))
for instance in rs:

SUM

This example calculates the cumulative amount of a numeric column in a set of groups.

rs = session.query(func.sum([MyBucket].[MyScope].[Customer].AnnualRevenue).label("CustomSum"), [MyBucket].[MyScope].[Customer].Name).group_by([MyBucket].[MyScope].[Customer].Name)
for instance in rs:
	print("Sum: ", instance.CustomSum)
	print("Name: ", instance.Name)
	print("---------")

You can also invoke SUM using the session object's execute() method.

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().with_only_columns([func.sum([MyBucket].[MyScope].[Customer]_table.c.AnnualRevenue).label("CustomSum"), [MyBucket].[MyScope].[Customer]_table.c.Name]).group_by([MyBucket].[MyScope].[Customer]_table.c.Name))
for instance in rs:

AVG

This example uses the session object's query() method to calculate the average amount of a numeric column in a set of groups:
rs = session.query(func.avg([MyBucket].[MyScope].[Customer].AnnualRevenue).label("CustomAvg"), [MyBucket].[MyScope].[Customer].Name).group_by([MyBucket].[MyScope].[Customer].Name)
for instance in rs:
	print("Avg: ", instance.CustomAvg)
	print("Name: ", instance.Name)
	print("---------")

You can also use the session object's execute() method to invoke AVG:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().with_only_columns([func.avg([MyBucket].[MyScope].[Customer]_table.c.AnnualRevenue).label("CustomAvg"), [MyBucket].[MyScope].[Customer]_table.c.Name]).group_by([MyBucket].[MyScope].[Customer]_table.c.Name))
for instance in rs:

MAX and MIN

This example finds the maximum value and minimum value of a numeric column in a set of groups.
rs = session.query(func.max([MyBucket].[MyScope].[Customer].AnnualRevenue).label("CustomMax"), func.min([MyBucket].[MyScope].[Customer].AnnualRevenue).label("CustomMin"), [MyBucket].[MyScope].[Customer].Name).group_by([MyBucket].[MyScope].[Customer].Name)
for instance in rs:
	print("Max: ", instance.CustomMax)
	print("Min: ", instance.CustomMin)
	print("Name: ", instance.Name)
	print("---------")

You can also use the session object's execute() method to invoke MAX and MIN:

rs = session.execute([MyBucket].[MyScope].[Customer]_table.select().with_only_columns([func.max([MyBucket].[MyScope].[Customer]_table.c.AnnualRevenue).label("CustomMax"), func.min([MyBucket].[MyScope].[Customer]_table.c.AnnualRevenue).label("CustomMin"), [MyBucket].[MyScope].[Customer]_table.c.Name]).group_by([MyBucket].[MyScope].[Customer]_table.c.Name))
for instance in rs:

CData Python Connector for Couchbase

Modifying Data

Commands can be executed individually by the session with a call to "execute()".

Obtaining the Table Object

The query supplied to this method is constructed using the associated Table object of a mapped class. This Table object is obtained from the mapped class's metadata field, as below:

[MyBucket].[MyScope].[Customer]_table = [MyBucket].[MyScope].[Customer].metadata.tables["[MyBucket].[MyScope].[Customer]"]

Once the table object is obtained, the write operations are executed in the following ways. The queries are executed immediately without the need for a call to "commit()":

Insert

The following example adds a new record to the table:

session.execute([MyBucket].[MyScope].[Customer]_table.insert(), {"Name": "Jon Doe", "TotalDue": "John"})

Update

The following example modifies an existing record in the table:

session.execute([MyBucket].[MyScope].[Customer]_table.update().where([MyBucket].[MyScope].[Customer]_table.c.Id == "1").values(Name="Jon Doe", TotalDue="John"))

Delete

The following example removes an existing record from the table:

session.execute([MyBucket].[MyScope].[Customer]_table.delete().where([MyBucket].[MyScope].[Customer]_table.c.Id == "1"))

CData Python Connector for Couchbase

From Pandas

When combined with the connector, Pandas can be used to generate data frames that contain your Couchbase data. Once created, a data frame can be passed to various other Python packages.

Connecting

Pandas relies on an SQLAlchemy engine to execute queries. Before you can use Pandas you must import it:
import pandas as pd
from sqlalchemy import create_engine
engine = create_engine("couchbase:///?User='myusername';Password='mypassword';Server='http://couchbase40'")

Querying Data

In Pandas, SELECT queries are provided in a call to the read_sql() method, alongside a relevant connection object. Pandas executes the query on that connection, and returns the results in the form of a data frame, which can be used for a variety of purposes.
df = pd.read_sql("""
	SELECT
	   Name,
	   TotalDue,
     $exNumericCol;
	FROM [MyBucket].[MyScope].[Customer];""", engine)
print(df)

Modifying Data

To insert new records into a table, create a new data frame, and define its fields accordingly. When that is done, call to_sql() on the data frame to perform the INSERT operation with the connector, as shown in the example below. You must set the "if _exists" argument to "append" to prevent Pandas from attempting building the table from scratch. To prevent Pandas from writing the data frame index as a column, set index=False.
df = pd.DataFrame({"Name": ["Jon Doe"], "TotalDue": ["John"]})
df.to_sql("[MyBucket].[MyScope].[Customer]", con=engine, if_exists="append", index=False)

CData Python Connector for Couchbase

From Matplotlib

Matplotlib contains a number of tools that can graphically model Couchbase data after being fed a data frame From Pandas.

Using PyPlot

Before any Matplotlib tool, such as pyplot, can be used, it must be imported:
from matplotlib import pyplot as plt

Once a Pandas data frame is obtained, it can be used to create a plot visualizing Couchbase data. For example, the following plot generates and displays a bar graph relating Name and AnnualRevenue values:

df.plot(kind="bar", x="Name", y=["AnnualRevenue"])
plt.show()

CData Python Connector for Couchbase

From Petl

The connector can be used to create ETL applications and pipelines for CSV data in Python using Petl.

Install Required Modules

Install the Petl modules using the pip utility.
pip install petl

Connecting

After you import the modules, including the CData Python Connector for Couchbase, you can use the connector's connect function to create a connection using a valid Couchbase connection string. If you prefer not to use a direct connection, you can use a SQLAlchemy engine.
import petl as etl
import cdata.couchbase as mod
cnxn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")

Extract, Transform, and Load the Couchbase Data

Create a SQL query string and store the query results in a DataFrame.
sql = "SELECT	Name, TotalDue FROM [MyBucket].[MyScope].[Customer] "
table1 = etl.fromdb(cnxn,sql)

Loading Data

With the query results stored in a DataFrame, you can load your data into any supported Petl destination. The following example loads the data into a CSV file.
etl.tocsv(table1,'output.csv')

Modifying Data

Insert new rows into Couchbase tables using Petl's appenddb function.
table1 = [['Name','TotalDue'],['Jon Doe','John']]
etl.appenddb(table1,cnxn,'[MyBucket].[MyScope].[Customer]')

CData Python Connector for Couchbase

Schema Discovery

The extension supports schema discovery by using SQL queries to available System Tables.

Using SQL

The following sections describe the discovery of metadata through several System Tables:

CData Python Connector for Couchbase

Tables and Views

The connector possesses system tables that are used to discover the tables and views available in the data model. Of these system tables, "sys_tables" and "sys_views" are used to fetch information about the available tables and views respectively:

Tables


import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tables"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Views


import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")
cur = conn.cursor()
cmd = "SELECT * FROM sys_views"
cur.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

CData Python Connector for Couchbase

Columns

The available columns for any given table are fetched from a system table called "sys_tablecolumns". A specific table name is provided in the WHERE criteria to restrict the table from which the column information is fetched:

import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tablecolumns WHERE TableName = '[MyBucket].[MyScope].[Customer]'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

CData Python Connector for Couchbase

Procedures

Procedures

A system table called "sys_procedures" is queried to obtain the available stored procedures that are executed:
import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedures"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Parameters

The input parameters of any stored procedure are similarly obtained from the "sys_procedureparameters" system table:
import cdata.couchbase as mod
conn = mod.connect("User='myusername';Password='mypassword';Server='http://couchbase40'")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'SelectEntries'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

CData Python Connector for Couchbase

Advanced Features

This section details a selection of advanced features of the Couchbase connector.

User Defined Views

The connector supports the use of user defined views, virtual tables whose contents are decided by a pre-configured user defined query. These views are useful when you cannot directly control queries being issued to the drivers. For an overview of creating and configuring custom views, see User Defined Views .

SSL Configuration

Use SSL Configuration to adjust how connector handles TLS/SSL certificate negotiations. You can choose from various certificate formats;. For further information, see the SSLServerCert property under "Connection String Options" .

Firewall and Proxy

Configure the connector for compliance with Firewall and Proxy, including Windows proxies and HTTP proxies. You can also set up tunnel connections.

Caching Data

Caching Data enables faster access to data and reduces the number of API calls, improving performance. The connector supports a simple caching model where multiple connections can also share the cache over time. When configuring the cache connection, you can specify automatic or explicit data caching.

Query Processing

The connector offloads as much of the SELECT statement processing as possible to Couchbase and then processes the rest of the query in memory (client-side).

For further information, see Query Processing.

Logging

For an overview of configuration settings that can be used to refine CData logging, see Logging. Only two connection properties are required for basic logging, but there are numerous features that support more refined logging, which enables you to use the LogModules connection property to specify subsets of information to be logged.

Exception Handling

For an overview of how exceptions are reported and the components of an exception, see Exception Handling.

CData Python Connector for Couchbase

User Defined Views

The CData Python Connector for Couchbase supports the use of user defined views: user-defined virtual tables whose contents are decided by a preconfigured query. User defined views are useful in situations where you cannot directly control the query being issued to the driver; for example, when using the driver from a tool.

Use a user defined view to define predicates that are always applied. If you specify additional predicates in the query to the view, they are combined with the query already defined as part of the view.

There are two ways to create user defined views:

  • Create a JSON-formatted configuration file defining the views you want.
  • DDL statements.

Defining Views Using a Configuration File

User defined views are defined in a JSON-formatted configuration file called UserDefinedViews.json. The connector automatically detects the views specified in this file.

You can also have multiple view definitions and control them using the UserDefinedViews connection property. When you use this property, only the specified views are seen by the connector.

This user defined view configuration file is formatted so that each root element defines the name of a view, and includes a child element, called query, which contains the custom SQL query for the view.

For example:

{
	"MyView": {
		"query": "SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE MyColumn = 'value'"
	},
	"MyView2": {
		"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
	}
}
Use the UserDefinedViews connection property to specify the location of your JSON configuration file. For example:
"UserDefinedViews", "C:\\Users\\yourusername\\Desktop\\tmp\\UserDefinedViews.json"

Defining Views Using DDL Statements

The connector is also capable of creating and altering the schema via DDL Statements such as CREATE LOCAL VIEW, ALTER LOCAL VIEW, and DROP LOCAL VIEW.

Create a View

To create a new view using DDL statements, provide the view name and query as follows:

CREATE LOCAL VIEW [MyViewName] AS SELECT * FROM Customers LIMIT 20;

If no JSON file exists, the above code creates one. The view is then created in the JSON configuration file and is now discoverable. The JSON file location is specified by the UserDefinedViews connection property.

Alter a View

To alter an existing view, provide the name of an existing view alongside the new query you would like to use instead:

ALTER LOCAL VIEW [MyViewName] AS SELECT * FROM Customers WHERE TimeModified > '3/1/2020';

The view is then updated in the JSON configuration file.

Drop a View

To drop an existing view, provide the name of an existing schema alongside the new query you would like to use instead.

DROP LOCAL VIEW [MyViewName]

This removes the view from the JSON configuration file. It can no longer be queried.

Schema for User Defined Views

In order to avoid a view's name clashing with an actual entity in the data model, user defined views are exposed in the UserViews schema by default. To change the name of the schema used for UserViews, reset the UserViewsSchemaName property.

Working with User Defined Views

For example, a SQL statement with a user defined view called UserViews.RCustomers only lists customers in Raleigh:
SELECT * FROM Customers WHERE City = 'Raleigh';
An example of a query to the driver:
SELECT * FROM UserViews.RCustomers WHERE Status = 'Active';
Resulting in the effective query to the source:
SELECT * FROM Customers WHERE City = 'Raleigh' AND Status = 'Active';
That is a very simple example of a query to a user defined view that is effectively a combination of the view query and the view definition. It is possible to compose these queries in much more complex patterns. All SQL operations are allowed in both queries and are combined when appropriate.

CData Python Connector for Couchbase

SSL Configuration

Customizing the SSL Configuration

By default, the connector attempts to negotiate TLS with the server. The server certificate is validated against the default system trusted certificate store. You can override how the certificate gets validated using the SSLServerCert connection property.

To specify another certificate, see the SSLServerCert connection property.

Client SSL Certificates

The Couchbase connector also supports setting client certificates. Set the following to connect using a client certificate.

CData Python Connector for Couchbase

Firewall and Proxy

Connecting Through a Firewall or Proxy

HTTP Proxies

Note: The connector uses the system proxy settings by default, without further configuration needed. If you want to connect to other proxies, set ProxyAutoDetect to False and read further.

To authenticate to an HTTP proxy, set the following:

  • ProxyServer: the hostname or IP address of the proxy server that you want to route HTTP traffic through.
  • ProxyPort: the TCP port that the proxy server is running on.
  • ProxyAuthScheme: the authentication method the connector uses when authenticating to the proxy server.
  • ProxyUser: the username of a user account registered with the proxy server.
  • ProxyPassword: the password associated with the ProxyUser.

Other Proxies

Set the following properties:

CData Python Connector for Couchbase

Caching Data

Caching Data

Caching data provides several benefits, including faster access to data and reducing the number of API calls, which improve performance. The connector supports a simple caching model where multiple connections can also share the cache over time. You can enable and configure caching features by setting the necessary connection properties.

Contents

The sections in this chapter detail the connector's caching functionality and link to the corresponding connection properties, as well as SQL statements.

Configuring the Cache Connection

Configuring the Cache Connection describes the properties that you can set when configuring the cache database.

Caching Metadata

Caching Metadata describes the CacheMetadata property. This property determines whether or not to cache the table metadata to a file store.

Automatically Caching Data

Automatically Caching Data describes how the connector automatically refreshes the cache when the AutoCache property is set.

Explicitly Caching Data

Explicitly Caching Data describes how you can decide what data is stored in the cache and when it is updated.

Data Type Mapping

Data Type Mapping shows the mappings between the data types configured in the schema and the data types in the database.

CData Python Connector for Couchbase

Configuring the Cache Connection

Configuring the Caching Database

This section describes the properties for caching data to the persistent store of your choice.

CacheLocation

The CacheLocation property species the path to a file-system-based database. When caching is enabled, a file-system-based database is used by default. If CacheLocation is not specified, this database is stored at the path in Location. If neither of these connection properties are specified, the connector uses a platform-dependent default location.

CacheConnection

The CacheConnection property specifies a database driver and the connection string to the caching database.

CacheDriver and CacheProvider

Both the CacheDriver and CacheProvider properties are supported. Each specifies a database driver and the connection string to the caching database. CacheDriver is designed for Linux and MacOS; CacheProvider is Windows-based.

CData Python Connector for Couchbase

Caching Metadata

This section describes how to enable caching metadata and how to update the metadata cache.

Before being able to query data, the connector requires relevant metadata to be retrieved. By default, metadata is cached in memory and shared across connections. But if you want to persist across processes, or if metadata requests are expensive, the solution is to cache the metadata to disk.

Enable Caching Metadata

To enable caching of metadata, set CacheMetadata = true and see Configuring the Cache Connection for instructions on how to configure your connection string. The connector caches the metadata the first time it is needed and uses the metadata cache for subsequent requests.

Update the Metadata Cache

Because metadata is cached, changes to metadata on the live source, for example, adding or removing a column or attribute, are not automatically reflected in the metadata cache. To get updates to the live metadata, you need to delete or drop the cached data.

CData Python Connector for Couchbase

Automatically Caching Data

Automatically caching data is useful when you do not want to rebuild the cache for each query. When you query data for the first time, the connector automatically initializes and builds a cache in the background. When AutoCache = true, the connector uses the cache for subsequent query executions, resulting in faster response times.

Configuring Automatic Caching

Caching the [MyBucket].[MyScope].[Customer] Table

The following example caches the [MyBucket].[MyScope].[Customer] table in the file specified by the CacheLocation property of the connection string.

SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'

Common Use Case

A common use for automatically caching data is to improve driver performance when making repeated requests to a live data source, such as building a report or creating a visualization. With auto caching enabled, repeated requests to the same data may be executed in a short period of time, but within an allowable tolerance (CacheTolerance) of what is considered "live" data.

CData Python Connector for Couchbase

Explicitly Caching Data

With explicit caching (AutoCache = false), you decide exactly what data is cached and when to query the cache instead of the live data. Explicit caching gives you full control over the cache contents by using CACHE Statements. This section describes some strategies to use the caching features offered by the connector.

Creating the Cache

To load data in the cache, issue the following statement.

CACHE SELECT * FROM tableName WHERE ...

Once the statement is issued, any matching data in tableName is loaded into the corresponding table.

Updating the Cache

This section describes two ways to update the cache.

Updating with the SELECT Statement

The following example shows a statement that can update modified rows and add missing rows in the cached table. However, this statement does not delete extra rows that are already in the cache. This statement only merges the new rows or updates the existing rows.

CACHE SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'

Updating with the TRUNCATE Statement

The following example shows a statement that can update modified rows and add missing rows in the cached table. This statement can also delete rows in the cache table that are not present in the live data source.

  CACHE WITH TRUNCATE SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'
  

Query the Data in Online or Offline Mode

This section describes how to query the data in online or offline mode.

Online: Select Cached Tables

You can use the tableName#CACHE syntax to explicitly execute queries to the cache while still online, as shown in the following example.

SELECT * FROM [MyBucket].[MyScope].[Customer]#CACHE

Offline: Select Cached Tables

With Offline = true, SELECT statements always execute against the local cache database, regardless of whether you explicitly specify the cached table or not. Modification of the cache is disabled in Offline mode to prevent accidentally updating only the cached data. Executing a DELETE/UPDATE/INSERT statement while in Offline mode results in an exception.

The following example selects from the local cache but not the live data source because Offline = true.

SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId='12345' ORDER BY TotalDue ASC

Delete Data from the Cache

You can delete data from the cache by building a direct connection to the database. Note that the connector does not support manually deleting data from the cache.

Common Use Case

A common use for caching is to have an application always query the cached data and only update the cache at set intervals, such as once every day or every two hours. There are two ways in which this can be implemented:

  • AutoCache = false and Offline = false. All queries issued by the application explicitly reference the tableName#CACHE table. When the cache needs to be updated, the application executes a tableName#CACHE ... statement to bring the cached data up to date.
  • Offline = true. Caching is transparent to the application. All queries are executed against the table as normal, so most application code does not need to be aware that caching is done. To update the cached data, simply create a separate connection with Offline = false and execute a tableName#CACHE ... statement.

CData Python Connector for Couchbase

Data Type Mapping

The connector maps types from the data source to the corresponding data type available in the chosen cache database. The following table shows the mappings between the data types configured in the schema and the data types in the database. Some schema types have synonyms which are all listed in the Schema column.

Data Type Mapping

Note: String columns can map to different data types depending on their length.

Schema .NET JDBC SQL Server Derby MySQL Oracle SQLite Access
int, integer, int32 Int32 int int INTEGER INT NUMBER integer LONG
smallint, short, int16 Int16 short smallint SMALLINT SMALLINT NUMBER integer SHORT
double, float, real Double double float DOUBLE DOUBLE NUMBER double DOUBLE
date DateTime java.sql.Date date DATE DATE DATE date DATETIME
datetime, timestamp DateTime java.sql.Date datetime TIMESTAMP DATETIME TIMESTAMP datetime DATETIME
time, timespan TimeSpan java.sql.Time time TIME TIME TIMESTAMP datetime DATETIME
string, varchar String java.lang.String If length > 4000: nvarchar(max), Otherwise: nvarchar(length)If length > 32672: LONG VARCHAR, Otherwise VARCHAR(length)If length > 255: LONGTEXT, Otherwise: VARCHAR(length)If length > 4000: CLOB, Otherwise: VARCHAR2(length)nvarchar(length)If length > 255: LONGTEXT, Otherwise: VARCHAR(length)
long, int64, bigint Int64 long bigint BIGINT BIGINT NUMBER bigint LONG
boolean, bool Boolean boolean tinyint SMALLINT BIT NUMBER tinyint BIT
decimal, numeric Decimal java.math.BigDecimal decimal DECIMAL DECIMAL DECIMAL decimal CURRENCY
uuid Guid java.util.UUID nvarchar(length) VARCHAR(length)VARCHAR(length) VARCHAR2(length)nvarchar(length) VARCHAR(length)
binary, varbinary, longvarbinary byte[] byte[] binary(1000) or varbinary(max) after SQL Server 2000, image otherwise BLOB LONGBLOB BLOB BLOB LONGBINARY

CData Python Connector for Couchbase

Query Processing

Query Processing

CData has a client-side SQL engine built into the connector library. This enables support for the full capabilities that SQL-92 offers, including filters, aggregations, functions, etc.

For sources that do not support SQL-92, the connector offloads as much of SQL statement processing as possible to Couchbase and then processes the rest of the query in memory (client-side). This results in optimal performance.

For data sources with limited query capabilities, the connector handles transformations of the SQL query to make it simpler for the connector. The goal is to make smart decisions based on the query capabilities of the data source to push down as much of the computation as possible. The Couchbase Query Evaluation component examines SQL queries and returns information indicating what parts of the query the connector is not capable of executing natively.

The Couchbase Query Slicer component is used in more specific cases to separate a single query into multiple independent queries. The client-side Query Engine makes decisions about simplifying queries, breaking queries into multiple queries, and pushing down or computing aggregations on the client-side while minimizing the size of the result set.

There's a significant trade-off in evaluating queries, even partially, client-side. There are always queries that are impossible to execute efficiently in this model, and some can be particularly expensive to compute in this manner. CData always pushes down as much of the query as is feasible for the data source to generate the most efficient query possible and provide the most flexible query capabilities.

More Information

For a full discussion of how CData handles query processing, see CData Architecture: Query Execution.

CData Python Connector for Couchbase

Logging

Logging

Capturing connector logging can be very helpful when diagnosing error messages or other unexpected behavior.

Basic Logging

To begin capturing connector logging, set these properties:

  • Logfile: A filepath that designates the name and location of the log file.
  • Verbosity: A numerical value (1-5) that determines the amount of detail in the log. See the page in the Connection Properties section for an explanation of the five levels.
  • MaxLogFileSize: When the limit is hit, a new log is created in the same folder with the date and time appended to the end. The default limit is 100 MB. Values lower than 100 kB will use 100 kB as the value instead.
  • MaxLogFileCount: A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted. Minimum supported value is 2. A value of 0 or a negative value indicates no limit on the count.

Once these properties are set, the connector populates the log file as it carries out various tasks, such as when authentication is performed or queries are executed. If the specified file doesn't already exist, it is created.

Log Verbosity

The verbosity level determines the amount of detail that the connector reports to the Logfile. Supported Verbosity levels range from 1 to 5.

The following list describes each level:

1Setting Verbosity to 1 logs the query, the number of rows returned by it, the start of execution and the time taken, and any errors.
2Setting Verbosity to 2 logs everything included in Verbosity 1, cache queries, and additional information about the request.
3Setting Verbosity to 3 also logs HTTP headers, as well as the body of the request and the response.
4Setting Verbosity to 4 also logs transport-level communication with the data source. This includes SSL negotiation.
5Setting Verbosity to 5 also logs communication with the data source and additional details that may be helpful in troubleshooting problems. This includes interface commands.

For normal operations, Verbosity should not be set to greater than 1. At higher verbosities you can log substantial amounts of data, which can delay execution times.

To refine the logged content further by showing/hiding specific categories of information, see LogModules.

Sensitive Data

Verbosity levels of 3 and higher may capture information that you do not want shared outside of your organization. The following lists information of concern for each level:

  • Verbosity 3: The full body of the request and the response, which includes all the data returned by the connector
  • Verbosity 4: SSL certificates
  • Verbosity 5: Any extra transfer data not included at Verbosity 3, such as non human-readable binary transfer data

Note: Although we mask sensitive values, such as passwords, in the connection string and any request in the log, it is always best practice to review the logs for any sensitive information before sharing outside your organization.

Advanced Logging

You may want to refine the exact information that is recorded to the log file. This can be accomplished using the LogModules property. This property allows you to filter the logging using a semicolon-separated list of logging modules.

Example property value:

LogModules=INFO;EXEC;SSL;SQL;META;

Note that the logfile filtering triggered by the Verbosity connection property takes precedence over the filtering imposed by this connection property. This means that operations of a higher verbosity level than the level specified in the Verbosity connection property are not printed in the logfile, even if they belong to one of the modules specified in this connection property.

The available modules and submodules are:

Module Name Module Description Submodules
INFO General Information. Includes the connection string, product version (build number), and initial connection messages.
  • Connec – Information related to creating or destroying connections.
  • Messag – Generic label for messages pertaining to connections, the connection string, and product version. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
EXEC Query Execution. Includes execution messages for user-written SQL queries, parsed SQL queries, and normalized SQL queries. Success/failure messages for queries and query pages appear here as well.
  • Messag – Messages pertaining to query execution. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • Normlz – Query normalization steps. Query normalization is when the product takes the user-submitted query and rewrites the query to get the same results with optimal performance.
  • Origin – This label applies to any messages recording a user's original query (the exact, unaltered, non-normalized query executed by the user).
  • Page – Messages related to query paging.
  • Parsed – Query parsing steps. Parsing is the process of converting the user-submitted query into a standardized format for easier processing.
HTTP HTTP protocol messages. Includes HTTP requests/responses (including POST messages), as well as Kerberos related messages.
  • KERB – HTTP requests related to Kerberos.
  • Messag – Messages pertaining to HTTP protocols. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • Unpack – This label applies to messages about zipped data being returned from the service API and unpacked by the product.
  • Res – Messages containing HTTP responses.
  • Req – Messages containing HTTP requests.
WSDL Messages pertaining to the generation of WSDL/XSD files.
SSL SSL certificate messages.
  • Certif – Messages pertaining to SSL certificates.
AUTH Authentication related failure/success messages.
  • Messag – Messages pertaining to authentication. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • OAuth – Messages related to OAuth authentication.
  • Krbros – Kerberos-related authentication messages.
SQL Includes SQL transactions, SQL bulk transfer messages, and SQL result set messages.
  • Bulk – Messages pertaining to bulk query execution.
  • Cache – Messages related to reading row data from and writing row data to the product's cache for better performance.
  • Messag – Messages pertaining to SQL transactions. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • ResSet – Query resultsets.
  • Transc – Messages related to handling transactions, including information about the number of jobs executed and backup table handling.
META Metadata cache and schema messages.
  • Cache – Messages related to reading from and modifying column and table definitions in the product's cache for better performance.
  • Schema – Messages related to retrieving metadata from or modifying the service schema.
  • MemSto – Messages related to writing to or reading from in-memory metadata cache.
  • Storag – Messages relating to storing metadata on disk or in an external data store, rather than in memory.
FUNC Information related to executing SQL functions.
  • Errmsg – Error messages related to executing SQL functions.
TCP Incoming and outgoing raw bytes on TCP transport layer messages.
  • Send – Raw data sent via the TCP protocol.
  • Receiv – Raw data received via the TCP protocol.
FTP Messages pertaining to the File Transfer Protocol.
  • Info – Status messages related to communication in the FTP protocol.
  • Client – Messages related to actions taken by the FTP client (the product) during FTP communication.
  • Server – Messages related to actions taken by the FTP server during FTP communication.
SFTP Messages pertaining to the Secure File Transfer Protocol.
  • Info – Status messages related to communication in the SFTP protocol.
  • To_Server – Messages related to actions taken by the SFTP client (the product) during SFTP communication.
  • From_Server – Messages related to actions taken by the SFTP server during SFTP communication.
POP Messages pertaining to data transferred via the Post Office Protocol.
  • Client – Messages related to actions taken by the POP client (the product) during POP communication.
  • Server – Messages related to actions taken by the POP server during POP communication.
  • Status – Status messages related to communication in the POP protocol.
SMTP Messages pertaining to data transferred via the Simple Mail Transfer Protocol.
  • Client – Messages related to actions taken by the SMTP client (the product) during SMTP communication.
  • Server – Messages related to actions taken by the SMTP server during SMTP communication.
  • Status – Status messages related to communication in the SMTP protocol.
CORE Messages relating to various internal product operations not covered by other modules.
DEMN Messages related to SQL remoting.
CLJB Messages about bulk data uploads (cloud job).
  • Commit – Submissions for bulk data uploads.
SRCE Miscellaneous messages produced by the product that don't belong in any other module.
TRANCE Advanced messages concerning low-level product operations.
CBAS Applies to log messages generated from the Couchbase protocol.

CData Python Connector for Couchbase

Exception Handling

Exception Handling

Exceptions can be surfaced from either the API or the CData Python Connector for Couchbase. Each exception will have an error code, an error message, and a SQL state.

Error Codes

The error code classifies the type of error.

0 NONE Used for unclassified errors and internally handled errors. This code also covers data source-specific errors that do not fit in any specific category.
65537 TCP_UNKNOWN_HOST Unable to resolve a hostname (DNS failure).
65538 TCP_CONNECTION_REFUSED Could not connect to the remote port.
65539 TCP_AUTH_FAILED Login failed when using a binary authentication protocol. Use this for auth errors when the protocol is not HTTP (LDAP, SASL, Kerberos, ...).
65540 TCP_TIMEOUT Did not receive a response after sending a request to the server.
65541 TCP_PROTOCOL For wire protocol drivers. Either the server sent a bad packet that we are unable to process, or we cannot construct a packet to send.
131073 TLS_SERVER_UNTRUSTED Could not verify SSL server certificate.
131074 TLS_CLIENT_UNTRUSTED Server did not accept the client certificate we sent.
196609 OAUTH_DECRYPT_FAILED OAuthEncryptKey did not decrypt the OAuthSettings file.
196610 OAUTH_MISSING_CLIENT_INFO OAuthClientId / OAuthClientSecret / OAuthJWTCert is missing.
196611 OAUTH_MISSING_PROP General OAuth property missing. OAUTH_MISSING_CLIENT_INFO is used for missing client ID/secret and JWT cert.
196612 OAUTH_NO_ACCESS_TOKEN Unable to retrieve access token. Only use this when getting a token in GetOAuthAccessToken / RefreshOAuthAccessToken.
196613 OAUTH_TOKEN_EXPIRED The access token expired. Normally used with a RefreshOAuth/OAuthException behavior.
196614 OAUTH_INVALID_PROP OAuth property has an invalid value. OAUTH_MISSING_CLIENT_INFO / OAUTH_MISSING_PROP is used if the value is not set.
262145 HTTP_REQUEST_TIMEOUT Did not receive a response from the HTTP server.
262146 HTTP_CLIENT_ERROR Generic HTTP 4xx error. Only use for 4xx errors not covered by other codes.
262147 HTTP_AUTH_FAILED HTTP 401 error.
262148 HTTP_LIMIT_EXCEEDED HTTP 429 error.
262149 HTTP_SERVER_ERROR HTTP 5xx error.
262150 HTTP_NOT_FOUND_ERROR HTTP 404 error.
327681 CORE_TIMEOUT General timeout. Not related to a specific network request.
327682 CORE_OP_NOT_ALLOWED Operation blocked by provider permissions.
327683 CORE_CONNECTION_CONFIG Connection configuration is not valid.
327684 CORE_SERIALIZE Failed to encode data into a specific format (XML, JSON, CSV, ...).
327685 CORE_DESERIALIZE Failed to decode data from a specific format (XML, JSON, CSV, ...).
393217 SQL_SYNTAX_ERROR Unable to parse a SQL query.
393218 SQL_MISSING_COLUMNS Query did not include required columns.
393219 SQL_MISSING_PARAMS Stored procedure call did not include required parameters.
393220 SQL_QUERY_NOT_SUPPORTED A part of the query is not allowed in the current context.
458753 SSH_SERVER_UNTRUSTED Could not verify SSH server.
524289 STORAGE_LIST_EXCEPTION Issue listing storage resources.
524290 STORAGE_RESOURCE_NOT_FOUND Issue finding storage resources.
524291 STORAGE_ROOT_RESOURCE_NOT_FOUND The root resource (bucket/share/drive) was not found; cannot create it in flat file drivers.
524292 STORAGE_RESOURCE_NOT_A_DIRECTORY Storage resource is not a directory.
524293 STORAGE_RESOURCE_NOT_A_FILE Storage resource is not a file.
524294 STORAGE_PERMISSIONS_DENIED Storage permissions denied.

SQL State

The SQL state is used when throwing generic provider errors to the wrapper and indicates the success or failure of a call.

Some of the common SQL states are listed below:

07007 REQUIRED_CLAUSE Class Code 07: Dynamic SQL Error.
08001 OPEN_CONNECTION Class Code 08: Connection Exception. The connection was unable to be established to the application server or other server.
08004 REJECT_CONNECTION The application server rejected establishment of the connection.
42501 PRIVILEGE_IDENTIFIED_OBJECT Class Code 42: Syntax Error or Access Rule Violation. The authorization ID does not have the privilege to perform the specified operation on the identified object.
42506 AUTH_FAILED Owner authorization failure occurred.
42601 SQL_SYNTAX A character, token, or clause is invalid or missing.

Error Message

The error message provides more detailed reasoning about why the error occurred. It provides an explanation of the issue, and may include steps on how to resolve it.

CData Python Connector for Couchbase

SQL Compliance

The CData Python Connector for Couchbase supports several operations on data, including querying, deleting, modifying, and inserting.

SELECT Statements

See SELECT Statements for a syntax reference and examples.

See Data Model for information on the capabilities of the Couchbase API.

INSERT Statements

See INSERT Statements for a syntax reference and examples.

UPDATE Statements

The primary key Id is required to update a record. See UPDATE Statements for a syntax reference and examples.

UPSERT Statements

An UPSERT updates a record if it exists and inserts the record if it does not. See UPSERT Statements for a syntax reference and examples.

DELETE Statements

The primary key Id is required to delete a record. See DELETE Statements for a syntax reference and examples.

CACHE Statements

CACHE statements allow granular control over the connector's caching functionality. For a syntax reference and examples, see CACHE Statements.

For more information on the caching feature, see Caching Data.

EXECUTE Statements

Use EXECUTE or EXEC statements to execute stored procedures. See EXECUTE Statements for a syntax reference and examples.

Names and Quoting

  • Table and column names are considered identifier names; as such, they are restricted to the following characters: [A-Z, a-z, 0-9, _:@].
  • To use a table or column name with characters not listed above, the name must be quoted using square brackets ([name]) in any SQL statement.
  • Parameter names can optionally start with the @ symbol (e.g., @p1 or @CustomerName) and cannot be quoted.
  • Strings must be quoted using single quotes (e.g., 'John Doe').

Transactions and Batching

Transactions are not currently supported.

Additionally, the connector does not support batching of SQL statements. To execute multiple commands, you can create multiple instances and execute each separately.

CData Python Connector for Couchbase

SQL Functions

The connector provides functions that are similar to those that are available with most standard databases. These functions are implemented in the CData provider engine and thus are available across all data sources with the same consistent API. Three categories of functions are available: string, date, and math.

The connector interprets all SQL function inputs as either strings or column identifiers, so you need to escape all literals as strings, with single quotes. For example, contrast the SQL Server syntax and connector syntax for the DATENAME function:

  • SQL Server:
    SELECT DATENAME(yy,GETDATE())
  • connector:
    SELECT DATENAME('yy',GETDATE())

String Functions

These functions perform string manipulations and return a string value. See STRING Functions for more details.

Date Functions

These functions perform date and date time manipulations. See DATE Functions for more details.

Math Functions

These functions provide mathematical operations. See MATH Functions for more details.

Projection Functions

These functions can be used to refine projections in your SQL query. See Projection Functions for more details.

Predicate Functions

These functions can be used to specify criteria in the WHERE clause of your SQL query. See Predicate Functions for more details.

CData Python Connector for Couchbase

STRING Functions

ASCII(character_expression)

Returns the ASCII code value of the left-most character of the character expression.

  • character_expression: The character expression.

                      SELECT ASCII('0');
                      --  Result: 48
                    

BASE64_ENCODE(input_binary)

Returns the Base64-encoded string form of a binary input.

  • input_binary: The binary value to encode.

                        SELECT BASE64_ENCODE(BinaryData);
                    -- Result: 'QmFzZTY0RW5jb2RlZA=='
                    

BASE64_DECODE(input_string)

Returns the binary result of decoding a Base64-encoded string.

  • input_string: The Base64-encoded string.

                        SELECT BASE64_DECODE('QmFzZTY0RW5jb2RlZA==');
                    -- Result: (binary output)
                    

CHAR(integer_expression)

Converts the integer ASCII code to the corresponding character.

  • integer_expression: The integer from 0 through 255.

                      SELECT CHAR(48);
                      -- Result: '0'
                    

CHARINDEX(expressionToFind ,expressionToSearch [,start_location ])

Returns the starting position of the specified expression in the character string.

  • expressionToFind: The character expression to find.
  • expressionToSearch: The character expression, typically a column, to search.
  • start_location: An optional character position to start searching for expressionToFind in expressionToSearch.

                      SELECT CHARINDEX('456', '0123456');
                      -- Result: 4

                      SELECT CHARINDEX('456', '0123456', 5);
                      -- Result: -1
                    

CHAR_LENGTH(character_expression),

Returns the number of UTF-8 characters present in the expression.

  • character_expression: The set of characters to be evaluated for length.

				 SELECT CHAR_LENGTH('sample text') FROM Account LIMIT 1
				 -- Result: 11			
				

CONCAT(string_value1, string_value2, ..., string_valueN)

Returns the string that is the concatenation of two or more string values.

  • string_value1: The first string to be concatenated.
  • string_value2: The second string to be concatenated.
  • string_valueN: (optional) Any additional strings to be concatenated.

                      SELECT CONCAT('Hello, ', 'world!');
                      -- Result: 'Hello, world!'
                    

CONTAINS(expressionToSearch, expressionToFind)

Returns 1 if expressionToFind is found within expressionToSearch; otherwise, 0.

  • expressionToSearch: The character expression, typically a column, to search.
  • expressionToFind: The character expression to find.

                      SELECT CONTAINS('0123456', '456');
                      -- Result: 1

                      SELECT CONTAINS('0123456', 'Not a number');
                      -- Result: 0
                    

ENDSWITH(character_expression, character_suffix)

Returns 1 if character_expression ends with character_suffix; otherwise, 0.

  • character_expression: The character expression.
  • character_suffix: The character suffix to search for.

                      SELECT ENDSWITH('0123456', '456');
                      -- Result: 1

                      SELECT ENDSWITH('0123456', '012');
                      -- Result: 0
                    

FILESIZE(uri)

Returns the number of bytes present in the file at the specified file path.

  • uri: The path of the file from which to read the size.

				SELECT FILESIZE('C:/Users/User1/Desktop/myfile.txt');
				-- Result: 23684
				

FORMAT(value [, parseFormat], format )

Returns the value formatted with the specified format.

  • value: The string to format.
  • format: The string specifying the output syntax of the date or numeric format.
  • parseFormat: The string specifying the input syntax of the date value. Not applicable to numeric types.

                      SELECT FORMAT(12.34, '#');
                      -- Result: 12

                      SELECT FORMAT(12.34, '#.###');
                      -- Result: 12.34

                      SELECT FORMAT(1234, '0.000E0');
                      -- Result: 1.234E3
                      
                      SELECT FORMAT('2019/01/01', 'yyyy-MM-dd');
                      -- Result: 2019-01-01
                      
                      SELECT FORMAT('20190101', 'yyyyMMdd', 'yyyy-MM-dd');
                      -- Result: '2019-01-01'
                    

HASHBYTES(algorithm, value)

Returns the hash of the input value as a byte array using the given algorithm. The supported algorithms are MD5, SHA1, SHA2_256, SHA2_512, SHA3_224, SHA3_256, SHA3_384, and SHA3_512.

  • algorithm: The algorithm to use for hashing. Must be one of MD5, SHA1, SHA2_256, SHA2_512, SHA3_224, SHA3_256, SHA3_384, or SHA3_512.
  • value: The value to hash. Must be either a string or byte array.

                      SELECT HASHBYTES('MD5', 'Test');
                      -- Result (byte array): 0x0CBC6611F5540BD0809A388DC95A615B
                    

INDEXOF(expressionToSearch, expressionToFind [,start_location ])

Returns the starting position of the specified expression in the character string.

  • expressionToSearch: The character expression, typically a column, to search.
  • expressionToFind: The character expression to find.
  • start_location: An optional character position to start searching for expressionToFind in expressionToSearch.

                      SELECT INDEXOF('0123456', '456');
                      -- Result: 4

                      SELECT INDEXOF('0123456', '456', 5);
                      -- Result: -1
                    

ISALPHABETIC(character_expression)

Returns 1 if the character expression consists only of alphabetic characters; otherwise, 0.

  • character_expression: The string expression to evaluate.

                      SELECT ISALPHABETIC('Hello');
                      -- Result: 1

                      SELECT ISALPHABETIC('Hello123');
                      -- Result: 0

                      SELECT ISALPHABETIC('Hello!');
                      -- Result: 0
                    

ISALPHANUMERIC(character_expression)

Returns 1 if the character expression consists only of alphabetic and numeric characters; otherwise, 0.

  • character_expression: The string expression to evaluate.

                      SELECT ISALPHANUMERIC('Hello123');
                      -- Result: 1

                      SELECT ISALPHANUMERIC('123');
                      -- Result: 1

                      SELECT ISALPHANUMERIC('Hello.123');
                      -- Result: 0
                    

ISNUMERIC(character_expression)

Returns 1 if the character expression consists only of numeric digits and up to one decimal point; otherwise, 0.

  • character_expression: The string expression to evaluate.

                      SELECT ISNUMERIC('123');
                      -- Result: 1

                      SELECT ISNUMERIC('123.45');
                      -- Result: 1

                      SELECT ISNUMERIC('123.45.67');
                      -- Result: 0

                      SELECT ISNUMERIC('12a3');
                      -- Result: 0
                    

JSON_EXTRACT(json, jsonpath)

Selects any value in a JSON array or object. The path to the array is specified in the jsonpath argument. Return value is numeric or null.

  • json: The JSON document to extract.
  • jsonpath: The XPath used to select the nodes. The JSONPath must be a string constant. The values of the nodes selected will be returned in a token-separated list.

                      SELECT JSON_EXTRACT('{"test": {"data": 1}}', '$.test');
                      -- Result: '{"data":1}'

                      SELECT JSON_EXTRACT('{"test": {"data": 1}}', '$.test.data');
                      -- Result: 1

                      SELECT JSON_EXTRACT('{"test": {"data": [1, 2, 3]}}', '$.test.data[1]');
                      -- Result: 2
                    

LEFT ( character_expression , integer_expression )

Returns the specified number of characters counting from the left of the specified string.

  • character_expression: The character expression.
  • integer_expression: The positive integer that specifies how many characters will be returned counting from the left of character_expression.

                      SELECT LEFT('1234567890', 3);
                      -- Result: '123'
                    

LEN(string_expression)

Returns the number of characters of the specified string expression.

  • string_expression: The string expression.

                      SELECT LEN('12345');
                      -- Result: 5
                    

LOCATE(substring,string)

Returns an integer representing how many characters into the string the substring appears.

  • substring: The substring to find inside larger string.
  • string: The larger string that is searched for the substring.
  • start locations: An optional integer that sets the character position (offset) from which to start searching.

				SELECT LOCATE('sample','XXXXXsampleXXXXX');
				-- Result: 6

                SELECT LOCATE('sample', 'XXXXXsampleXXXXX', 7)
                -- Result: 0
				

LOWER ( character_expression )

Returns the character expression with the uppercase character data converted to lowercase.

  • character_expression: The character expression.

                      SELECT LOWER('MIXED case');
                      -- Result: 'mixed case'
                    

LTRIM(character_expression)

Returns the character expression with leading blanks removed.

  • character_expression: The character expression.

                      SELECT LTRIM('     trimmed');
                      -- Result: 'trimmed'
                    

MASK(string_expression, mask_character [, start_index [, end_index ]])

Replaces the characters between start_index and end_index with the mask_character within the string.

  • string_expression: The string expression to be searched.
  • mask_character: The character to mask with.
  • start_index: The optional number of characters to leave unmasked at beginning of string. Defaults to 0.
  • end_index: The optional number of characters to leave unmasked at end of string. Defaults to 0.

                        SELECT MASK('1234567890','*',);
                        -- Result: '**********'
                        SELECT MASK('1234567890','*', 4);
                        -- Result: '1234******'
                        SELECT MASK('1234567890','*', 4, 2);
                        -- Result: '1234****90'  
                    

NCHAR(integer_expression)

Returns the Unicode character with the specified integer code as defined by the Unicode standard.

  • integer_expression: The integer from 0 through 65535 (0 through xFFFF).

OCTET_LENGTH(character_expression),

Returns the number of bytes present in the expression.

  • character_expression: The set of characters to be be evaluated.

				 SELECT OCTET_LENGTH('text') FROM Account LIMIT 1
				 -- Result: 4
				

PATINDEX(pattern, expression)

Returns the starting position of the first occurrence of the pattern in the expression. Returns 0 if the pattern is not found.

  • pattern: The character expression that contains the sequence to be found. The wild-card character % can be used only at the start or end of the expression.
  • expression: The expression, typically a column, to search for the pattern.

                      SELECT PATINDEX('123%', '1234567890');
                      -- Result: 1

                      SELECT PATINDEX('%890', '1234567890');
                      -- Result: 8

                      SELECT PATINDEX('%456%', '1234567890');
                      -- Result: 4
                    

POSITION(expressionToFind IN expressionToSearch)

Returns the starting position of the specified expression in the character string.

  • expressionToFind: The character expression to find.
  • expressionToSearch: The character expression, typically a column, to search.

                      SELECT POSITION('456' IN '123456');
                      -- Result: 4

                      SELECT POSITION('x' IN '123456');
                      -- Result: 0
                    

QUOTENAME(character_string [, quote_character])

Returns a valid SQL Server-delimited identifier by adding the necessary delimiters to the specified Unicode string.

  • character_string: The string of Unicode character data. The string is limited to 128 characters. Inputs greater than 128 characters return null.
  • quote_character: An optional single character to be used as the delimiter. These include:
    • a single quotation mark (')
    • a left or right bracket ([])
    • a double quotation mark (")
    • a left or right parenthesis ( () )
    • a greater or less than sign (><)
    • a left or right brace ({})
    • a backtick (`)

    If quote_character is not specified brackets are used. If an unacceptable character is supplied, it returns NULL.


                      SELECT QUOTENAME('table_name');
                      -- Result: '[table_name]'

                      SELECT QUOTENAME('table_name', '"');
                      -- Result: '"table_name"'

                      SELECT QUOTENAME('table_name', '[');
                      -- Result: '[table_name]'
                    

REGEXP_REPLACE(expr, pattern [, replacement [, position [, occurrence [, match_type]]]])

Replaces occurrences of a regular expression pattern in the input string with a specified value and returns the resulting string.

  • expr: The string expression to be searched.
  • pattern: The regular expression pattern to match.
  • replacement: (optional) The string to replace each matched occurrence of pattern with. Supports backreferences \1 through \9 and escape sequences \n, \r, \t, and \\. By default, this argument is an empty string, meaning matched portions are removed from the output string.
  • position: (optional) The 1-based starting position used when searching for regular expression matches in expr. The default is 1. All characters prior to the starting position are included in the output string unaltered. Skipped characters are ignored when calculating regular expression matches, even if they match pattern.
  • occurrence: (optional) Specifies whether all occurrences of pattern,, or only a specific occurrence of pattern are replaced. The default is 0, which means all occurrences of pattern are replaced with replacement. Set to 1 to only replace the first instance of the pattern; 2 to replace the second; etc.
  • match_type: (optional) Modifiers used to customize matching behavior. Supported values are: 'c' (case-sensitive, default), 'i' (case-insensitive), 'm' (multiline), 'n' (dot matches newline), 'x' (extended mode). These can be freely combined by including the letters back to back. For example, 'im' applies the functionality of both 'i' and 'm'. The regular expression syntax used is that of the Extended mode ('x') ignores whitespace and allows inline comments. If the pattern needs to match a literal space, it must be explicitly escaped.

                      SELECT REGEXP_REPLACE('abc123def456', '\d+', 'NUM');
                      -- Result: 'abcNUMdefNUM'

                      SELECT REGEXP_REPLACE('Hello\nHELLO\nhello', '^hello', 'X', 1, 0, 'im');
                      -- Result: 'X\nX\nX'
                    

REPLACE(string_expression, string_pattern, string_replacement)

Replaces all occurrences of a string with another string.

  • string_expression: The string expression to be searched. This can be a character or binary data type.
  • string_pattern: The substring to be found. Cannot be an empty string.
  • string_replacement: The replacement string.

                      SELECT REPLACE('1234567890', '456', '|');
                      -- Result: '123|7890'

                      SELECT REPLACE('123123123', '123', '.');
                      -- Result: '...'

                      SELECT REPLACE('1234567890', 'a', 'b');
                      -- Result: '1234567890'
                    

REPLICATE ( string_expression ,integer_expression )

Repeats the string value the specified number of times.

  • string_expression: The string to replicate.
  • integer_expression: The repeat count.

                      SELECT REPLACE('x', 5);
                      -- Result: 'xxxxx'
                    

REVERSE ( string_expression )

Returns the reverse order of the string expression.

  • string_expression: The string.

                      SELECT REVERSE('1234567890');
                      -- Result: '0987654321'
                    

RIGHT ( character_expression , integer_expression )

Returns the right part of the string with the specified number of characters.

  • character_expression: The character expression.
  • integer_expression: The positive integer that specifies how many characters of the character expression will be returned.

                      SELECT RIGHT('1234567890', 3);
                      -- Result: '890'
                    

RTRIM(character_expression)

Returns the character expression after it removes trailing blanks.

  • character_expression: The character expression.

                      SELECT RTRIM('trimmed     ');
                      -- Result: 'trimmed'
                    

SOUNDEX(character_expression)

Returns the four-character Soundex code, based on how the string sounds when spoken.

  • character_expression: The alphanumeric expression of character data.

                      SELECT SOUNDEX('smith');
                      -- Result: 'S530'
                    

SPACE(repeatcount)

Returns the string that consists of repeated spaces.

  • repeatcount: The number of spaces.

                      SELECT SPACE(5);
                      -- Result: '     '
                    

SPLIT(string, delimiter, offset)

Returns a section of the string between to delimiters.

  • string: The string to split.
  • delimiter: The character to split the string with.
  • offset: The number of the split to return. Positive numbers are treated as offsets from the left, and negative numbers are treated as offsets from the right.

                      SELECT SPLIT('a/b/c/d', '/', 1);
                      -- Result: 'a'
                      SELECT SPLIT('a/b/c/d', '/', -2);
                      -- Result: 'c'
                    

STARTSWITH(character_expression, character_prefix)

Returns 1 if character_expression starts with character_prefix; otherwise, 0.

  • character_expression: The character expression.
  • character_prefix: The character prefix to search for.

                      SELECT STARTSWITH('0123456', '012');
                      -- Result: 1

                      SELECT STARTSWITH('0123456', '456');
                      -- Result: 0
                    

STR ( float_expression [ , integer_length [ , integer_decimal ] ] )

Returns the character data converted from the numeric data. For example, STR(123.45, 6, 1) returns 123.5.

  • float_expression: The float expression.
  • length: The optional total length to return. This includes decimal point, sign, digits, and spaces. The default is 10.
  • decimal: The optional number of places to the right of the decimal point. The decimal must be less than or equal to 16.

                      SELECT STR('123.456');
                      -- Result: '123'

                      SELECT STR('123.456', 2);
                      -- Result: '**'

                      SELECT STR('123.456', 10, 2);
                      -- Result: '123.46'
                    

STUFF(character_expression , integer_start , integer_length , replaceWith_expression)

Inserts a string into another string. It deletes the specified length of characters in the first string at the start position and then inserts the second string into the first string at the start position.

  • character_expression: The string expression.
  • start: The integer value that specifies the location to start deletion and insertion. If start or length is negative, null is returned. If start is longer than the string to be modified, character_expression, null is returned.
  • length: The integer that specifies the number of characters to delete. If length is longer than character_expression, deletion occurs up to the last character in replaceWith_expression.
  • replaceWith_expression: The expression of character data that will replace length characters of character_expression beginning at the start value.

                      SELECT STUFF('1234567890', 3, 2, 'xx');
                      -- Result: '12xx567890'
                    

SUBSTRING(string_value FROM start FOR length)

Returns the part of the string with the specified length; starts at the specified index.

  • string_value: The character string.
  • start: The positive integer that specifies the start index of characters to return.
  • length: Optional. The positive integer that specifies how many characters will be returned.

                      SELECT SUBSTRING('1234567890' FROM 3 FOR 2);
                      -- Result: '34'

                      SELECT SUBSTRING('1234567890' FROM 3);
                      -- Result: '34567890'
                    
You can also drop the FROM and FOR clauses:
                    SELECT SUBSTRING('1234567890', 3, 2)
                    --Result: '34'
                    SELECT SUBSTRING('1234567890', 3)
                    --Result: '34567890'
                    

TEXT_ENCODE(input_string, charset)

Returns binary output by encoding a string using the specified character set.

  • input_string: The plain text string.
  • charset: The character set to use, such as 'UTF-8', 'ISO-8859-1'.

                    SELECT TEXT_ENCODE('Café', 'UTF-8');
                    -- Result: (binary output)
                    

TEXT_DECODE(input_binary, charset)

Returns a string decoded from binary data using the specified character set.

  • input_binary: The binary value to decode.
  • charset: The character set used for decoding.

                    SELECT TEXT_DECODE(BinaryData, 'UTF-8');
                    -- Result: 'Café'
                    

TOSTRING(string_value1)

Converts the value of this instance to its equivalent string representation.

  • string_value1: The string to be converted.

                      SELECT TOSTRING(123);
                      -- Result: '123'

                      SELECT TOSTRING(123.456);
                      -- Result: '123.456'

                      SELECT TOSTRING(null);
                      -- Result: ''
                    

TRIM(trimspec trimchar FROM string_value)

Returns the character expression with leading and/or trailing blanks removed.

  • trimspec: Optional. If included must be one of the keywords BOTH, LEADING or TRAILING.
  • trimchar: Optional. If included should be a one-character string value.
  • string_value: The string value to trim.

                      SELECT TRIM('     trimmed     ');
                      -- Result: 'trimmed'

                      SELECT TRIM(LEADING FROM '     trimmed     ');
                      -- Result: 'trimmed     '

                      SELECT TRIM('-' FROM '-----trimmed-----');
                      -- Result: 'trimmed'

                      SELECT TRIM(BOTH '-' FROM '-----trimmed-----');
                      -- Result: 'trimmed'

                      SELECT TRIM(TRAILING '-' FROM '-----trimmed-----');
                      -- Result: '-----trimmed'
                    

UNICODE(ncharacter_expression)

Returns the integer value defined by the Unicode standard of the first character of the input expression.

  • ncharacter_expression: The Unicode character expression.

UPPER ( character_expression )

Returns the character expression with lowercase character data converted to uppercase.

  • character_expression: The character expression.

                      SELECT UPPER('MIXED case');
                      -- Result: 'MIXED CASE'
                    

XML_EXTRACT(xml, xpath [, separator])

Extracts an XML document using the specified XPath to flatten the XML. A comma is used to separate the outputs by default, but this can be changed by specifying the third parameter.

  • xml: The XML document to extract.
  • xpath: The XPath used to select the nodes. The nodes selected will be returned in a token-separated list.
  • separator: The optional token used to separate the items in the flattened response. If this is not specified, the separator will be a comma.

                      SELECT XML_EXTRACT('<vowels><ch>a</ch><ch>e</ch><ch>i</ch><ch>o</ch><ch>u</ch></vowels>', '/vowels/ch');
                      -- Result: 'a,e,i,o,u'

                      SELECT XML_EXTRACT('<vowels><ch>a</ch><ch>e</ch><ch>i</ch><ch>o</ch><ch>u</ch></vowels>', '/vowels/ch', ';');
                      -- Result: 'a;e;i;o;u'
                    

CData Python Connector for Couchbase

MATH Functions

ABS ( numeric_expression )

Returns the absolute (positive) value of the specified numeric expression.

  • numeric_expression: The expression of an indeterminate numeric data type except for the bit data type.

                      SELECT ABS(15);
                      -- Result: 15

                      SELECT ABS(-15);
                      -- Result: 15
                    

ACOS ( float_expression )

Returns the arc cosine, the angle in radians whose cosine is the specified float expression.

  • float_expression: The float expression that specifies the cosine of the angle to be returned. Values outside the range from -1 to 1 return null.

                      SELECT ACOS(0.5);
                      -- Result: 1.0471975511966
                    

ASIN ( float_expression )

Returns the arc sine, the angle in radians whose sine is the specified float expression.

  • float_expression: The float expression that specifies the sine of the angle to be returned. Values outside the range from -1 to 1 return null.

                      SELECT ASIN(0.5);
                      -- Result: 0.523598775598299
                    

ATAN ( float_expression )

Returns the arc tangent, the angle in radians whose tangent is the specified float expression.

  • float_expression: The float expression that specifies the tangent of the angle to be returned.

                      SELECT ATAN(10);
                      -- Result: 1.47112767430373
                    

ATN2 ( float_expression1 , float_expression2 )

Returns the angle in radians between the positive x-axis and the ray from the origin to the point (y, x) where x and y are the values of the two specified float expressions.

  • float_expression1: The float expression that is the y-coordinate.
  • float_expression2: The float expression that is the x-coordinate.

                      SELECT ATN2(1, 1);
                      -- Result: 0.785398163397448
                    

CEILING ( numeric_expression ) or CEIL( numeric_expression )

Returns the smallest integer greater than or equal to the specified numeric expression.

  • numeric_expression: The expression of an indeterminate numeric data type except for the bit data type.

                      SELECT CEILING(1.3);
                      -- Result: 2

                      SELECT CEILING(1.5);
                      -- Result: 2

                      SELECT CEILING(1.7);
                      -- Result: 2
                    

COS ( float_expression )

Returns the trigonometric cosine of the specified angle in radians in the specified expression.

  • float_expression: The float expression of the specified angle in radians.

                      SELECT COS(1);
                      -- Result: 0.54030230586814
                    

COT ( float_expression )

Returns the trigonometric cotangent of the angle in radians specified by float_expression.

  • float_expression: The float expression of the angle in radians.

                      SELECT COT(1);
                      -- Result: 0.642092615934331
                    

DEGREES ( numeric_expression )

Returns the angle in degrees for the angle specified in radians.

  • numeric_expression: The angle in radians, an expression of an indeterminate numeric data type except for the bit data type.

                      SELECT DEGREES(3.1415926);
                      -- Result: 179.999996929531
                    

EXP ( float_expression )

Returns the exponential value of the specified float expression. For example, EXP(LOG(20)) is 20.

  • float_expression: The float expression.

                      SELECT EXP(2);
                      -- Result: 7.38905609893065
                    

EXPR ( expression )

Evaluates the expression.

  • expression: The expression. Operators allowed are +, -, *, /, ==, !=, >, <, >=, and <=.

                      SELECT EXPR('1 + 2 * 3');
                      -- Result: 7

                      SELECT EXPR('1 + 2 * 3 == 7');
                      -- Result: true
                    

FLOOR ( numeric_expression )

Returns the largest integer less than or equal to the numeric expression.

  • numeric_expression: The expression of an indeterminate numeric data type except for the bit data type.

                      SELECT FLOOR(1.3);
                      -- Result: 1

                      SELECT FLOOR(1.5);
                      -- Result: 1

                      SELECT FLOOR(1.7);
                      -- Result: 1
                    

GREATEST(int1,int2,....)

Returns the greatest of the supplied integers.

				SELECT GREATEST(3,5,8,10,1)
				-- Result: 10			
				

HEX(value)

Returns a the equivalent hex for the input value.

  • value: A string or numerical value to be converted into hex.

				SELECT HEX(866849198);
				-- Result: 33AB11AE
				
				SELECT HEX('Sample Text');
				-- Result: 53616D706C652054657874
				

JSON_AVG(json, jsonpath)

Computes the average value of a JSON array within a JSON object. The path to the array is specified in the jsonpath argument. Return value is numeric or null.

  • json: The JSON document to compute.
  • jsonpath: The JSONPath used to select the nodes. [x], [2..], [..8], or [1..12] are accepted. [x] selects all nodes.

                      SELECT JSON_AVG('[1,2,3,4,5]', '$[x]');
                      -- Result: 3

                      SELECT JSON_AVG('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[x]');
                      -- Result: 3

                      SELECT JSON_AVG('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[3..]');
                      -- Result: 4.5
                    

JSON_COUNT(json, jsonpath)

Returns the number of elements in a JSON array within a JSON object. The path to the array is specified in the jsonpath argument. Return value is numeric or null.

  • json: The JSON document to compute.
  • jsonpath: The JSONPath used to select the nodes. [x], [2..], [..8], or [1..12] are accepted. [x] selects all nodes.

                      SELECT JSON_COUNT('[1,2,3,4,5]', '$[x]');
                      -- Result: 5

                      SELECT JSON_COUNT('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[x]');
                      -- Result: 5

                      SELECT JSON_COUNT('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[3..]');
                      -- Result: 2
                    

JSON_MAX(json, jsonpath)

Gets the maximum value in a JSON array within a JSON object. The path to the array is specified in the jsonpath argument. Return value is numeric or null.

  • json: The JSON document to compute.
  • jsonpath: The JSONPath used to select the nodes. [x], [2..], [..8], or [1..12] are accepted. [x] selects all nodes.

                      SELECT JSON_MAX('[1,2,3,4,5]', '$[x]');
                      -- Result: 5

                      SELECT JSON_MAX('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[x]');
                      -- Result: 5

                      SELECT JSON_MAX('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[..3]');
                      -- Result: 4
                    

JSON_MIN(json, jsonpath)

Gets the minimum value in a JSON array within a JSON object. The path to the array is specified in the jsonpath argument. Return value is numeric or null.

  • json: The JSON document to compute.
  • jsonpath: The JSONPath used to select the nodes. [x], [2..], [..8], or [1..12] are accepted. [x] selects all nodes.

                      SELECT JSON_MIN('[1,2,3,4,5]', '$[x]');
                      -- Result: 1

                      SELECT JSON_MIN('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[x]');
                      -- Result: 1

                      SELECT JSON_MIN('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[3..]');
                      -- Result: 4
                    

JSON_SUM(json, jsonpath)

Computes the summary value in JSON according to the JSONPath expression. Return value is numeric or null.

  • json: The JSON document to compute.
  • jsonpath: The JSONPath used to select the nodes. [x], [2..], [..8], or [1..12] are accepted. [x] selects all nodes.

                      SELECT JSON_SUM('[1,2,3,4,5]', '$[x]');
                      -- Result: 15

                      SELECT JSON_SUM('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[x]');
                      -- Result: 15

                      SELECT JSON_SUM('{"test": {"data": [1,2,3,4,5]}}', '$.test.data[3..]');
                      -- Result: 9
                    

LEAST(int1,int2,....)

Returns the least of the supplied integers.

				SELECT LEAST(3,5,8,10,1)
				-- Result: 1			
				

LOG ( float_expression [, base ] )

Returns the natural logarithm of the specified float expression.

  • float_expression: The float expression.
  • base: The optional integer argument that sets the base for the logarithm.

                      SELECT LOG(7.3890560);
                      -- Result: 1.99999998661119
                    

LOG10 ( float_expression )

Returns the base-10 logarithm of the specified float expression.

  • float_expression: The expression of type float.

                      SELECT LOG10(10000);
                      -- Result: 4
                    

MOD(dividend,divisor)

Returns the integer value associated with the remainder when dividing the dividend by the divisor.

  • dividend: The number to take the modulus of.
  • divisor: The number to divide the dividend by when determining the modulus.

				SELECT MOD(10,3);
				-- Result: 1
				

NEGATE(real_number)

Returns the opposite to the real number input.

  • real_number: The real number to find the opposite of.

				SELECT NEGATE(10);
				-- Result: -10
				
				SELECT NEGATE(-12.4)
				--Result: 12.4
				

PI ( )

Returns the constant value of pi.

                  SELECT PI()
                  -- Result: 3.14159265358979 
                

POWER ( float_expression , y )

Returns the value of the specified expression raised to the specified power.

  • float_expression: The float expression.
  • y: The power to raise float_expression to.

                      SELECT POWER(2, 10);
                      -- Result: 1024

                      SELECT POWER(2, -2);
                      -- Result: 0.25
                    

RADIANS ( float_expression )

Returns the angle in radians of the angle in degrees.

  • float_expression: The degrees of the angle as a float expression.

                      SELECT RADIANS(180);
                      -- Result: 3.14159265358979
                    

RAND ( [ integer_seed ] )

Returns a pseudorandom float value from 0 through 1, exclusive.

  • seed: The optional integer expression that specifies the seed value. If seed is not specified, a seed value at random will be assigned.

                      SELECT RAND();
                      -- This result may be different, since the seed is randomized
                      -- Result: 0.873159630165044

                      SELECT RAND(1);
                      -- This result will always be the same, since the seed is constant
                      -- Result: 0.248668584157093
                    

ROUND ( numeric_expression [ ,integer_length] [ ,function ] )

Returns the numeric value rounded to the specified length or precision.

  • numeric_expression: The expression of a numeric data type.
  • length: The optional precision to round the numeric expression to. When this is omitted, the default behavior will be to round to the nearest whole number.
  • function: The optional type of operation to perform. When the function parameter is omitted or has a value of 0 (default), numeric_expression is rounded. When a value other than 0 is specified, numeric_expression is truncated.

                      SELECT ROUND(1.3, 0);
                      -- Result: 1

                      SELECT ROUND(1.55, 1);
                      -- Result: 1.6

                      SELECT ROUND(1.7, 0, 0);
                      -- Result: 2

                      SELECT ROUND(1.7, 0, 1);
                      -- Result: 1
                      
                      SELECT ROUND (1.24);
                      -- Result: 1.0
                    

SIGN ( numeric_expression )

Returns the positive sign (1), 0, or negative sign (-1) of the specified expression.

  • numeric_expression: The expression of an indeterminate data type except for the bit data type.

                      SELECT SIGN(0);
                      -- Result: 0

                      SELECT SIGN(10);
                      -- Result: 1

                      SELECT SIGN(-10);
                      -- Result: -1
                    

SIN ( float_expression )

Returns the trigonometric sine of the angle in radians.

  • float_expression: The float expression specifying the angle in radians.

                     SELECT SIN(1);
                     -- Result: 0.841470984807897
                    

SQRT ( float_expression )

Returns the square root of the specified float value.

  • float_expression: The expression of type float.

                      SELECT SQRT(100);
                      -- Result: 10
                    

SQUARE ( float_expression )

Returns the square of the specified float value.

  • float_expression: The expression of type float.

                      SELECT SQUARE(10);
                      -- Result: 100

                      SELECT SQUARE(-10);
                      -- Result: 100
                    

TAN ( float_expression )

Returns the tangent of the input expression.

  • float_expression: The expression of type float.

                      SELECT TAN(1);
                      -- Result: 1.5574077246549
                    

TRUNC(decimal_number,precision)

Returns the supplied decimal number truncated to have the supplied decimal precision.

  • decimal_number: The decimal value to truncate.
  • precision: The number of decimal places to truncate the decimal number to.

				SELECT TRUNC(10.3423,2);
				-- Result: 10.34
				

_ROW_NUMBER_()

Returns a row index as an additional column.

				SELECT ColumnName, _ROW_NUMBER_() FROM TableName
				-- Result: ColumnData, 0
				ColumnData2, 1
				ColumnData3, 2
				

CData Python Connector for Couchbase

DATE Functions

CURRENT_DATE()

Returns the current date value.

                  SELECT CURRENT_DATE();
                  -- Result: 2018-02-01
                

CURRENT_TIMESTAMP()

Returns the current time stamp of the database system as a datetime value. This value is equal to GETDATE and SYSDATETIME, and is always in the local timezone.

                  SELECT CURRENT_TIMESTAMP();
                  -- Result: 2018-02-01 03:04:05
                

DATEADD (datepart , integer_number , date [, dateformat])

Returns the datetime value that results from adding the specified number (a signed integer) to the specified date part of the date.

  • datepart: The part of the date to add the specified number to. The valid values and abbreviations are
    • year (yy, yyyy)
    • quarter (qq, q)
    • month (mm, m)
    • week (wk, ww)
    • weekday (dw)
    • dayofyear (dy, y)
    • day (dd, d)
    • hour (hh)
    • minute (mi, n)
    • second (ss, s)
    • millisecond (ms)
  • number: The number to be added.
  • date: The expression of the datetime data type.
  • dateformat: The optional output date format.

                  SELECT DATEADD('d', 5, '2018-02-01');
                  -- Result: 2018-02-06

                  SELECT DATEADD('hh', 5, '2018-02-01 00:00:00');
                  -- Result: 2018-02-01 05:00:00
                

DATEDIFF ( datepart , startdate , enddate )

Returns the difference (a signed integer) of the specified time interval between the specified start date and end date.

  • datepart: The part of the date that is the time interval of the difference between the start date and end date. The valid values and abbreviations are:
    • Year (year, yyyy, yy)
    • Quarter (quarter, qq, q)
    • Month (month, mm, m)
    • Week (week, wk, ww)
    • Weekday (weekday, dw)
    • Dayofyear (dayofyear, dy, y)
    • Day (day, dd, d)
    • Hour (hour, hh)
    • Minute (minute, mi, n)
    • Second (second, ss, s)
    • Millisecond (millisecond, ms)
  • startdate: The datetime expression of the start date.
  • enddate: The datetime expression of the end date.

                  SELECT DATEDIFF('d', '2018-02-01', '2018-02-10');
                  -- Result: 9

                  SELECT DATEDIFF('hh', '2018-02-01 00:00:00', '2018-02-01 12:00:00');
                  -- Result: 12
                

DATE_FORMAT(date,format)

Returns the date or timestamp in the format specified. This function mirrors the MySQL DATE_FORMAT function.

  • date: A date or timestamp string.
  • format: The specifier string of the desired output format. The list of supported format specifiers comes from the MySQL DATE_FORMAT function (see link to MySQL documentation above).

					SELECT DATE_FORMAT('9/4/2021 3:11:53 AM','%h')
					-- Result: 03
				  

DATEFROMPARTS(integer_year, integer_month, integer_day)

Returns the datetime value for the specified year, month, and day.

  • year: The integer expression specifying the year.
  • month: The integer expression specifying the month.
  • day: The integer expression specifying the day.

                    SELECT DATEFROMPARTS(2018, 2, 1);
                    -- Result: 2018-02-01
                  

DATENAME(datepart , date)

Returns the character string that represents the specified date part of the specified date.

  • datepart: The part of the date to return. The valid values and abbreviations are year (yy, yyyy), quarter (qq, q), month (mm, m), dayofyear (dy, y), day (dd, d), week (wk, ww), weekday (dw), hour (hh), minute (mi, n), second (ss, s), millisecond (ms), microsecond (mcs), and nanosecond (ns).
  • date: The datetime expression.

                     SELECT DATENAME('yy', '2018-02-01');
                     -- Result: '2018'

                     SELECT DATENAME('dw', '2018-02-01');
                     -- Result: 'Thursday'
                   

DATEPART(datepart, date [,integer_datefirst])

Returns a character string that represents the specified date part of the specified date.

  • datepart: The part of the date to return. The valid values and abbreviations are year (yy, yyyy), quarter (qq, q), month (mm, m), dayofyear (dy, y), day (dd, d), week (wk, ww), weekday (dw), hour (hh), minute (mi, n), second (ss, s), millisecond (ms), microsecond (mcs), nanosecond (ns), ISODOW, ISO_WEEK (isoweek, isowk,isoww), and ISOYEAR.
  • date: The datetime string.
  • datefirst: The optional integer representing the first day of the week. The default is 7, Sunday.

                    SELECT DATEPART('yy', '2018-02-01');
                    -- Result: 2018

                    SELECT DATEPART('dw', '2018-02-01');
                    -- Result: 5
                  

DATETIMEFROMPARTS(integer_year, integer_month, integer_day, integer_hour, integer_minute, integer_seconds, integer_milliseconds)

Returns the datetime value for the specified date parts.

  • year: The integer expression specifying the year.
  • month: The integer expression specifying the month.
  • day: The integer expression specifying the day.
  • hour: The integer expression specifying the hour.
  • minute: The integer expression specifying the minute.
  • seconds: The integer expression specifying the seconds.
  • milliseconds: The integer expression specifying the milliseconds.

                    SELECT DATETIMEFROMPARTS(2018, 2, 1, 1, 2, 3, 456);
                    -- Result: 2018-02-01 01:02:03.456
                  

DATETIME2FROMPARTS(integer_year, integer_month, integer_day, integer_hour, integer_minute, integer_seconds, integer_fractions, integer_precision)

Returns the datetime value for the specified date parts.

  • year: The integer expression specifying the year.
  • month: The integer expression specifying the month.
  • day: The integer expression specifying the day.
  • hour: The integer expression specifying the hour.
  • minute: The integer expression specifying the minute.
  • seconds: The integer expression specifying the seconds.
  • fractions: The integer expression specifying the fractions of the second.
  • precision: The integer expression specifying the precision of the fraction.

				    SELECT DATETIME2FROMPARTS(2018, 2, 1, 1, 2, 3, 456, 3);
                    -- Result: 2018-02-01 01:02:03.456
                  

DATE_TRUNC(date, datepart)

Truncates the date to the precision of the given date part. Modeled after the Oracle TRUNC function.

  • date: The datetime string that specifies the date.
  • datepart: Refer to the Oracle documentation for valid datepart syntax.

				    SELECT DATE_TRUNC('05-04-2005', 'YY');
                    -- Result: '1/1/2005'
					
                    SELECT DATE_TRUNC('05-04-2005', 'MM');
                    -- Result: '5/1/2005'                    
                  

DATE_TRUNC2(datepart, date, [weekday])

Truncates the date to the precision of the given date part. Modeled after the PostgreSQL date_trunc function.

  • datepart: One of 'millennium', 'century', 'decade', 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute' or 'second'.
  • date: The datetime string that specifies the date.
  • weekday: The optional day of the week to use as the first day for 'week'. One of 'sunday', 'monday', etc.

                    SELECT DATE_TRUNC2('year', '2020-02-04');
                    -- Result: '2020-01-01'

                    SELECT DATE_TRUNC2('week', '2020-02-04', 'monday');
                    -- Result: '2020-02-02', which is the previous Monday
                  

DAY(date)

Returns the integer that specifies the day component of the specified date.

  • date: The datetime string that specifies the date.

                    SELECT DAY('2018-02-01');
                    -- Result: 1
                  

DAYNAME(date)

Returns the name of the day of the week of the specified date.

  • date: The datetime string that specifies the date.

                    SELECT DAYNAME('8/18/2021');
                    -- Result: Wednesday
                  

DAYOFMONTH(date)

Returns the day of the month of the given date part.
  • date: The datetime string that specifies the date.

				  SELECT DAYOFMONTH('04/15/2000');
				  -- Result: 15
				  

DAYOFWEEK(date)

Returns the day of the week of the given date part.
  • date: The datetime string that specifies the date.

				  SELECT DAYOFWEEK('04/15/2000');
				  -- Result: 7
				  

DAYOFYEAR(date)

Returns the day of the year of the given date part.
  • date: The datetime string that specifies the date.

				  SELECT DAYOFYEAR('04/15/2000');
				  -- Result: 106
				  

EOMONTH(date [, integer_month_to_add ]) or LAST_DAY(date)

Returns the last day of the month that contains the specified date with an optional offset.

  • date: The datetime expression specifying the date for which to return the last day of the month.
  • integer_month_to_add: The optional integer expression specifying the number of months to add to the date before calculating the end of the month.

                  SELECT EOMONTH('2018-02-01');
                  -- Result: 2018-02-28
                  
                  SELECT LAST_DAY('2018-02-01');
                  -- Result: 2018-02-28

                  SELECT EOMONTH('2018-02-01', 2);
                  -- Result: 2018-04-30
                

EXTRACT(date_part FROM date_column_name)

Returns the last day of the month that contains the specified date with an optional offset.

  • date_part: One of the following date components: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND.
  • date_column_name: The name of a date column in a table.

                  SELECT EXTRACT(YEAR FROM DateColumn)
                  -- Result: 2021
                

FDWEEK(date)

Returns the first day of the week of the given date part.
  • date: The datetime string that specifies the date.
  • weeks to add: An optional integer expression specifying the number of months to add to the date before calculating the first day of the week.

				  SELECT FDWEEK('02-08-2018');
				  -- Result: 2/4/2018

          SELECT FDWEEK('02-08-2018', 1)
          --Result: 02/11/2018
				  

FDMONTH(date)

Returns the first day of the month of the given date part.
  • date: The datetime string that specifies the date.
  • month to add: An optional integer expression specifying the number of months to add to the date before calculating the first day of the month.

				  SELECT FDMONTH('02-08-2018');
				  -- Result: 2/1/2018

          SELECT FDMONTH('02-08-2018', 1) 
          --Result: 03/01/2018
				  

FDQUARTER(date)

Returns the first day of the quarter of the given date part.
  • date: The datetime string that specifies the date.
  • quarters to add: An optional integer expression specifying the number of months to add to the date before calculating the first day of the quarter.

				  SELECT FDQUARTER('05-08-2018');
				  -- Result: 4/1/2018

          SELECT FDQUARTER('05-08-2018',1)
          --Result: 07/01/2018
				  

FILEMODIFIEDTIME(uri)

Returns the time stamp associated with the Date Modified of the relevant file.

  • uri: An absolute path pointing to a file on the local file system.

				 SELECT FILEMODIFIEDTIME('C:/Documents/myfile.txt');
				 -- Result: 6/25/2019 10:06:58 AM
				 

FROM_DAYS(datevalue)

Returns a date derived from the number of days after 1582-10-15 (based upon the Gregorian calendar). This will be equivalent to the MYSQL FROM_DAYS function.

  • datevalue: A integer value representing the number of days since 1582-10-15.

				SELECT FROM_DAYS(736000);
				-- Result: 2/6/2015
				

FROM_UNIXTIME(time, issecond)

Returns a representation of the unix_timestamp argument as a value in YYYY-MM-DD HH:MM:SS expressed in the current time zone.

  • time: The time stamp value from epoch time. Milliseconds are accepted.
  • issecond: Indicates the time stamp value is milliseconds to epoch time.

                      SELECT FROM_UNIXTIME(1540495231, 1);
                      -- Result: 2018-10-25 19:20:31

                      SELECT FROM_UNIXTIME(1540495357385, 0);
                      -- Result: 2018-10-25 19:22:37
                    

GETDATE()

Returns the current time stamp of the database system as a datetime value. This value is equal to CURRENT_TIMESTAMP and SYSDATETIME, and is always in the local timezone.

                  SELECT GETDATE();
                  -- Result: 2018-02-01 03:04:05
                

GETUTCDATE()

Returns the current time stamp of the database system formatted as a UTC datetime value. This value is equal to SYSUTCDATETIME.

In addition, GETUTCDATE can take an optional second parameter, a date and time that are converted to UTC.

                  SELECT GETUTCDATE();
                  -- For example, if the local timezone is Eastern European Time (GMT+2)
                  -- Result: 2018-02-01 05:04:05

                  SELECT GETUTCDATE('2020/08/31 13:56:00')
                  --Result: '2020-08-31 17:56:00'
                

HOUR(date)

Returns the hour component from the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT HOUR('02-02-2020 11:30:00');
				-- Result: 11
				

ISDATE(date, [date_format])

Returns 1 if the value is a valid date, time, or datetime value; otherwise, 0.

  • date: The datetime string.
  • date_format: The optional datetime format.

                      SELECT ISDATE('2018-02-01', 'yyyy-MM-dd');
                      -- Result: 1

                      SELECT ISDATE('Not a date');
                      -- Result: 0
                    

LAST_WEEK()

Returns a time stamp equivalent to exactly one week before the current date.

				SELECT LAST_WEEK();	//Assume the date is 3/17/2020	
			 -- Result: 3/10/2020 00:00:00
				

LAST_MONTH()

Returns a time stamp equivalent to exactly one month before the current date.

	
				SELECT LAST_MONTH(); //Assume the date is 3/17/2020
				-- Result: 2/17/2020 00:00:00
				

LAST_YEAR()

Returns a time stamp equivalent to exactly one year before the current date.

				SELECT LAST_YEAR();	//Assume the date is 3/17/2020	
				-- Result: 3/10/2019 00:00:00
				

LDWEEK(date)

Returns the last day of the provided week.

  • date: The datetime string.
  • weeks to add: An optional integer expression specifying the number of months to add to the date before calculating the last day of the week.

				SELECT LDWEEK('02-02-2020');
				-- Result: 2/8/2020
				

LDMONTH(date)

Returns the last day of the provided month.

  • date: The datetime string.
  • months to add: An optional integer expression specifying the number of months to add to the date before calculating the last day of the month.

				SELECT LDMONTH('02-02-2020');
				-- Result: 2/29/2020

        SELECT LDMONTH('02-08-2020', 1)
        --Result: 03/31/2020
				

LDQUARTER(date)

Returns the last day of the provided quarter.

  • date: The datetime string.
  • quarters to add: An optional integer expression specifying the number of months to add to the date before calculating the last day of the quarter.

				SELECT LDQUARTER('02-02-2020');
				-- Result: 3/31/2020

        SELECT LDQUARTER('02-02-2020',1)
        --Result: 06/30/2020
				

MAKEDATE(year, days)

Returns a date value from a year and a number of days.

  • year: The year
  • days: The number of days into the year. Value must be greater than 0.

          SELECT MAKEDATE(2020, 1);
          -- Result: 2020-01-01
        

MINUTE(date)

Returns the minute component from the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT MINUTE('02-02-2020 11:15:00');
				-- Result: 15
				

MONTH(date)

Returns the month component from the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT MONTH('02-02-2020');
				-- Result: 2
				

QUARTER(date)

Returns the quarter associated with the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT QUARTER('02-02-2020');
				-- Result: 1
				

SECOND(date)

Returns the second component from the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT SECOND('02-02-2020 11:15:23');
				-- Result: 23
				

SMALLDATETIMEFROMPARTS(integer_year, integer_month, integer_day, integer_hour, integer_minute)

Returns the datetime value for the specified date and time.

  • year: The integer expression specifying the year.
  • month: The integer expression specifying the month.
  • day: The integer expression specifying the day.
  • hour: The integer expression specifying the hour.
  • minute: The integer expression specifying the minute.

                      SELECT SMALLDATETIMEFROMPARTS(2018, 2, 1, 1, 2);
                      -- Result: 2018-02-01 01:02:00
                    

STRTODATE(string,format)

Parses the provided string value and returns the corresponding datetime.

  • string: The string value to be converted to datetime format.
  • format: A format string which describes how to interpret the first string input. A few special formats are available as well, including UNIX, UNIXMILIS, TICKS, and FILETICKS.

				SELECT STRTODATE('03*04*2020','dd*MM*yyyy');
				-- Result: 4/3/2020
				

SYSDATETIME()

Returns the current time stamp as a datetime value of the database system. It is equal to GETDATE and CURRENT_TIMESTAMP, and is always in the local timezone.

                  SELECT SYSDATETIME();
                  -- Result: 2018-02-01 03:04:05
                

SYSUTCDATETIME()

Returns the current system date and time as a UTC datetime value. It is equal to GETUTCDATE.

                  SELECT SYSUTCDATETIME();
                  -- For example, if the local timezone is Eastern European Time (GMT+2)
                  -- Result: 2018-02-01 05:04:05
                

TIMEFROMPARTS(integer_hour, integer_minute, integer_seconds, integer_fractions, integer_precision)

Returns the time value for the specified time and with the specified precision.

  • hour: The integer expression specifying the hour.
  • minute: The integer expression specifying the minute.
  • seconds: The integer expression specifying the seconds.
  • fractions: The integer expression specifying the fractions of the second.
  • precision : The integer expression specifying the precision of the fraction.

                      SELECT TIMEFROMPARTS(1, 2, 3, 456, 3);
                      -- Result: 01:02:03.456
                    

TO_DAYS(date)

Returns the number of days since 0000-00-01. This will only return a value for dates on or after 1582-10-15 (based upon the Gregorian calendar). This will be equivalent to the MYSQL TO_DAYS function.

  • date: The datetime string that specifies the date.

				SELECT TO_DAYS('02-06-2015');
				-- Result: 736000
				

WEEK(date)

Returns the week (of the year) associated with the provided datetime.

  • date: The datetime string that specifies the date.

				SELECT WEEK('02-17-2020 11:15:23');
				-- Result: 8
				

YEAR(date)

Returns the integer that specifies the year of the specified date.

  • date: The datetime string.

                      SELECT YEAR('2018-02-01');
                      -- Result: 2018
                    

CData Python Connector for Couchbase

Date Literal Functions

The following date literal functions can be used to filter date fields using relative intervals. Note that while the <, >, and = operators are supported for these functions, <= and >= are not.

L_TODAY()

The current day.

  SELECT * FROM MyTable WHERE MyDateField = L_TODAY()

L_YESTERDAY()

The previous day.

  SELECT * FROM MyTable WHERE MyDateField = L_YESTERDAY()

L_TOMORROW()

The following day.

  SELECT * FROM MyTable WHERE MyDateField = L_TOMORROW()

L_LAST_WEEK()

Every day in the preceding week.

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_WEEK()

L_THIS_WEEK()

Every day in the current week.

  SELECT * FROM MyTable WHERE MyDateField = L_THIS_WEEK()

L_NEXT_WEEK()

Every day in the following week.

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_WEEK()
Also available:
  • L_LAST/L_THIS/L_NEXT MONTH
  • L_LAST/L_THIS/L_NEXT QUARTER
  • L_LAST/L_THIS/L_NEXT YEAR

L_LAST_N_DAYS(n)

The previous n days, excluding the current day.

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_N_DAYS(3)

L_NEXT_N_DAYS(n)

The following n days, including the current day.

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_N_DAYS(3)
Also available:
  • L_LAST/L_NEXT_90_DAYS

L_LAST_N_WEEKS(n)

Every day in every week, starting n weeks before current week, and ending in the previous week.

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_N_WEEKS(3)

L_NEXT_N_WEEKS(n)

Every day in every week, starting the following week, and ending n weeks in the future.

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_N_WEEKS(3)
Also available:
  • L_LAST/L_NEXT_N_MONTHS(n)
  • L_LAST/L_NEXT_N_QUARTERS(n)
  • L_LAST/L_NEXT_N_YEARS(n)

CData Python Connector for Couchbase

Projection Functions

ARRAY_AGG(column)

Returns array of the non-MISSING values in the group, including NULL values.

  • column: Any column expression.

ARRAY_APPEND(column, value)

Returns new array with value appended.

  • column: Any column expression.
  • value: The value to be appended to the array.

ARRAY_CONCAT(column1, column2)

Returns new array with the concatenation of the input arrays.

  • column1: Any column expression.
  • column2: Any column expression.

ARRAY_DISTINCT(column)

Returns new array with distinct elements of input array.

  • column: Any column expression.

ARRAY_IFNULL(column)

Returns the first non-NULL value in the array, or NULL.

  • column: Any column expression.

ARRAY_PREPEND(column, value)

Returns new array with value pre-pended.

  • column: Any column expression.
  • value: The value to be pre-pended to the array.

ARRAY_PUT(column, value)

Returns new array with value appended, if value is not already present, otherwise returns the unmodified input array.

  • column: Any column expression.
  • value: The value to append to the array.

ARRAY_REMOVE(column, value)

Returns new array with all occurrences of value removed.

  • column: Any column expression.
  • value: The value to be removed from the array.

ARRAY_REPLACE(column, value1, value2 [, integer_n])

Returns new array with all occurrences of value removed.

  • column: Any column expression.
  • value1: The value to be replaced by value2.
  • value2: The value to replace value1.
  • integer_n: The maximum number of replacements to be performed.

ARRAY_REVERSE(column)

Returns new array with all elements in reverse order.

  • column: Any column expression.

ARRAY_SORT(column)

Returns new array with elements sorted in N1QL collation order.

  • column: Any column expression.

DECODE_JSON(column)

Unmarshals the JSON-encoded string into a N1QL value. The empty string is MISSING.

  • column: Any column expression.

ENCODE_JSON(column)

Marshals the N1QL value into a JSON-encoded string. MISSING becomes the empty string.

  • column: Any column expression.

ENCODED_SIZE(column)

Number of bytes in an uncompressed JSON encoding of the value. The exact size is implementation-dependent. Always returns an integer, and never MISSING or NULL. Returns 0 for MISSING.

  • column: Any column expression.

POLY_LENGTH(column)

Returns length of the value after evaluating the expression. The exact meaning of length depends on the type of the value: MISSING: MISSING; NULL: NULL; String: The length of the string.; Array: The number of elements in the array.; Object: The number of name/value pairs in the object; Any other value: NULL.

  • column: Any column expression.

OBJECT_LENGTH(column)

Returns number of name-value pairs in the object.

  • column: Any column expression.

OBJECT_NAMES(column)

Returns array containing the attribute names of the object, in N1QL collation order.

  • column: Any column expression.

OBJECT_PAIRS(column)

Returns array containing the attribute name and value pairs of the object, in N1QL collation order of the names.

  • column: Any column expression.

OBJECT_VALUES(column)

Returns array containing the attribute values of the object, in N1QL collation order of the corresponding names.

  • column: Any column expression.

ARRAY_AVG(column)

Returns arithmetic mean (average) of all the non-NULL number values in the array, or NULL if there are no such values.

  • column: Any column expression.

ARRAY_CONTAINS(column, value)

Returns true if the array contains value.

  • column: Any column expression.
  • value: The value contained within the array.

ARRAY_COUNT(column)

Returns count of all the non-NULL values in the array, or zero if there are no such values.

  • column: Any column expression.

ARRAY_LENGTH(column)

Returns the number of elements in the array.

  • column: Any column expression.

ARRAY_MAX(column)

Returns the largest non-NULL, non-MISSING array element, in N1QL collation order.

  • column: Any column expression.

ARRAY_MIN(column)

Returns smallest non-NULL, non-MISSING array element, in N1QL collation order.

  • column: Any column expression.

ARRAY_POSITION(column, value)

Returns the first position of value within the array, or -1. Array position is zero-based, i.e. the first position is 0.

  • column: Any column expression.
  • value: The value contained within the array.

ARRAY_SUM(column)

Sum of all the non-NULL number values in the array, or zero if there are no such values.

  • column: Any column expression.

GREATEST(column1, column2 [,column3 [,column4]])

Largest non-NULL, non-MISSING value if the values are of the same type; otherwise NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

LEAST(column1, column2 [,column3 [,column4]])

Returns smallest non-NULL, non-MISSING value if the values are of the same type, otherwise returns NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFMISSING(column1, column2 [,column3 [,column4]])

Returns the first non-MISSING value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFMISSINGORNULL(column1, column2 [,column3 [,column4]])

Returns first non-NULL, non-MISSING value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNULL(column1, column2 [,column3 [,column4]])

Returns first non-NULL value. Note that this function might return MISSING if there is no non-NULL value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

MISSINGIF(column1, column2)

Returns MISSING if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.

NULLIF(column1, column2)

Returns NULL if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.

IFINF(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-Inf number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNAN(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-NaN number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNANORINF(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-Inf, or non-NaN number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

NANIF(column1, column2 [,column3 [,column4]])

Returns NaN if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

NEGINFIF(column1, column2 [,column3 [,column4]])

Returns NegInf if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

POSINFIF(column1, column2 [,column3 [,column4]])

Returns PosInf if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

CLOCK_MILLIS()

Returns system clock at function evaluation time, as UNIX milliseconds. Varies during a query.

CLOCK_STR([string_fmt])

Returns system clock at function evaluation time, as a string in a supported format. Varies during a query.

  • string_fmt: The datetime format to return the system clock in.

DATE_ADD_MILLIS(column, integer_n, string_part)

Performs date arithmetic, and returns result of computation. n and part are used to define an interval or duration, which is then added (or subtracted) to the UNIX time stamp, returning the result.

  • column: Any column expression.
  • integer_n: The number of string_part's to add to the column value.
  • string_part: The part to add integer_n to, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_ADD_STR(column, integer_n, string_part)

Performs date arithmetic. n and part are used to define an interval or duration, which is then added (or subtracted) to the date string in a supported format, returning the result.

  • column: Any column expression.
  • integer_n: The number of string_part's to add to the column value.
  • string_part: The part to add integer_n to, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_DIFF_MILLIS(column1, column2, string_part)

Performs date arithmetic. Returns the elapsed time between two UNIX time stamps as an integer whose unit is part.

  • column1: Any column expression.
  • column2: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_DIFF_STR(column1, column2, string_part)

Performs date arithmetic. Returns the elapsed time between two date strings in a supported format, as an integer whose unit is part.

  • column1: Any column expression.
  • column2: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_PART_MILLIS(column1, string_part [, tz])

Returns date part as an integer. The date expression is a number representing UNIX milliseconds, and part is one of the following date part strings.

  • column1: Any column expression.
  • string_part: The component of the date to extract. Available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, millisecond, day_of_year, day_of_week, iso_week, iso_year, iso_dow, timezone, timezone_hour, and timezone_minute.
  • tz: The timezone to convert the local time to. Default to the system timezone if not specified. If an incorrect time zone is provided, the null is returned.

DATE_PART_STR(column1, string_part)

Returns date part as an integer. The date expression is a string in a supported format, and part is one of the supported date part strings.

  • column1: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, millisecond, day_of_year, day_of_week, iso_week, iso_year, iso_dow, timezone, timezone_hour, and timezone_minute.

DATE_TRUNC_MILLIS(column1, string_part)

Returns UNIX time stamp that has been truncated so that the given date part string is the least significant.

  • column1: Any column expression.
  • string_part: The least significant date part, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_TRUNC_STR(column1, string_part)

Returns ISO 8601 time stamp that has been truncated so that the given date part string is the least significant.

  • column1: Any column expression.
  • string_part: The least significant date part, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

MILLIS(column1)

Returns date that has been converted in a supported format to UNIX milliseconds.

  • column1: Any column expression.

STR_TO_MILLIS(column1)

Returns date that has been converted in a supported format to UNIX milliseconds.

  • column1: Any column expression.

MILLIS_TO_STR(column [, string_fmt])

Returns the string in the supported format to which the UNIX milliseconds has been converted.

  • column1: Any column expression.
  • string_fmt: The datetime format to return the system clock in.

MILLIS_TO_UTC(column [, string_fmt])

Returns the UTC string to which the UNIX time stamp has been converted in the supported format.

  • column1: Any column expression.
  • string_fmt: The datetime format to return the system clock in.

MILLIS_TO_TZ(column, string_tzname [, string_fmt])

Converts the UNIX time stamp to a string in the named time zone, and returns the string.

  • column1: Any column expression.
  • string_tzname: The time zone name.
  • string_fmt: The datetime format to return the system clock in.

NOW_MILLIS()

Returns statement time stamp as UNIX milliseconds; does not vary during a query.

NOW_STR([string_fmt])

Returns statement time stamp as a string in a supported format; does not vary during a query.

  • string_fmt: The datetime format to return the timestamp in.

STR_TO_UTC(column1)

Converts the ISO 8601 time stamp to UTC.

  • column1: Any column expression.

STR_TO_ZONE_NAME(column, string_tzname)

Converts the supported time stamp string to the named time zone.

  • column1: Any column expression.
  • string_tzname: The time zone name.

BASE64(expression)

Returns base64 encoding of expression.

  • expression: Any column or literal expression.

ABS(expression)

Returns absolute value of the number.

  • expression: Any column or literal expression.

ACOS(expression)

Returns arccosine in radians.

  • expression: Any column or literal expression.

ASIN(expression)

Returns arcsine in radians.

  • expression: Any column or literal expression.

ATAN(expression)

Returns arctangent in radians.

  • expression: Any column or literal expression.

ATAN2(expression1, expression2)

Returns arctangent of expression2/expression1.

  • expression1: Any column or literal expression.
  • expression2: Any column or literal expression.

CEIL(expression)

Returns smallest integer not less than the number.

  • expression: Any column or literal expression.

COS(expression)

Returns cosine.

  • expression: Any column or literal expression.

DEGREES(expression)

Returns radians to degrees.

  • expression: Any column or literal expression.

E()

Base of natural logarithms.

EXP(expression)

Returns e^expression.

  • expression: Any column or literal expression.

LN(expression)

Returns log base e.

  • expression: Any column or literal expression.

LOG(expression)

Returns log base 10.

  • expression: Any column or literal expression.

FLOOR(expression)

Largest integer not greater than the number.

  • expression: Any column or literal expression.

PI()

Returns PI.

POWER(expression1, expression2)

Returns expression1^expression2.

  • expression1: Any column or literal expression.
  • expression2: Any column or literal expression.

RADIANS(expression)

Returns degrees to radians.

  • expression: Any column or literal expression.

RANDOM([expression])

Returns pseudo-random number with optional seed.

  • expression: Any column or literal expression.

ROUND(expression [, integer_digits])

Rounds the value to the given number of integer digits to the right of the decimal point (left if digits is negative). Digits is 0 if not given.

  • expression: Any column or literal expression.
  • integer_digits: The number of digits to round to.

SIGN(expression)

Valid values: -1, 0, or 1 for negative, zero, or positive numbers respectively.

  • expression: Any column or literal expression.

SIN(expression)

Returns sine.

  • expression: Any column or literal expression.

SQRT(expression)

Returns square root.

  • expression: Any column or literal expression.

TAN(expression)

Returns tangent.

  • expression: Any column or literal expression.

TRUNC(expression [, integer_digits])

Truncates the number to the given number of integer digits to the right of the decimal point (left if digits is negative). Digits is 0 if not given.

  • expression: Any column or literal expression.
  • integer_digits: The number of digits to truncate.

CONTAINS(column, string_substring)

True if the string contains the substring.

  • column: Any column or literal expression.
  • string_substring: The substring to search for.

INITCAP(column)

Converts the string so that the first letter of each word is uppercase and every other letter is lowercase.

  • column: Any column or literal expression.

LENGTH(column)

Returns length of the string value.

  • column: Any column or literal expression.

LOWER(column)

Returns lowercase of the string value.

  • column: Any column or literal expression.

LTRIM(column [, string_chars])

Returns string with all leading chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The leading characters to remove.

POSITION(column, string_substring)

Returns the first position of the substring within the string, or -1. The position is zero-based, i.e., the first position is 0.

  • column: Any column or literal expression.
  • string_substring: The substring to search for.

REPEAT(column, integer_n)

Returns string formed by repeating expression n times.

  • column: Any column or literal expression.
  • integer_n: The number of times to repeat column.

REPLACE(column, string_substring, string_replace [, integer_n])

Returns string with all occurrences of substr replaced with repl. If n is given, at most n replacements are performed.

  • column: The column expression.
  • string_substring: The regular expression to match.
  • string_replace: The value to replace the matched pattern.
  • integer_n: The maximum number of replacements to make.

RTRIM(column [, string_chars])

Returns string with all trailing chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The trailing characters to remove.

SPLIT(column [, string_sep])

Splits the string into an array of substrings separated by string_sep. If string_sep is not given, any combination of white space characters is used.

  • column: Any column or literal expression.
  • string_sep: The separator to split column on.

SUBSTR(column, integer_position [, integer_length])

Returns substring from the integer position of the given length, or to the end of the string. The position is zero-based, i.e. the first position is 0. If position is negative, it is counted from the end of the string; -1 is the last position in the string.

  • column: Any column or literal expression.
  • integer_position: The starting position.
  • integer_length: The total length of the substring to retrieve.

TRIM(column [, string_chars])

Returns string with all leading and trailing chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The leading and trailing characters to remove.

UPPER(column)

Returns uppercase of the string value.

  • column: Any column or literal expression.

TOARRAY(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Arrays are themselves; All other values are wrapped in an array.

  • column: Any column expression.

TOATOM(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Arrays of length 1 are the result of TOATOM() on their single element; Objects of length 1 are the result of TOATOM() on their single value; Booleans, numbers, and strings are themselves; All other values are NULL.

  • column: Any column expression.

TOBOOLEAN(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is false; Numbers +0, -0, and NaN are false; Empty strings, arrays, and objects are false; All other values are true.

  • column: Any column expression.

TONUMBER(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is 0; True is 1; Numbers are themselves; Strings that parse as numbers are those numbers; All other values are NULL.

  • column: Any column expression.

TOOBJECT(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Objects are themselves; All other values are the empty object.

  • column: Any column expression.

TOSTRING(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is "false"; True is "true"; Numbers are their string representation; Strings are themselves; All other values are NULL.

  • column: Any column expression.

CData Python Connector for Couchbase

Predicate Functions

REGEXP_CONTAINS(column, string_pattern)

Returns True if the string value contains the regular expression pattern.

  • column: The column expression.
  • string_pattern: The regular expression to match.

REGEXP_LIKE(column, string_pattern)

Returns True if the string value matches the regular expression pattern.

  • column: The column expression.
  • string_pattern: The regular expression to match.

REGEXP_POSITION(column, string_pattern)

Returns first position of the regular expression pattern within the string, or -1.

  • column: The column expression.
  • string_pattern: The regular expression to match.

REGEXP_REPLACE(column, string_pattern, string_replace [, integer_n])

Returns new string with occurrences of pattern replaced with string_replace. If n is given, at most n replacements are performed.

  • column: The column expression.
  • string_pattern: The regular expression to match.
  • string_replace: The value to replace the matched pattern.
  • integer_n: The maximum number of replacements to make.

ISARRAY(column)

Returns True if expression is an array, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

ISATOM(column)

Returns True if expression is a Boolean, number, or string, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

ISBOOLEAN(column)

Returns True if expression is a Boolean, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

ISNUMBER(column)

Returns True if expression is a number, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

ISOBJECT(column)

Returns True if expression is an object, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

ISSTRING(column)

Returns True if expression is a string, otherwise returns MISSING, NULL or false.

  • column: Any column expression.

TYPE(column)

Returns one of the following strings, based on the value of expression: missing, null, boolean, number, string, array, object, or binary.

  • column: Any column expression.

ARRAY_AVG(column)

Returns arithmetic mean (average) of all the non-NULL number values in the array, or NULL if there are no such values.

  • column: Any column expression.

ARRAY_CONTAINS(column, value)

Returns true if the array contains value.

  • column: Any column expression.
  • value: The value contained within the array.

ARRAY_COUNT(column)

Returns count of all the non-NULL values in the array, or zero if there are no such values.

  • column: Any column expression.

ARRAY_LENGTH(column)

Returns the number of elements in the array.

  • column: Any column expression.

ARRAY_MAX(column)

Returns the largest non-NULL, non-MISSING array element, in N1QL collation order.

  • column: Any column expression.

ARRAY_MIN(column)

Returns smallest non-NULL, non-MISSING array element, in N1QL collation order.

  • column: Any column expression.

ARRAY_POSITION(column, value)

Returns the first position of value within the array, or -1. Array position is zero-based, i.e. the first position is 0.

  • column: Any column expression.
  • value: The value contained within the array.

ARRAY_SUM(column)

Sum of all the non-NULL number values in the array, or zero if there are no such values.

  • column: Any column expression.

GREATEST(column1, column2 [,column3 [,column4]])

Largest non-NULL, non-MISSING value if the values are of the same type; otherwise NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

LEAST(column1, column2 [,column3 [,column4]])

Returns smallest non-NULL, non-MISSING value if the values are of the same type, otherwise returns NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFMISSING(column1, column2 [,column3 [,column4]])

Returns the first non-MISSING value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFMISSINGORNULL(column1, column2 [,column3 [,column4]])

Returns first non-NULL, non-MISSING value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNULL(column1, column2 [,column3 [,column4]])

Returns first non-NULL value. Note that this function might return MISSING if there is no non-NULL value.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

MISSINGIF(column1, column2)

Returns MISSING if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.

NULLIF(column1, column2)

Returns NULL if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.

IFINF(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-Inf number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNAN(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-NaN number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

IFNANORINF(column1, column2 [,column3 [,column4]])

Returns first non-MISSING, non-Inf, or non-NaN number. Returns MISSING or NULL if a non-number input is encountered first.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

NANIF(column1, column2 [,column3 [,column4]])

Returns NaN if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

NEGINFIF(column1, column2 [,column3 [,column4]])

Returns NegInf if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

POSINFIF(column1, column2 [,column3 [,column4]])

Returns PosInf if column1 = column2, otherwise returns column1. Returns MISSING or NULL if either input is MISSING or NULL.

  • column1: Any column expression.
  • column2: Any column expression.
  • column3: Any column expression.
  • column4: Any column expression.

CLOCK_MILLIS()

Returns system clock at function evaluation time, as UNIX milliseconds. Varies during a query.

CLOCK_STR([string_fmt])

Returns system clock at function evaluation time, as a string in a supported format. Varies during a query.

  • string_fmt: The datetime format to return the system clock in.

DATE_ADD_MILLIS(column, integer_n, string_part)

Performs date arithmetic, and returns result of computation. n and part are used to define an interval or duration, which is then added (or subtracted) to the UNIX time stamp, returning the result.

  • column: Any column expression.
  • integer_n: The number of string_part's to add to the column value.
  • string_part: The part to add integer_n to, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_ADD_STR(column, integer_n, string_part)

Performs date arithmetic. n and part are used to define an interval or duration, which is then added (or subtracted) to the date string in a supported format, returning the result.

  • column: Any column expression.
  • integer_n: The number of string_part's to add to the column value.
  • string_part: The part to add integer_n to, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_DIFF_MILLIS(column1, column2, string_part)

Performs date arithmetic. Returns the elapsed time between two UNIX time stamps as an integer whose unit is part.

  • column1: Any column expression.
  • column2: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_DIFF_STR(column1, column2, string_part)

Performs date arithmetic. Returns the elapsed time between two date strings in a supported format, as an integer whose unit is part.

  • column1: Any column expression.
  • column2: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_PART_MILLIS(column1, string_part [, tz])

Returns date part as an integer. The date expression is a number representing UNIX milliseconds, and part is one of the following date part strings.

  • column1: Any column expression.
  • string_part: The component of the date to extract. Available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, millisecond, day_of_year, day_of_week, iso_week, iso_year, iso_dow, timezone, timezone_hour, and timezone_minute.
  • tz: The timezone to convert the local time to. Default to the system timezone if not specified. If an incorrect time zone is provided, the null is returned.

DATE_PART_STR(column1, string_part)

Returns date part as an integer. The date expression is a string in a supported format, and part is one of the supported date part strings.

  • column1: Any column expression.
  • string_part: The unit of the result, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, millisecond, day_of_year, day_of_week, iso_week, iso_year, iso_dow, timezone, timezone_hour, and timezone_minute.

DATE_TRUNC_MILLIS(column1, string_part)

Returns UNIX time stamp that has been truncated so that the given date part string is the least significant.

  • column1: Any column expression.
  • string_part: The least significant date part, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

DATE_TRUNC_STR(column1, string_part)

Returns ISO 8601 time stamp that has been truncated so that the given date part string is the least significant.

  • column1: Any column expression.
  • string_part: The least significant date part, available values are: millennium, century, decade, year, quarter, month, week, day, hour, minute, second, and millisecond.

MILLIS(column1)

Returns date that has been converted in a supported format to UNIX milliseconds.

  • column1: Any column expression.

STR_TO_MILLIS(column1)

Returns date that has been converted in a supported format to UNIX milliseconds.

  • column1: Any column expression.

MILLIS_TO_STR(column [, string_fmt])

Returns the string in the supported format to which the UNIX milliseconds has been converted.

  • column1: Any column expression.
  • string_fmt: The datetime format to return the system clock in.

MILLIS_TO_UTC(column [, string_fmt])

Returns the UTC string to which the UNIX time stamp has been converted in the supported format.

  • column1: Any column expression.
  • string_fmt: The datetime format to return the system clock in.

MILLIS_TO_TZ(column, string_tzname [, string_fmt])

Converts the UNIX time stamp to a string in the named time zone, and returns the string.

  • column1: Any column expression.
  • string_tzname: The time zone name.
  • string_fmt: The datetime format to return the system clock in.

NOW_MILLIS()

Returns statement time stamp as UNIX milliseconds; does not vary during a query.

NOW_STR([string_fmt])

Returns statement time stamp as a string in a supported format; does not vary during a query.

  • string_fmt: The datetime format to return the timestamp in.

STR_TO_UTC(column1)

Converts the ISO 8601 time stamp to UTC.

  • column1: Any column expression.

STR_TO_ZONE_NAME(column, string_tzname)

Converts the supported time stamp string to the named time zone.

  • column1: Any column expression.
  • string_tzname: The time zone name.

BASE64(expression)

Returns base64 encoding of expression.

  • expression: Any column or literal expression.

ABS(expression)

Returns absolute value of the number.

  • expression: Any column or literal expression.

ACOS(expression)

Returns arccosine in radians.

  • expression: Any column or literal expression.

ASIN(expression)

Returns arcsine in radians.

  • expression: Any column or literal expression.

ATAN(expression)

Returns arctangent in radians.

  • expression: Any column or literal expression.

ATAN2(expression1, expression2)

Returns arctangent of expression2/expression1.

  • expression1: Any column or literal expression.
  • expression2: Any column or literal expression.

CEIL(expression)

Returns smallest integer not less than the number.

  • expression: Any column or literal expression.

COS(expression)

Returns cosine.

  • expression: Any column or literal expression.

DEGREES(expression)

Returns radians to degrees.

  • expression: Any column or literal expression.

E()

Base of natural logarithms.

EXP(expression)

Returns e^expression.

  • expression: Any column or literal expression.

LN(expression)

Returns log base e.

  • expression: Any column or literal expression.

LOG(expression)

Returns log base 10.

  • expression: Any column or literal expression.

FLOOR(expression)

Largest integer not greater than the number.

  • expression: Any column or literal expression.

PI()

Returns PI.

POWER(expression1, expression2)

Returns expression1^expression2.

  • expression1: Any column or literal expression.
  • expression2: Any column or literal expression.

RADIANS(expression)

Returns degrees to radians.

  • expression: Any column or literal expression.

RANDOM([expression])

Returns pseudo-random number with optional seed.

  • expression: Any column or literal expression.

ROUND(expression [, integer_digits])

Rounds the value to the given number of integer digits to the right of the decimal point (left if digits is negative). Digits is 0 if not given.

  • expression: Any column or literal expression.
  • integer_digits: The number of digits to round to.

SIGN(expression)

Valid values: -1, 0, or 1 for negative, zero, or positive numbers respectively.

  • expression: Any column or literal expression.

SIN(expression)

Returns sine.

  • expression: Any column or literal expression.

SQRT(expression)

Returns square root.

  • expression: Any column or literal expression.

TAN(expression)

Returns tangent.

  • expression: Any column or literal expression.

TRUNC(expression [, integer_digits])

Truncates the number to the given number of integer digits to the right of the decimal point (left if digits is negative). Digits is 0 if not given.

  • expression: Any column or literal expression.
  • integer_digits: The number of digits to truncate.

CONTAINS(column, string_substring)

True if the string contains the substring.

  • column: Any column or literal expression.
  • string_substring: The substring to search for.

INITCAP(column)

Converts the string so that the first letter of each word is uppercase and every other letter is lowercase.

  • column: Any column or literal expression.

LENGTH(column)

Returns length of the string value.

  • column: Any column or literal expression.

LOWER(column)

Returns lowercase of the string value.

  • column: Any column or literal expression.

LTRIM(column [, string_chars])

Returns string with all leading chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The leading characters to remove.

POSITION(column, string_substring)

Returns the first position of the substring within the string, or -1. The position is zero-based, i.e., the first position is 0.

  • column: Any column or literal expression.
  • string_substring: The substring to search for.

REPEAT(column, integer_n)

Returns string formed by repeating expression n times.

  • column: Any column or literal expression.
  • integer_n: The number of times to repeat column.

REPLACE(column, string_substring, string_replace [, integer_n])

Returns string with all occurrences of substr replaced with repl. If n is given, at most n replacements are performed.

  • column: The column expression.
  • string_substring: The regular expression to match.
  • string_replace: The value to replace the matched pattern.
  • integer_n: The maximum number of replacements to make.

RTRIM(column [, string_chars])

Returns string with all trailing chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The trailing characters to remove.

SPLIT(column [, string_sep])

Splits the string into an array of substrings separated by string_sep. If string_sep is not given, any combination of white space characters is used.

  • column: Any column or literal expression.
  • string_sep: The separator to split column on.

SUBSTR(column, integer_position [, integer_length])

Returns substring from the integer position of the given length, or to the end of the string. The position is zero-based, i.e. the first position is 0. If position is negative, it is counted from the end of the string; -1 is the last position in the string.

  • column: Any column or literal expression.
  • integer_position: The starting position.
  • integer_length: The total length of the substring to retrieve.

TRIM(column [, string_chars])

Returns string with all leading and trailing chars removed. White space by default.

  • column: Any column or literal expression.
  • string_chars: The leading and trailing characters to remove.

UPPER(column)

Returns uppercase of the string value.

  • column: Any column or literal expression.

TOARRAY(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Arrays are themselves; All other values are wrapped in an array.

  • column: Any column expression.

TOATOM(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Arrays of length 1 are the result of TOATOM() on their single element; Objects of length 1 are the result of TOATOM() on their single value; Booleans, numbers, and strings are themselves; All other values are NULL.

  • column: Any column expression.

TOBOOLEAN(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is false; Numbers +0, -0, and NaN are false; Empty strings, arrays, and objects are false; All other values are true.

  • column: Any column expression.

TONUMBER(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is 0; True is 1; Numbers are themselves; Strings that parse as numbers are those numbers; All other values are NULL.

  • column: Any column expression.

TOOBJECT(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; Objects are themselves; All other values are the empty object.

  • column: Any column expression.

TOSTRING(column)

Returns array as follows: MISSING is MISSING; NULL is NULL; False is "false"; True is "true"; Numbers are their string representation; Strings are themselves; All other values are NULL.

  • column: Any column expression.

CData Python Connector for Couchbase

SELECT Statements

A SELECT statement can consist of the following basic clauses.

  • SELECT
  • INTO
  • FROM
  • JOIN
  • WHERE
  • GROUP BY
  • HAVING
  • UNION
  • ORDER BY
  • LIMIT

SELECT Syntax

The following syntax diagram outlines the syntax supported by the SQL engine of the connector:

SELECT {
  [ TOP <numeric_literal> | DISTINCT ]
  { 
    * 
    | { 
        <expression> [ [ AS ] <column_reference> ] 
        | { <table_name> | <correlation_name> } .* 
      } [ , ... ] 
  }
  { 
    FROM <table_reference> [ [ AS ] <identifier> ] 
  } [ , ... ]
  [ [  
      INNER | { { LEFT | RIGHT | FULL } [ OUTER ] } 
    ] JOIN <table_reference> [ ON <search_condition> ] [ [ AS ] <identifier> ] 
  ] [ ... ] 
  [ WHERE <search_condition> ]
  [ GROUP BY <column_reference> [ , ... ]
  [ HAVING <search_condition> ]
  [ UNION [ ALL ] <select_statement> ]
  [ 
    ORDER BY 
    <column_reference> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ]
  ]
  [ 
    LIMIT <expression>
    [ 
      { OFFSET | , }
      <expression> 
    ]
  ] 
} | SCOPE_IDENTITY() 

<expression> ::=
  | <column_reference>
  | @ <parameter> 
  | ?
  | COUNT( * | { [ DISTINCT ] <expression> } )
  | { AVG | MAX | MIN | SUM | COUNT } ( <expression> ) 
  | NULLIF ( <expression> , <expression> ) 
  | COALESCE ( <expression> , ... ) 
  | CASE <expression>
      WHEN { <expression> | <search_condition> } THEN { <expression> | NULL } [ ... ]
    [ ELSE { <expression> | NULL } ]
    END 
  | {RANK() | DENSE_RANK()} OVER ([PARTITION BY <column_reference>] {ORDER BY <column_reference>})
  | <literal>
  | <sql_function> 

<search_condition> ::= 
  {
    <expression> { = | > | < | >= | <= | <> | != | LIKE | NOT LIKE | IN | NOT IN | IS NULL | IS NOT NULL | AND | OR | CONTAINS | BETWEEN | IS DISTINCT FROM | IS NOT DISTINCT FROM } [ <expression> ]
  } [ { AND | OR } ... ] 

Examples

  1. Return all columns:
    SELECT * FROM [MyBucket].[MyScope].[Customer]
  2. Rename a column:
    SELECT [TotalDue] AS MY_TotalDue FROM [MyBucket].[MyScope].[Customer]
  3. Cast a column's data as a different data type:
    SELECT CAST(AnnualRevenue AS VARCHAR) AS Str_AnnualRevenue FROM [MyBucket].[MyScope].[Customer]
  4. Search data:
    SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'
  5. Return the number of items matching the query criteria:
    SELECT COUNT(*) AS MyCount FROM [MyBucket].[MyScope].[Customer] 
  6. Return the number of unique items matching the query criteria:
    SELECT COUNT(DISTINCT TotalDue) FROM [MyBucket].[MyScope].[Customer] 
  7. Return the unique items matching the query criteria:
    SELECT DISTINCT TotalDue FROM [MyBucket].[MyScope].[Customer] 
  8. Sort a result set in ascending order:
    SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer]  ORDER BY TotalDue ASC
  9. Restrict a result set to the specified number of rows:
    SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer] LIMIT 10 
  10. Parameterize a query to pass in inputs at execution time. This enables you to create prepared statements and mitigate SQL injection attacks.
    SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = @param
See Explicitly Caching Data for information on using the SELECT statement in offline mode.

Pseudo Columns

Some input-only fields are available in SELECT statements. These fields, called pseudo columns, do not appear as regular columns in the results, yet may be specified as part of the WHERE clause. You can use pseudo columns to access additional features from Couchbase.

    SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE PSEUDO = '@PSEUDO'
    

Aggregate Functions

For SELECT examples using aggregate functions, see Aggregate Functions.

JOIN Queries

See JOIN Queries for SELECT query examples using JOINs.

Date Literal Functions

Date Literal Functions contains SELECT examples with date literal functions.

Projection Functions

See Projection Functions for SELECT examples with projection functions.

Predicate Functions

For SELECT examples using predicate functions, see Predicate Functions.

CData Python Connector for Couchbase

Aggregate Functions

COUNT

Returns the number of rows matching the query criteria.

SELECT COUNT(*) FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'

COUNT(DISTINCT)

Returns the number of distinct, non-null field values matching the query criteria.

SELECT COUNT(DISTINCT Name) AS DistinctValues FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'

AVG

Returns the average of the column values.

SELECT TotalDue, AVG(AnnualRevenue) FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'  GROUP BY TotalDue

MIN

Returns the minimum column value.

SELECT MIN(AnnualRevenue), TotalDue FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345' GROUP BY TotalDue

MAX

Returns the maximum column value.

SELECT TotalDue, MAX(AnnualRevenue) FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345' GROUP BY TotalDue

SUM

Returns the total sum of the column values.

SELECT SUM(AnnualRevenue) FROM [MyBucket].[MyScope].[Customer] WHERE CustomerId = '12345'

CData Python Connector for Couchbase

JOIN Queries

The CData Python Connector for Couchbase supports standard SQL joins like the following examples.

Inner Join

An inner join selects only rows from both tables that match the join condition:

SELECT Customers.ContactName, Orders.OrderDate FROM Customers, Orders WHERE Customers.CustomerId=Orders.CustomerId

Left Join

A left join selects all rows in the FROM table and only matching rows in the JOIN table:

SELECT Customers.ContactName, Orders.OrderDate FROM Customers LEFT OUTER JOIN Orders ON Customers.CustomerId=Orders.CustomerId

CData Python Connector for Couchbase

INSERT Statements

To create new records, use INSERT statements.

INSERT Syntax

The INSERT statement specifies the columns to be inserted and the new column values. You can specify the column values in a comma-separated list in the VALUES clause, as shown in the following example:

INSERT INTO <table_name> 
( <column_reference> [ , ... ] )
VALUES 
( { <expression> | NULL } [ , ... ] ) 
  

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>
The following is an example query:
INSERT INTO [MyBucket].[MyScope].[Customer] (TotalDue) VALUES ('John')

CData Python Connector for Couchbase

UPDATE Statements

To modify existing records, use UPDATE statements.

Update Syntax

The UPDATE statement takes as input a comma-separated list of columns and new column values as name-value pairs in the SET clause, as shown in the following example:

UPDATE <table_name> SET <select_statement> | {<column_reference> = <expression> [ , ... ]} WHERE { Id = <expression>  } [ { AND | OR } ... ] 

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>

The following is an example query:

UPDATE [MyBucket].[MyScope].[Customer] SET TotalDue='John' WHERE Id = @myId

CData Python Connector for Couchbase

DELETE Statements

To delete information from a table, use DELETE statements.

DELETE Syntax

The DELETE statement requires the table name in the FROM clause and the row's primary key in the WHERE clause, as shown in the following example:

<delete_statement> ::= DELETE FROM <table_name> WHERE { Id = <expression> } [ { AND | OR } ... ]

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>

The following is an example query:

DELETE FROM [MyBucket].[MyScope].[Customer] WHERE Id = @myId

CData Python Connector for Couchbase

CACHE Statements

When caching is enabled, CACHE statements provide complete control over the data that is cached and the table to which it is cached. The CACHE statement executes the SELECT statement specified and caches its results to a table with the same name in the cache database or to table specified in <cached_table_name>. The connector updates or inserts rows to the cache depending on whether or not they already exist in the cache, so the primary key, which is used to identify existing rows, must be included in the selected columns.

See Caching Data for more information on different caching strategies.

CACHE Statement Syntax

The cache statement may include the following options that alter its behavior:

CACHE [ <cached_table_name> ] [ WITH TRUNCATE | AUTOCOMMIT | SCHEMA ONLY | DROP EXISTING | ALTER SCHEMA ] <select_statement> 

WITH TRUNCATE

If this option is set, the connector removes existing rows in the cache table before adding the selected rows. Use this option if you want to refresh the entire cache table but keep its existing schema.

AUTOCOMMIT

If this option is set, the connector commits each row individually. Use this option if you want to ignore the rows that could not be cached due to some reason. By default, the entire result set is cached as a single transaction.

DROP EXISTING

If this option is set, the connector drops the existing cache table before caching the new results. Use this option if you want to refresh the entire cache table, including its schema.

SCHEMA ONLY

If this option is set, the connector creates the cache table based on the SELECT statement without executing the query.

ALTER SCHEMA

If this option is set, the connector alters the schema of the existing table in the cache if it does not match the schema of the SELECT statement. This option results in new columns or dropped columns, if the schema of the SELECT statement does not match the cached table.

Common Queries

Use the following cache statement to cache all rows of a table:

CACHE SELECT * FROM [MyBucket].[MyScope].[Customer]

Use the following cache statement to cache all rows of a table into the cache table Cached[MyBucket].[MyScope].[Customer]:

CACHE Cached[MyBucket].[MyScope].[Customer] SELECT * FROM [MyBucket].[MyScope].[Customer]

Use the following cache statement for incremental caching. The DateModified column may not exist in all tables. The cache statement shows how incremental caching would work if there were such a column. Also, notice that, in this case, the WITH TRUNCATE and DROP EXISTING options are specifically omitted, which would have deleted all existing rows.

CACHE Cached[MyBucket].[MyScope].[Customer] SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE DateModified > '2013-04-04'

Use the following cache statements to create a table with all available columns that will then cache only a few of them. The sequence of statements cache only Name and TotalDue even though the cache table Cached[MyBucket].[MyScope].[Customer] has all the columns in [MyBucket].[MyScope].[Customer].

CACHE Cached[MyBucket].[MyScope].[Customer] SCHEMA ONLY SELECT * FROM [MyBucket].[MyScope].[Customer]
CACHE Cached[MyBucket].[MyScope].[Customer] SELECT Name, TotalDue FROM [MyBucket].[MyScope].[Customer]

CData Python Connector for Couchbase

EXECUTE Statements

To execute stored procedures, you can use EXECUTE or EXEC statements.

EXEC and EXECUTE assign stored procedure inputs, referenced by name, to values or parameter names.

Stored Procedure Syntax

To execute a stored procedure as an SQL statement, use the following syntax:

 
{ EXECUTE | EXEC } <stored_proc_name> 
{
  [ @ ] <input_name> = <expression>
} [ , ... ]

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>

Example Statements

Reference stored procedure inputs by name:

EXECUTE my_proc @second = 2, @first = 1, @third = 3;

Execute a parameterized stored procedure statement:

EXECUTE my_proc second = @p1, first = @p2, third = @p3; 

CData Python Connector for Couchbase

PIVOT and UNPIVOT

PIVOT and UNPIVOT can be used to change a table-valued expression into another table.

PIVOT

PIVOT rotates a table-value expression by turning unique values from one column into multiple columns in the output. PIVOT can run aggregations where required on any column value.
PIVOT Synax

 
"SELECT 'AverageCost' AS Cost_Sorted_By_Production_Days, [0], [1], [2], [3], [4]
FROM
(
SELECT DaysToManufacture, StandardCost
FROM Production.Product
) AS SourceTable
PIVOT
(
AVG(StandardCost)
FOR DaysToManufacture IN ([0], [1], [2], [3], [4])
) AS PivotTable;"

UNPIVOT

UNPIVOT carries out nearly the opposite to PIVOT by rotating columns of a table-valued expressions into column values.
UNPIVOT Sytax

 
"SELECT VendorID, Employee, Orders
FROM
(SELECT VendorID, Emp1, Emp2, Emp3, Emp4, Emp5
FROM pvt) p
UNPIVOT
(Orders FOR Employee IN
(Emp1, Emp2, Emp3, Emp4, Emp5)
)AS unpvt;"

For further information on PIVOT and UNPIVOT, see FROM clause plus JOIN, APPLY, PIVOT (Transact-SQL)

CData Python Connector for Couchbase

Data Model

Overview

Depending upon the connection settings being used, the connector can present several different mappings between Couchbase entities and relational tables and views. For more details on each of these capabilities, refer to the NoSQL portion of this documentation.

  • When connecting to the N1QL query service, the connector models Couchbase buckets as relational tables. In addition, if TypeDetectionScheme is set to DocType or Infer, the connector will present different document flavors in each bucket as their own tables.
  • When connecting to the Analytics service, the connector models Couchbase datasets as relational views.
  • When connecting with either service, the connector can expose arrays of data as child tables or views.

Please see the Automatic Schema Discovery section for more details on how flavor and child tables are exposed. In addition, the NewChildJoinsMode connection property is recommended for workflows that make heavy use of child tables. The documentation for that connection property details the improvements it makes to the connector data model.

Dataverses, Scopes and Collections

Couchbase has different ways of grouping buckets and datasets depending on the CouchbaseService and version of Couchbase you are connecting to:

  • Couchbase organizes Analytics datsets into groups called dataverses. By default the connector exposes datasets from all dataverses using compound names like Default.users as described in DataverseSeparator. It is important to remember that these compound names must be quoted when used in queries, for example SELECT * FROM [Default.users]
  • You may also set the Dataverse property to limit the the connector to exposing a single dataverse. This disables compound names so view names will not include the dataset.
  • When connecting to Couchbase 7 and above, the connector will use the scope, collection and bucket/dataset name to build table and view names. For example, a table with a name like crm.accounts.customers exposes the customers collection under the accounts scope of the crm bucket. These must be quoted the same as other compound names when used in queries, for example SELECT * FROM [crm.accounts.customers]

Live Metadata

All of the schemas provided by the connector are dynamically retrieved from Couchbase, so any changes in the buckets or fields within Couchbase will be reflected in the connector the next time you connect. You may also issue a reset query to refresh schemas without having to close the connection:

RESET SCHEMA CACHE

CData Python Connector for Couchbase

Stored Procedures

Stored procedures are function-like interfaces that extend the functionality of the connector beyond simple SELECT/INSERT/UPDATE/DELETE operations with Couchbase.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Couchbase, along with an indication of whether the procedure succeeded or failed.

CData Python Connector for Couchbase Stored Procedures

Name Description
AddDocument Upsert entire JSON documents to Couchbase as-is.
CreateBucket Creates a new bucket in CouchBase.
CreateCollection Creates a collection under an existing scope
CreateSchema Creates a schema definition of a table in Couchbase. Results may change depending of the value of FlattenObjects, FlattenArrays, and TypeDetectionScheme.
CreateScope Creates a scope under an existing bucket
CreateSearchIndex Creates a search index with the Search Service API in Couchbase.
CreateUserTable An internal operation used when GenerateSchemaFiles=OnCreate
DeleteBucket Deletes a bucket (and all its collections and scopes, where supported)
DeleteCollection Deletes a collection (Couchbase 7 and up)
DeleteScope Deletes a scope and all its collections (Couchbase 7 and up)
ExecuteSearchIndex Execute a search on an index using the Search Service API in Couchbase.
FlushBucket Removes all documents from a bucket in Couchbase.
ListIndices Lists all indices available in Couchbase
ManageIndices Creates/Drops an index in a target bucket in Couchbase.

CData Python Connector for Couchbase

AddDocument

Upsert entire JSON documents to Couchbase as-is.

Input

Name Type Required Description
BucketName String True The bucket to insert the document into.
SourceTable String False The name of the temp table containing ID and Document columns. Required if no ID is specified.
ID String False The primary key to insert the document under. Required if no SourceTable is specified.
Document String False The JSON text of the document to insert. Required if not SourceTable is specified.

Result Set Columns

Name Type Description
RowsAffected String The number of rows successfully updated

CData Python Connector for Couchbase

CreateBucket

Creates a new bucket in CouchBase.

Creating Buckets

Buckets using @AuthType 'none' can be created by specifying only the @Name, @AuthType, @BucketType, and @RamQuotaMB. The @ProxyPort option may also be required, depending upon what version of Couchbase you are connecting to.

EXECUTE CreateBucket
  @Name = 'Players',
  @AuthType = 'NONE',
  @BucketType = 'COUCHBASE',
  @RamQuotaMB = 100,
  @ProxyPort = 1234

When creating a bucket with @AuthType 'sasl', the @ProxyPort must not be provided, and the @SaslPassword is optional:

EXECUTE CreateBucket
  @Name = 'Players',
  @AuthType = 'SASL',
  @BucketType = 'COUCHBASE',
  @RamQuotaMB = 100

All other parameters can be used regardless of what @AuthType you provide.

Input

Name Type Required Description
Name String True The name of the bucket to create.
AuthType String True The type of authentication to use can be sasl or none.
BucketType String True The type of the bucket, can be memcached or couchbase.
EvictionPolicy String False What to evict from the cache if the bucket is full, can be fullEviction or valueOnly
FlushEnabled String False Enables or disables flush all support, can be 0 or 1.
ParallelDBAndViewCompaction String False Enables simultaneous compactions of the database and the views, can be true or false.
ProxyPort String False The proxy port, must be unused, required if authorization is not SASL.
RamQuotaMB String True The amount of RAM to allocate to the bucket, in megabytes.
ReplicaIndex String False Enables or disables replicate indexes, can be 1 or 0.
ReplicaNumber String False A number between 0 and 3, specifies number of replicas.
SaslPassword String False SASL password, may be provided if the authentication type is SASL.
ThreadsNumber String False A number between 2 and 8, specifies number of concurrent readers/writers.
CompressionMode String False Either Off (no compression), Passive (documents inserted compressed stay comressed) or Active (server can compress any document). On Couchbase Enterprise, Passive is the default.
ConflictResolutionType String False How the server will resolve conflicts between cluster nodes. Either lww (timestamp-based resolution) or seqno (revision ID-based resolution). Defaults to seqno on Couchbase Enterprise.

Result Set Columns

Name Type Description
Success String Whether or not the bucket was successfully created.

CData Python Connector for Couchbase

CreateCollection

Creates a collection under an existing scope

Input

Name Type Required Description
Bucket String True The name of the bucket containing the collection.
Scope String True The name of the scope containing the collection.
Name String True The name of the collection to create.

Result Set Columns

Name Type Description
Success Bool Whether or not the collection was successfully created.

CData Python Connector for Couchbase

CreateSchema

Creates a schema definition of a table in Couchbase. Results may change depending of the value of FlattenObjects, FlattenArrays, and TypeDetectionScheme.

CreateSchema

Creates a local schema file (.rsd) from an existing table or view in the data model.

The schema file is created in the directory set in the Location connection property when this procedure is executed. You can edit the file to include or exclude columns, rename columns, or adjust column datatypes.

The connector checks the Location to determine if the names of any .rsd files match a table or view in the data model. If there is a duplicate, the schema file will take precedence over the default instance of this table in the data model. If a schema file is present in Location that does not match an existing table or view, a new table or view entry is added to the data model of the connector.

Input

Name Type Required Description
TableName String True The name of the table.
FileName String False The full file path and name of the schema to generate. Ex : 'C:\\Users\\User\\Desktop\\Couchbase\\sheet.rsd'
Overwrite String False Will delete any existing schema file for this table.

Result Set Columns

Name Type Description
Result String Whether or not the schema was successfully built.
FileData String The content of the schema encoded as base64. Only returned if the FileName and FileStream are not provided.

CData Python Connector for Couchbase

CreateScope

Creates a scope under an existing bucket

Input

Name Type Required Description
Bucket String True The name of the bucket containing the scope.
Name String True The name of the scope to create.

Result Set Columns

Name Type Description
Success Bool Whether or not the scope was successfully created.

CData Python Connector for Couchbase

CreateSearchIndex

Creates a search index with the Search Service API in Couchbase.

Input

Name Type Required Description
SearchIndexName String True The Name of the search Index.
SearchIndex String True The JSON text of the document to insert. Required if not SourceTable is specified.

Result Set Columns

Name Type Description
Success String Whether or not the index was successfully created or dropped.

CData Python Connector for Couchbase

CreateUserTable

An internal operation used when GenerateSchemaFiles=OnCreate

This stored procedure is an internal operation that gets executed when running CREATE TABLE statements and GenerateSchemaFiles is set to OnCreate.

Note: This procedure makes use of indexed parameters. Indexed parameters facilitate providing multiple instances a single parameter as inputs for the procedure.

Suppose there is an input parameter named Param#. To input multiple instances of an indexed parameter like this, execute:

EXEC ProcedureName Param#1 = "value1", Param#2 = "value2", Param#3 = "value3"

In the Input table below, indexed parameters are denoted with a '#' character at the end of their names.

Input

Name Type Required Description
CreateNotExist String False Whether an existing table is an error or not
TableName String False The name of the table to create
ColumnNames String False For each column, its name
ColumnDataTypes String False For each column, its type
ColumnSizes String False For each column, its size (ignored)
ColumnScales String False For each column, its scale (ignored)
ColumnIsNulls String False For each column, whether it allows NULLs (ignored)
ColumnDefaults String False For each column, its default value (ignored)
Location String False Where the schema file is generated

Result Set Columns

Name Type Description
AffectedTables String The number of tables created, either 0 or 1

CData Python Connector for Couchbase

DeleteBucket

Deletes a bucket (and all its collections and scopes, where supported)

Input

Name Type Required Description
Name String True The name of the bucket to delete.

Result Set Columns

Name Type Description
Success Bool Whether or not the bucket was successfully deleted.

CData Python Connector for Couchbase

DeleteCollection

Deletes a collection (Couchbase 7 and up)

Input

Name Type Required Description
Bucket String True The name of the bucket containing the collection.
Scope String True The name of the scope containing the collection.
Name String True The name of the collection to delete.

Result Set Columns

Name Type Description
Success Bool Whether or not the collection was successfully deleted.

CData Python Connector for Couchbase

DeleteScope

Deletes a scope and all its collections (Couchbase 7 and up)

Input

Name Type Required Description
Bucket String True The name of the bucket containing the scope.
Name String True The name of the scope to delete.

Result Set Columns

Name Type Description
Success Bool Whether or not the scope was successfully deleted.

CData Python Connector for Couchbase

ExecuteSearchIndex

Execute a search on an index using the Search Service API in Couchbase.

Input

Name Type Required Description
SearchIndexName String True The Name of the search Index.
QueryRequest String True The JSON text of the document to insert. Required if not SourceTable is specified.

Result Set Columns

Name Type Description
Success String Whether or not the index was successfully created or dropped.

CData Python Connector for Couchbase

FlushBucket

Removes all documents from a bucket in Couchbase.

Input

Name Type Required Description
Name String True The name of the bucket to delete. Flush must be enabled on this bucket.

Result Set Columns

Name Type Description
Success Bool Whether or not the bucket was successfully flushed.

CData Python Connector for Couchbase

ListIndices

Lists all indices available in Couchbase

Result Set Columns

Name Type Description
Id String The unique index ID
Datastore_id String The server hosting the indexed bucket
Namespace_id String The pool hosting the indexed bucket
Bucket_id String The bucket the index applies to if the index applies to a collection (Couchbase 7 and up). NULL otherwise.
Scope_id String The scope the index applies to if the index applies to a collection (Couchbase 7 and up). NULL otherwise.
Keyspace_id String The collection the index applies to, if the index applis to a collection (Couchbase 7 and up). The bucket the index applies to otherwise.
Index_key String A list of keys participating in the index
Condition String The N1QL filter that the index applies to
Is_primary String Whether the index is on the primary key
Name String The name of the index
State String Whether the index is available
Using String Whether the index is backed by GSI or a view

CData Python Connector for Couchbase

ManageIndices

Creates/Drops an index in a target bucket in Couchbase.

Building Indices

An anonymous primary index can be created with these parameters:

EXECUTE ManageIndices
  @BucketName = 'Players'
  @Action = 'CREATE'
  @IsPrimary = 'true'
  @IndexType = 'VIEW'

This is the same as executing this N1QL:

CREATE PRIMARY INDEX ON `Players` USING VIEW

A named primary index can be created by specifying an @Name, in addition to the parameters listed above:

EXECUTE ManageIndices
  @BucketName = 'Players'
  @Action = 'CREATE'
  @IsPrimary = 'true'
  @Name = 'Players_primary'
  @IndexType = 'VIEW'

A secondary index can be created by setting @IsPrimary to false and providing at least one expression.

EXECUTE ManageIndices
  @BucketName = 'Players',
  @Action = 'CREATE',
  @IsPrimary = 'false',
  @Name = 'Players_playtime_score',
  @Expressions = '["score", "playtime"]'

This is the same as running the following N1QL:

CREATE INDEX `Players_playtime_score` ON `Players`(score, playtime) USING GSI;

Multiple nodes and filters can also be provied to generate more complex indices. They must be provided as JSON lists:

EXECUTE ManageIndices
  @BucketName = 'Players',
  @Name = 'TopPlayers',
  @Expressions = '["score", "playtime"]',
  @Filter = '["topscore > 1000", "playtime > 600"]',
  @Nodes = '["127.0.0.1:8091", "192.168.0.100:8091"]'

This is the same as running the following N1QL:

CREATE INDEX `TopPlayers` ON `Players`(score, playtime) WHERE topscore > 1000 AND playtime > 600 USING GSI WITH { "nodes": ["127.0.0.1:8091", "192.168.0.100:8091"]};

Input

Name Type Required Description
BucketName String True The target bucket to create or drop the the index from.
ScopeName String False The target scope to create or drop the index from (Couchbase 7 and up)
CollectionName String False The target collection to create or drop the index from (Couchbase 7 and up)
Action String True Specifies which action to perform on the index, can be Create or Drop.
Expressions String False A list of expressions or functions, encoded as JSON, that the index will be based off of. At least one is required if IsPrimary is set to false and the action is Create.
Name String False The name of the index to create or drop, required if IsPrimary is set to false.
IsPrimary String False Specifies wether the index should be a primary index.

The default value is true.

Filters String False A list of filters, encoded as JSON, to apply on the index.
IndexType String False The type of index to create, can be GSI or View, only used if the action is Create.

The default value is GSI.

ViewName String False Deprecated, included for compatibility only. Does nothing.
Nodes String False A list, encoded as JSON, of nodes to contain the index, must contain the port. Only used if the action is Create.
NumReplica String False How many replicas to create among the index nodes in the cluster.

Result Set Columns

Name Type Description
Success String Whether or not the index was successfully created or dropped.

CData Python Connector for Couchbase

System Tables

You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.

Schema Tables

The following tables return database metadata for Couchbase:

Data Source Tables

The following tables return information about how to connect to and query the data source:

  • sys_connection_props: Returns information on the available connection properties.
  • sys_sqlinfo: Describes the SELECT queries that the connector can offload to the data source.

Query Information Tables

The following table returns query statistics for data modification queries

  • sys_identity: Returns information about batch operations or single updates.

CData Python Connector for Couchbase

sys_catalogs

Lists the available databases.

The following query retrieves all databases determined by the connection string:

SELECT * FROM sys_catalogs

Columns

Name Type Description
CatalogName String The database name.

CData Python Connector for Couchbase

sys_schemas

Lists the available schemas.

The following query retrieves all available schemas:

          SELECT * FROM sys_schemas
          

Columns

Name Type Description
CatalogName String The database name.
SchemaName String The schema name.

CData Python Connector for Couchbase

sys_tables

Lists the available tables.

The following query retrieves the available tables and views:

          SELECT * FROM sys_tables
          

Columns

Name Type Description
CatalogName String The database containing the table or view.
SchemaName String The schema containing the table or view.
TableName String The name of the table or view.
TableType String The table type (table or view).
Description String A description of the table or view.
IsUpdateable Boolean Whether the table can be updated.
IsInsertable Boolean Whether the table can be inserted into.
IsDeleteable Boolean Whether rows can be deleted from the table.

CData Python Connector for Couchbase

sys_tablecolumns

Describes the columns of the available tables and views.

The following query returns the columns and data types for the [MyBucket].[MyScope].[Customer] table:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName = '[MyBucket].[MyScope].[Customer]' 

Columns

Name Type Description
CatalogName String The name of the database containing the table or view.
SchemaName String The schema containing the table or view.
TableName String The name of the table or view containing the column.
ColumnName String The column name.
DataTypeName String The data type name.
DataType Int32 An integer indicating the data type. This value is determined at run time based on the environment.
Length Int32 The storage size of the column.
DisplaySize Int32 The designated column's normal maximum width in characters.
NumericPrecision Int32 The maximum number of digits in numeric data. The column length in characters for character and date-time data.
NumericScale Int32 The column scale or number of digits to the right of the decimal point.
IsNullable Boolean Whether the column can contain null.
Description String A brief description of the column.
Ordinal Int32 The sequence number of the column.
IsAutoIncrement String Whether the column value is assigned in fixed increments.
IsGeneratedColumn String Whether the column is generated.
IsHidden Boolean Whether the column is hidden.
IsArray Boolean Whether the column is an array.
IsReadOnly Boolean Whether the column is read-only.
IsKey Boolean Indicates whether a field returned from sys_tablecolumns is the primary key of the table.
ColumnType String The role or classification of the column in the schema. Possible values include SYSTEM, LINKEDCOLUMN, NAVIGATIONKEY, REFERENCECOLUMN, and NAVIGATIONPARENTCOLUMN.
ColumnCapabilities Int32 A bit mask denoting the column's write capabilities. The value is the sum of the following: 1 if the column is required for INSERTs, 2 if the column is allowed for INSERTs, and 4 if the column is allowed for UPDATEs. A value of 0 indicates that the write capabilities of the column are unknown or that the column is read-only.

CData Python Connector for Couchbase

sys_procedures

Lists the available stored procedures.

The following query retrieves the available stored procedures:

          SELECT * FROM sys_procedures
          

Columns

Name Type Description
CatalogName String The database containing the stored procedure.
SchemaName String The schema containing the stored procedure.
ProcedureName String The name of the stored procedure.
Description String A description of the stored procedure.
ProcedureType String The type of the procedure, such as PROCEDURE or FUNCTION.

CData Python Connector for Couchbase

sys_procedureparameters

Describes stored procedure parameters.

The following query returns information about all of the input parameters for the SelectEntries stored procedure:

SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'SelectEntries' AND Direction = 1 OR Direction = 2

To include result set columns in addition to the parameters, set the IncludeResultColumns pseudo column to True:

SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'SelectEntries' AND IncludeResultColumns='True'

Columns

Name Type Description
CatalogName String The name of the database containing the stored procedure.
SchemaName String The name of the schema containing the stored procedure.
ProcedureName String The name of the stored procedure containing the parameter.
ColumnName String The name of the stored procedure parameter.
Direction Int32 An integer corresponding to the type of the parameter: input (1), input/output (2), or output(4). input/output type parameters can be both input and output parameters.
DataType Int32 An integer indicating the data type. This value is determined at run time based on the environment.
DataTypeName String The name of the data type.
NumericPrecision Int32 The maximum precision for numeric data. The column length in characters for character and date-time data.
Length Int32 The number of characters allowed for character data. The number of digits allowed for numeric data.
NumericScale Int32 The number of digits to the right of the decimal point in numeric data.
IsNullable Boolean Whether the parameter can contain null.
IsRequired Boolean Whether the parameter is required for execution of the procedure.
IsArray Boolean Whether the parameter is an array.
Description String The description of the parameter.
Ordinal Int32 The index of the parameter.
Values String The values you can set in this parameter are limited to those shown in this column. Possible values are comma-separated.
SupportsStreams Boolean Whether the parameter represents a file that you can pass as either a file path or a stream.
IsPath Boolean Whether the parameter is a target path for a schema creation operation.
Default String The value used for this parameter when no value is specified.
SpecificName String A label that, when multiple stored procedures have the same name, uniquely identifies each identically-named stored procedure. If there's only one procedure with a given name, its name is simply reflected here.
IsCDataProvided Boolean Whether the procedure is added/implemented by CData, as opposed to being a native Couchbase procedure.

Pseudo-Columns

Name Type Description
IncludeResultColumns Boolean Whether the output should include columns from the result set in addition to parameters. Defaults to False.

CData Python Connector for Couchbase

sys_keycolumns

Describes the primary and foreign keys.

The following query retrieves the primary key for the [MyBucket].[MyScope].[Customer] table:

         SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='[MyBucket].[MyScope].[Customer]' 
          

Columns

Name Type Description
CatalogName String The name of the database containing the key.
SchemaName String The name of the schema containing the key.
TableName String The name of the table containing the key.
ColumnName String The name of the key column.
IsKey Boolean Whether the column is a primary key in the table referenced in the TableName field.
IsForeignKey Boolean Whether the column is a foreign key referenced in the TableName field.
PrimaryKeyName String The name of the primary key.
ForeignKeyName String The name of the foreign key.
ReferencedCatalogName String The database containing the primary key.
ReferencedSchemaName String The schema containing the primary key.
ReferencedTableName String The table containing the primary key.
ReferencedColumnName String The column name of the primary key.

CData Python Connector for Couchbase

sys_foreignkeys

Describes the foreign keys.

The following query retrieves all foreign keys which refer to other tables:

         SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
          

Columns

Name Type Description
CatalogName String The name of the database containing the key.
SchemaName String The name of the schema containing the key.
TableName String The name of the table containing the key.
ColumnName String The name of the key column.
PrimaryKeyName String The name of the primary key.
ForeignKeyName String The name of the foreign key.
ReferencedCatalogName String The database containing the primary key.
ReferencedSchemaName String The schema containing the primary key.
ReferencedTableName String The table containing the primary key.
ReferencedColumnName String The column name of the primary key.
ForeignKeyType String Designates whether the foreign key is an import (points to other tables) or export (referenced from other tables) key.

CData Python Connector for Couchbase

sys_primarykeys

Describes the primary keys.

The following query retrieves the primary keys from all tables and views:

         SELECT * FROM sys_primarykeys
          

Columns

Name Type Description
CatalogName String The name of the database containing the key.
SchemaName String The name of the schema containing the key.
TableName String The name of the table containing the key.
ColumnName String The name of the key column.
KeySeq String The sequence number of the primary key.
KeyName String The name of the primary key.

CData Python Connector for Couchbase

sys_indexes

Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.

The following query retrieves all indexes that are not primary keys:

          SELECT * FROM sys_indexes WHERE IsPrimary='false'
          

Columns

Name Type Description
CatalogName String The name of the database containing the index.
SchemaName String The name of the schema containing the index.
TableName String The name of the table containing the index.
IndexName String The index name.
ColumnName String The name of the column associated with the index.
IsUnique Boolean True if the index is unique. False otherwise.
IsPrimary Boolean True if the index is a primary key. False otherwise.
Type Int16 An integer value corresponding to the index type: statistic (0), clustered (1), hashed (2), or other (3).
SortOrder String The sort order: A for ascending or D for descending.
OrdinalPosition Int16 The sequence number of the column in the index.

CData Python Connector for Couchbase

sys_connection_props

Returns information on the available connection properties and those set in the connection string.

The following query retrieves all connection properties that have been set in the connection string or set through a default value:

SELECT * FROM sys_connection_props WHERE Value <> ''

Columns

Name Type Description
Name String The name of the connection property.
ShortDescription String A brief description.
Type String The data type of the connection property.
Default String The default value if one is not explicitly set.
Values String A comma-separated list of possible values. A validation error is thrown if another value is specified.
Value String The value you set or a preconfigured default.
Required Boolean Whether the property is required to connect.
Category String The category of the connection property.
IsSessionProperty String Whether the property is a session property, used to save information about the current connection.
Sensitivity String The sensitivity level of the property. This informs whether the property is obfuscated in logging and authentication forms.
PropertyName String A camel-cased truncated form of the connection property name.
Ordinal Int32 The index of the parameter.
CatOrdinal Int32 The index of the parameter category.
Hierarchy String Shows dependent properties associated that need to be set alongside this one.
Visible Boolean Informs whether the property is visible in the connection UI.
ETC String Various miscellaneous information about the property.

CData Python Connector for Couchbase

sys_sqlinfo

Describes the SELECT query processing that the connector can offload to the data source.

See SQL Compliance for SQL syntax details.

Discovering the Data Source's SELECT Capabilities

Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.

NameDescriptionPossible Values
AGGREGATE_FUNCTIONSSupported aggregation functions.AVG, COUNT, MAX, MIN, SUM, DISTINCT
COUNTWhether COUNT function is supported.YES, NO
IDENTIFIER_QUOTE_OPEN_CHARThe opening character used to escape an identifier.[
IDENTIFIER_QUOTE_CLOSE_CHARThe closing character used to escape an identifier.]
SUPPORTED_OPERATORSA list of supported SQL operators.=, >, <, >=, <=, <>, !=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL, AND, OR
GROUP_BYWhether GROUP BY is supported, and, if so, the degree of support.NO, NO_RELATION, EQUALS_SELECT, SQL_GB_COLLATE
OJ_CAPABILITIESThe supported varieties of outer joins supported.NO, LEFT, RIGHT, FULL, INNER, NOT_ORDERED, ALL_COMPARISON_OPS
OUTER_JOINSWhether outer joins are supported.YES, NO
SUBQUERIESWhether subqueries are supported, and, if so, the degree of support.NO, COMPARISON, EXISTS, IN, CORRELATED_SUBQUERIES, QUANTIFIED
STRING_FUNCTIONSSupported string functions.LENGTH, CHAR, LOCATE, REPLACE, SUBSTRING, RTRIM, LTRIM, RIGHT, LEFT, UCASE, SPACE, SOUNDEX, LCASE, CONCAT, ASCII, REPEAT, OCTET, BIT, POSITION, INSERT, TRIM, UPPER, REGEXP, LOWER, DIFFERENCE, CHARACTER, SUBSTR, STR, REVERSE, PLAN, UUIDTOSTR, TRANSLATE, TRAILING, TO, STUFF, STRTOUUID, STRING, SPLIT, SORTKEY, SIMILAR, REPLICATE, PATINDEX, LPAD, LEN, LEADING, KEY, INSTR, INSERTSTR, HTML, GRAPHICAL, CONVERT, COLLATION, CHARINDEX, BYTE
NUMERIC_FUNCTIONSSupported numeric functions.ABS, ACOS, ASIN, ATAN, ATAN2, CEILING, COS, COT, EXP, FLOOR, LOG, MOD, SIGN, SIN, SQRT, TAN, PI, RAND, DEGREES, LOG10, POWER, RADIANS, ROUND, TRUNCATE
TIMEDATE_FUNCTIONSSupported date/time functions.NOW, CURDATE, DAYOFMONTH, DAYOFWEEK, DAYOFYEAR, MONTH, QUARTER, WEEK, YEAR, CURTIME, HOUR, MINUTE, SECOND, TIMESTAMPADD, TIMESTAMPDIFF, DAYNAME, MONTHNAME, CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, EXTRACT
REPLICATION_SKIP_TABLESIndicates tables skipped during replication.
REPLICATION_TIMECHECK_COLUMNSA string array containing a list of columns which will be used to check for (in the given order) to use as a modified column during replication.
IDENTIFIER_PATTERNString value indicating what string is valid for an identifier.
SUPPORT_TRANSACTIONIndicates if the provider supports transactions such as commit and rollback.YES, NO
DIALECTIndicates the SQL dialect to use.
KEY_PROPERTIESIndicates the properties which identify the uniform database.
SUPPORTS_MULTIPLE_SCHEMASIndicates if multiple schemas may exist for the provider.YES, NO
SUPPORTS_MULTIPLE_CATALOGSIndicates if multiple catalogs may exist for the provider.YES, NO
DATASYNCVERSIONThe CData Data Sync version needed to access this driver.Standard, Starter, Professional, Enterprise
DATASYNCCATEGORYThe CData Data Sync category of this driver.Source, Destination, Cloud Destination
SUPPORTSENHANCEDSQLWhether enhanced SQL functionality beyond what is offered by the API is supported.TRUE, FALSE
SUPPORTS_BATCH_OPERATIONSWhether batch operations are supported.YES, NO
SQL_CAPAll supported SQL capabilities for this driver.SELECT, INSERT, DELETE, UPDATE, TRANSACTIONS, ORDERBY, OAUTH, ASSIGNEDID, LIMIT, LIKE, BULKINSERT, COUNT, BULKDELETE, BULKUPDATE, GROUPBY, HAVING, AGGS, OFFSET, REPLICATE, COUNTDISTINCT, JOINS, DROP, CREATE, DISTINCT, INNERJOINS, SUBQUERIES, ALTER, MULTIPLESCHEMAS, GROUPBYNORELATION, OUTERJOINS, UNIONALL, UNION, UPSERT, GETDELETED, CROSSJOINS, GROUPBYCOLLATE, MULTIPLECATS, FULLOUTERJOIN, MERGE, JSONEXTRACT, BULKUPSERT, SUM, SUBQUERIESFULL, MIN, MAX, JOINSFULL, XMLEXTRACT, AVG, MULTISTATEMENTS, FOREIGNKEYS, CASE, LEFTJOINS, COMMAJOINS, WITH, LITERALS, RENAME, NESTEDTABLES, EXECUTE, BATCH, BASIC, INDEX
PREFERRED_CACHE_OPTIONSA string value specifies the preferred cacheOptions.
ENABLE_EF_ADVANCED_QUERYIndicates if the driver directly supports advanced queries coming from Entity Framework. If not, queries will be handled client side.YES, NO
PSEUDO_COLUMNSA string array indicating the available pseudo columns.
MERGE_ALWAYSIf the value is true, The Merge Mode is forcibly executed in Data Sync.TRUE, FALSE
REPLICATION_MIN_DATE_QUERYA select query to return the replicate start datetime.
REPLICATION_MIN_FUNCTIONAllows a provider to specify the formula name to use for executing a server side min.
REPLICATION_START_DATEAllows a provider to specify a replicate startdate.
REPLICATION_MAX_DATE_QUERYA select query to return the replicate end datetime.
REPLICATION_MAX_FUNCTIONAllows a provider to specify the formula name to use for executing a server side max.
IGNORE_INTERVALS_ON_INITIAL_REPLICATEA list of tables which will skip dividing the replicate into chunks on the initial replicate.
CHECKCACHE_USE_PARENTIDIndicates whether the CheckCache statement should be done against the parent key column.TRUE, FALSE
CREATE_SCHEMA_PROCEDURESIndicates stored procedures that can be used for generating schema files.

The following query retrieves the operators that can be used in the WHERE clause:

SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'
Note that individual tables may have different limitations or requirements on the WHERE clause; refer to the Data Model section for more information.

Columns

Name Type Description
NAME String A component of SQL syntax, or a capability that can be processed on the server.
VALUE String Detail on the supported SQL or SQL syntax.

CData Python Connector for Couchbase

sys_identity

Returns information about attempted modifications.

The following query retrieves the Ids of the modified rows in a batch operation:

         SELECT * FROM sys_identity
          

Columns

Name Type Description
Id String The database-generated Id returned from a data modification operation.
Batch String An identifier for the batch. 1 for a single operation.
Operation String The result of the operation in the batch: INSERTED, UPDATED, or DELETED.
Message String SUCCESS or an error message if the update in the batch failed.

CData Python Connector for Couchbase

sys_information

Describes the available system information.

The following query retrieves all columns:

SELECT * FROM sys_information

Columns

NameTypeDescription
ProductStringThe name of the product.
VersionStringThe version number of the product.
DatasourceStringThe name of the datasource the product connects to.
NodeIdStringThe unique identifier of the machine where the product is installed.
HelpURLStringThe URL to the product's help documentation.
LicenseStringThe license information for the product. (If this information is not available, the field may be left blank or marked as 'N/A'.)
LocationStringThe file path location where the product's library is stored.
EnvironmentStringThe version of the environment or rumtine the product is currently running under.
DataSyncVersionStringThe tier of CData Sync required to use this connector.
DataSyncCategoryStringThe category of CData Sync functionality (e.g., Source, Destination).

CData Python Connector for Couchbase

Connection String Options

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

For more information on establishing a connection, see Establishing a Connection.

Authentication


PropertyDescription
AuthSchemeThe type of authentication to use when connecting to Couchbase.
UserSpecifies the authenticating user's user ID.
PasswordSpecifies the authenticating user's password.
CredentialsFileUse this property if you need to provide credentials for multiple users or buckets. This file takes priority over other forms of authentication.
ServerThe address of the Couchbase server or servers to which you are connecting.
CouchbaseServiceDetermines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics.
ConnectionModeDetermines how to connect to the Couchbase server. Must be either Direct or Cloud.
DNSServerDetermines what DNS server to use when retrieving Couchbase Capella information.
N1QLPortThe port or URL for connecting to the Couchbase N1QL Endpoint.
AnalyticsPortThe port or URL for connecting to the Couchbase Analytics Endpoint.
WebConsolePortThe port or URL for connecting to the Couchbase Web Console.
SearchPortThe port or URL for connecting to the Couchbase Search Service Endpoint.

SSL


PropertyDescription
SSLClientCertSpecifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.
SSLClientCertTypeSpecifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.
SSLClientCertPasswordSpecifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.
SSLClientCertSubjectSpecifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.
UseSSLWhether to negotiate TLS/SSL when connecting to the Couchbase server.
SSLServerCertSpecifies the certificate to be accepted from the server when connecting using TLS/SSL.

Firewall


PropertyDescription
FirewallTypeSpecifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
FirewallServerIdentifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.
FirewallPortSpecifies the TCP port to be used for a proxy-based firewall.
FirewallUserIdentifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPasswordSpecifies the password of the user account authenticating to a proxy-based firewall.

Proxy


PropertyDescription
ProxyAutoDetectSpecifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServerIdentifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPortIdentifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthSchemeSpecifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUserProvides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPasswordSpecifies the password of the user specified in the ProxyUser connection property.
ProxySSLTypeSpecifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
ProxyExceptionsSpecifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Logging


PropertyDescription
LogfileSpecifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
VerbositySpecifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
LogModulesSpecifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.
MaxLogFileSizeSpecifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.
MaxLogFileCountSpecifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.

Schema


PropertyDescription
LocationSpecifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.
BrowsableSchemasOptional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
TablesOptional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
ViewsOptional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .
DataverseWhich Analytics dataverse to scan when discovering tables.
TypeDetectionSchemeDetermines how the provider builds tables and columns from the buckets found in Couchbase.
InferNumSampleValuesThe maximum number of values for every field to scan before determining its data type. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
InferSampleSizeThe maximum number of documents to scan for the columns available in the bucket. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
InferSimilarityMetricSpecifies the similarity degree where different schemas will be considered to be the same flavor. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
FlexibleSchemasWhether the provider allows queries to use columns that it has not discovered.
ExposeTTLSpecifies whether document TTL information should be exposed.
NumericStringsWhether to allow string values to be treated as numbers.
IgnoreChildAggregatesWhether the provider exposes aggregate columns that are also available as child tables. Ignored if TableSupport is not set to Full.
TableSupportHow much effort the provider will put into discovering tables on the Couchbase server.
NewChildJoinsModeDetermines the kind of child table model the provider exposes.

Caching


PropertyDescription
AutoCacheSpecifies whether the content of tables targeted by SELECT queries is automatically cached to the specified cache database.
CacheProviderThe namespace of an ADO.NET provider. The specified provider is used as the target database for all caching operations.
CacheDriverThe driver class of a JDBC driver. The specified driver is used to connect to the target database for all caching operations.
CacheConnectionSpecifies the connection string for the specified cache database.
CacheLocationSpecifies the path to the cache when caching to a file.
CacheToleranceNotes the tolerance, in seconds, for stale data in the specified cache database. Requires AutoCache to be set to True.
OfflineGets the data from the specified cache database instead of live Couchbase data.
CacheMetadataDetermines whether the provider caches table metadata to a file-based cache database.

Miscellaneous


PropertyDescription
AllowJSONParametersAllows raw JSON to be used in parameters when QueryPassthrough is enabled.
ChildSeparatorThe character or characters used to denote child tables.
CreateTableRamQuotaThe default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.
DataverseSeparatorThe character or characters used to denote Analytics dataverses and scopes/collections.
FlattenArraysThe number of elements to expose as columns from nested arrays. Ignored if IgnoreChildAggregates is enabled.
FlattenObjectsSet FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.
FlavorSeparatorThe character or characters used to denote flavors.
GenerateSchemaFilesIndicates the user preference as to when schemas should be generated and saved.
InsertNullValuesDetermines whether an INSERT should include fields that have NULL values.
MaxRowsSpecifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
OtherSpecifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
PagesizeSpecifies the maximum number of records per page the provider returns when requesting data from Couchbase.
PeriodsSeparatorThe character or characters used to denote hierarchy.
PseudoColumnsSpecifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'.
QueryExecutionTimeoutThis sets the server-side timeout for the query, which governs how long Couchbase will execute the query before returning a timeout error.
QueryPassthroughThis option passes the query to the Couchbase server as is.
ReadonlyToggles read-only access to Couchbase from the provider.
RowScanDepthThe maximum number of rows to scan to look for the columns available in a table.
RTKSpecifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.
StrictComparisonAdjusts how precisely to translate filters on SQL input queries into Couchbase queries. This can be set to a comma-separated list of values, where each value can be one of: date, number, boolean, or string.
TimeoutSpecifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.
TransactionDurabilitySpecifies how a document must be stored for a transaction to succeed. Specifies whether to use N1QL transactions when executing queries.
TransactionTimeoutThis sets the amount of time a transaction may execute before it is timed out by Couchbase.
UpdateNullValuesDetermines whether an UPDATE writes NULL values as NULL, or removes them.
UseCollectionsForDDLWhether to assume that CREATE TABLE statements use collections instead of flavors. Only takes effect when connecting to Couchbase v7+ and GenerateSchemaFiles is set to OnCreate.
UserDefinedViewsSpecifies a filepath to a JSON configuration file that defines custom views. The provider automatically detects and uses the views specified in this file.
UseTransactionsSpecifies whether to use N1QL transactions when executing queries.
ValidateJSONParametersAllows the provider to validate that string parameters are valid JSON before sending the query to Couchbase.
CData Python Connector for Couchbase

Authentication

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.


PropertyDescription
AuthSchemeThe type of authentication to use when connecting to Couchbase.
UserSpecifies the authenticating user's user ID.
PasswordSpecifies the authenticating user's password.
CredentialsFileUse this property if you need to provide credentials for multiple users or buckets. This file takes priority over other forms of authentication.
ServerThe address of the Couchbase server or servers to which you are connecting.
CouchbaseServiceDetermines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics.
ConnectionModeDetermines how to connect to the Couchbase server. Must be either Direct or Cloud.
DNSServerDetermines what DNS server to use when retrieving Couchbase Capella information.
N1QLPortThe port or URL for connecting to the Couchbase N1QL Endpoint.
AnalyticsPortThe port or URL for connecting to the Couchbase Analytics Endpoint.
WebConsolePortThe port or URL for connecting to the Couchbase Web Console.
SearchPortThe port or URL for connecting to the Couchbase Search Service Endpoint.
CData Python Connector for Couchbase

AuthScheme

The type of authentication to use when connecting to Couchbase.

Possible Values

Basic, CredentialsFile, SSLCertificate

Data Type

string

Default Value

"Basic"

Remarks

Note that only Basic authentication is supported when using the "Cloud" ConnectionMode.

CData Python Connector for Couchbase

User

Specifies the authenticating user's user ID.

Data Type

string

Default Value

""

Remarks

The authenticating server requires both User and Password to validate the user's identity.

CData Python Connector for Couchbase

Password

Specifies the authenticating user's password.

Data Type

string

Default Value

""

Remarks

The authenticating server requires both User and Password to validate the user's identity.

CData Python Connector for Couchbase

CredentialsFile

Use this property if you need to provide credentials for multiple users or buckets. This file takes priority over other forms of authentication.

Data Type

string

Default Value

""

Remarks

Use this property if you need to provide credentials for multiple users or buckets. This takes priority over other forms of authentication.

Set CredentialsFile to the path to a file that has the same markup as below:

[{"user": "YourUserName1", "pass":"YourPassword1"},
  {"user": "YourUserName2", "pass":"YourPassword2"}] 

CData Python Connector for Couchbase

Server

The address of the Couchbase server or servers to which you are connecting.

Data Type

string

Default Value

""

Remarks

This value can be set to a hostname or an IP address, like "couchbase-server.com" or "1.2.3.4". It can also be set to an HTTP or HTTPS URL, such as "https://couchbase-server.com" or "http://1.2.3.4". If ConnectionMode is set to Cloud then this should be the hostname of the Couchbase Cloud instance as reported in the control panel.

If the URL form is used, then setting this option will also set the UseSSL option: if the URL scheme is "https://", then UseSSL will be set to true, and a URL with "http://" will set UseSSL to false.

A port value cannot be used as part of this option, so values like "http://couchbase-server.com:8093" are not allowed. Please use WebConsolePort, N1QLPort and AnalyticsPort.

This value can also accept multiple servers in the above format separated by commas, such as "1.2.3.4, couchbase-server.com". This will allow the connector to recover the connection in case some of the servers listed are inaccessible.

Note that while the connector will try to recover the connection as a whole, it may lose individual operations. For example, while a long-running query will fail if the server becomes inaccesssible while that query is running, that query can be retried on the same connection and the connector will execute it on the next active server.

CData Python Connector for Couchbase

CouchbaseService

Determines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics.

Possible Values

N1QL, Analytics

Data Type

string

Default Value

"N1QL"

Remarks

Determines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics

CData Python Connector for Couchbase

ConnectionMode

Determines how to connect to the Couchbase server. Must be either Direct or Cloud.

Possible Values

Direct, Cloud

Data Type

string

Default Value

"Direct"

Remarks

By default the connector connects to Couchbase directly using the address given in the Server option. The Server must be running the appropriate CouchbaseService to accept the connection. This will work in most on-premise or basic cloud deployments.

This should be set to Cloud when connecting to Couchbase Capella or a custom deployment that uses service records. These records will allow the connector to determine the exact Couchbase servers that provide the appropriate CouchbaseService. You must also set the DNSServer property so that the connector is able to fetch these service records.

Note that enabling Cloud mode will override these connection properties with the values discovered by contacting the cluster:

  • Server
  • N1QLPort
  • AnalyticsPort

CData Python Connector for Couchbase

DNSServer

Determines what DNS server to use when retrieving Couchbase Capella information.

Data Type

string

Default Value

""

Remarks

In most cases any public DNS server can be provided here such as the ones provided by OpenDNS, Cloudflare or Google.

If these are not accessible then you will need to use the DNS server configured by your network administrator. You can also provide a port if needed: DNSServer=10.1.2.3:5300

CData Python Connector for Couchbase

N1QLPort

The port or URL for connecting to the Couchbase N1QL Endpoint.

Data Type

string

Default Value

""

Remarks

This port is used for submitting queries when CouchbaseService is set to N1QL. Any requests to manage indices will also go through this port. It defaults to 8093 when not using SSL, and 18093 when using SSL. See UseSSL.

This option can be set one of two ways:

  • As a port number like "1234". With this setting the connector will send N1QL queries to the endpoint http://Server:N1QLPort/query/service. (or https:// if Server is https:// or UseSSL is enabled).
  • As a full URL like "http://couchbase.example:1234/proxy". With this setting the connector send N1QL queries using the endpoint you specify. For example, if you use that URL then N1QL requests will go to http://couchbase.example:1234/proxy/query/serivce. Server and UseSSL are ignored for N1QL requests.

CData Python Connector for Couchbase

AnalyticsPort

The port or URL for connecting to the Couchbase Analytics Endpoint.

Data Type

string

Default Value

""

Remarks

This port is used for submitting queries when CouchbaseService is set to Analytics. It defaults to 8095 when not using SSL, and 18095 when using SSL. See UseSSL.

This option can be set one of two ways:

  • As a port number like "1234". With this setting the connector will send Analytics queries to the endpoint http://Server:AnalyticsPort/analytics/service (or https:// if Server is https:// or UseSSL is enabled).
  • As a full URL like "http://couchbase.example:1234/proxy". With this setting the connector send Analytics queries using the endpoint you specify. For example, if you use that URL then Analytics requests will go to http://couchbase.example:1234/proxy/analytics/serivce. Server and UseSSL are ignored for Analytics requests.

CData Python Connector for Couchbase

WebConsolePort

The port or URL for connecting to the Couchbase Web Console.

Data Type

string

Default Value

""

Remarks

This port is used for API operations like managing buckets. It defaults to 8091 when not using SSL, and 18091 when using SSL. See UseSSL.

This option can be set one of two ways:

  • As a port number like "1234". With this setting the connector will send management requests to http://Server:WebConsolePort/. The exact endpoint depends upon the operation being used. For example, the cluster status request will go to the endpoint http://Server:WebConsolePort/pools.
  • As a full URL like "http://couchbase.example:1234/proxy". With this setting the connector will send Web Console queries using the endpoint you specify. For example, if you use that URL then the cluster status request (normally at /pools) will go to http://couchbase.example:1234/proxy/pools. Server and UseSSL are ignored for web console requests.

CData Python Connector for Couchbase

SearchPort

The port or URL for connecting to the Couchbase Search Service Endpoint.

Data Type

string

Default Value

""

Remarks

This port is used for submitting queries when CouchbaseService is set to Search Service. It defaults to 8094 when not using SSL, and 18094 when using SSL. See UseSSL.

This option can be set one of two ways:

  • As a port number like "1234". With this setting the connector will send Search Service queries to the endpoint http://Server:SearchPort/api/index/ (or https:// if Server is https:// or UseSSL is enabled).
  • As a full URL like "http://couchbase.example:1234/proxy". With this setting the connector send Search Service queries using the endpoint you specify. For example, if you use that URL then Search Service requests will go to http://couchbase.example:1234/proxy/api/index/. Server and UseSSL are ignored for Search Service requests.

CData Python Connector for Couchbase

SSL

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.


PropertyDescription
SSLClientCertSpecifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.
SSLClientCertTypeSpecifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.
SSLClientCertPasswordSpecifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.
SSLClientCertSubjectSpecifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.
UseSSLWhether to negotiate TLS/SSL when connecting to the Couchbase server.
SSLServerCertSpecifies the certificate to be accepted from the server when connecting using TLS/SSL.
CData Python Connector for Couchbase

SSLClientCert

Specifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.

Data Type

string

Default Value

""

Remarks

This property specifies the client certificate store for SSL Client Authentication. Use this property alongside SSLClientCertType, which defines the type of the certificate store, and SSLClientCertPassword, which specifies the password for password-protected stores. When SSLClientCert is set and SSLClientCertSubject is configured, the driver searches for a certificate matching the specified subject.

Certificate store designations vary by platform. On Windows, certificate stores are identified by names such as MY (personal certificates), while in Java, the certificate store is typically a file containing certificates and optional private keys.

The following are designations of the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.
SPCSoftware publisher certificates.

For PFXFile types, set this property to the filename. For PFXBlob types, set this property to the binary contents of the file in PKCS12 format.

CData Python Connector for Couchbase

SSLClientCertType

Specifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.

Possible Values

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PUBLIC_KEY_FILE, PUBLIC_KEY_BLOB, SSHPUBLIC_KEY_FILE, SSHPUBLIC_KEY_BLOB, P7BFILE, PPKFILE, XMLFILE, XMLBLOB, BCFKSFILE, BCFKSBLOB

Data Type

string

Default Value

"USER"

Remarks

This property determines the format and location of the key store used to provide the client certificate. Supported values include platform-specific and universal key store formats. The available values and their usage are:

USER - defaultFor Windows, this specifies that the certificate store is a certificate store owned by the current user. Note that this store type is not available in Java.
MACHINEFor Windows, this specifies that the certificate store is a machine store. Note that this store type is not available in Java.
PFXFILEThe certificate store is the name of a PFX (PKCS12) file containing certificates.
PFXBLOBThe certificate store is a string (base-64-encoded) representing a certificate store in PFX (PKCS12) format.
JKSFILEThe certificate store is the name of a Java key store (JKS) file containing certificates. Note that this store type is only available in Java.
JKSBLOBThe certificate store is a string (base-64-encoded) representing a certificate store in JKS format. Note that this store type is only available in Java.
PEMKEY_FILEThe certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
PEMKEY_BLOBThe certificate store is a string (base64-encoded) that contains a private key and an optional certificate.
PUBLIC_KEY_FILEThe certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
PUBLIC_KEY_BLOBThe certificate store is a string (base-64-encoded) that contains a PEM- or DER-encoded public key certificate.
SSHPUBLIC_KEY_FILEThe certificate store is the name of a file that contains an SSH-style public key.
SSHPUBLIC_KEY_BLOBThe certificate store is a string (base-64-encoded) that contains an SSH-style public key.
P7BFILEThe certificate store is the name of a PKCS7 file containing certificates.
PPKFILEThe certificate store is the name of a file that contains a PuTTY Private Key (PPK).
XMLFILEThe certificate store is the name of a file that contains a certificate in XML format.
XMLBLOBThe certificate store is a string that contains a certificate in XML format.
BCFKSFILEThe certificate store is the name of a file that contains an Bouncy Castle keystore.
BCFKSBLOBThe certificate store is a string (base-64-encoded) that contains a Bouncy Castle keystore.

CData Python Connector for Couchbase

SSLClientCertPassword

Specifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.

Data Type

string

Default Value

""

Remarks

This property provides the password needed to open a password-protected certificate store. This property is necessary when using certificate stores that require a password for decryption, as is often recommended for PFX or JKS type stores.

If the certificate store type does not require a password, for example USER or MACHINE on Windows, this property can be left blank. Ensure that the password matches the one associated with the specified certificate store to avoid authentication errors.

CData Python Connector for Couchbase

SSLClientCertSubject

Specifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.

Data Type

string

Default Value

"*"

Remarks

This property determines which client certificate to load based on its subject. The connector searches for a certificate that exactly matches the specified subject. If no exact match is found, the connector looks for certificates containing the value of the subject. If no match is found, no certificate is selected.

The subject should follow the standard format of a comma-separated list of distinguished name fields and values. For example, CN=www.server.com, OU=Test, C=US. Common fields include the following:

FieldMeaning
CNCommon Name. This is commonly a host name like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

Note: If any field contains special characters, such as commas, the value must be quoted. For example: CN="Example, Inc.", C=US.

CData Python Connector for Couchbase

UseSSL

Whether to negotiate TLS/SSL when connecting to the Couchbase server.

Data Type

bool

Default Value

false

Remarks

When this is set to true, the defaults for the following options change:

Property Plaintext Default SSL Default
AnalyticsPort 8095 18095
N1QLPort 8093 18093
WebConsolePort 8091 18091

This option should be enabled when connecting to Couchbase Capella because all Capella deployments use SSL by default.

CData Python Connector for Couchbase

SSLServerCert

Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

Data Type

string

Default Value

""

Remarks

If you are using a TLS/SSL connection, use this property to specify the TLS/SSL certificate to be accepted from the server. If you specify a value for this property, all other certificates that are not trusted by the machine are rejected.

This property can take the following forms:

Description Example
A full PEM Certificate (example shortened for brevity) -----BEGIN CERTIFICATE-----
MIIChTCCAe4CAQAwDQYJKoZIhv......Qw==
-----END CERTIFICATE-----
A path to a local file containing the certificate C:\cert.cer
The public key (example shortened for brevity) -----BEGIN RSA PUBLIC KEY-----
MIGfMA0GCSq......AQAB
-----END RSA PUBLIC KEY-----
The MD5 Thumbprint (hex values can also be either space- or colon-separated) ecadbdda5a1529c58a1e9e09828d70e4
The SHA1 Thumbprint (hex values can also be either space- or colon-separated) 34a929226ae0819f2ec14b4a3d904f801cbb150d

Note: It is possible to use '*' to signify that all certificates should be accepted, but due to security concerns this is not recommended.

CData Python Connector for Couchbase

Firewall

This section provides a complete list of the Firewall properties you can configure in the connection string for this provider.


PropertyDescription
FirewallTypeSpecifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
FirewallServerIdentifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.
FirewallPortSpecifies the TCP port to be used for a proxy-based firewall.
FirewallUserIdentifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPasswordSpecifies the password of the user account authenticating to a proxy-based firewall.
CData Python Connector for Couchbase

FirewallType

Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.

Possible Values

NONE, TUNNEL, SOCKS4, SOCKS5

Data Type

string

Default Value

"NONE"

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

Note: By default, the connector connects to the system proxy. To disable this behavior and connect to one of the following proxy types, set ProxyAutoDetect to false.

The following table provides port number information for each of the supported protocols.

Protocol Default Port Description
TUNNEL 80 The port where the connector opens a connection to Couchbase. Traffic flows back and forth via the proxy at this location.
SOCKS4 1080 The port where the connector opens a connection to Couchbase. SOCKS 4 then passes theFirewallUser value to the proxy, which determines whether the connection request should be granted.
SOCKS5 1080 The port where the connector sends data to Couchbase. If the SOCKS 5 proxy requires authentication, set FirewallUser and FirewallPassword to credentials the proxy recognizes.

To connect to HTTP proxies, use ProxyServer and ProxyPort. To authenticate to HTTP proxies, use ProxyAuthScheme, ProxyUser, and ProxyPassword.

CData Python Connector for Couchbase

FirewallServer

Identifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

CData Python Connector for Couchbase

FirewallPort

Specifies the TCP port to be used for a proxy-based firewall.

Data Type

int

Default Value

0

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

CData Python Connector for Couchbase

FirewallUser

Identifies the user ID of the account authenticating to a proxy-based firewall.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

CData Python Connector for Couchbase

FirewallPassword

Specifies the password of the user account authenticating to a proxy-based firewall.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

CData Python Connector for Couchbase

Proxy

This section provides a complete list of the Proxy properties you can configure in the connection string for this provider.


PropertyDescription
ProxyAutoDetectSpecifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServerIdentifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPortIdentifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthSchemeSpecifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUserProvides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPasswordSpecifies the password of the user specified in the ProxyUser connection property.
ProxySSLTypeSpecifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
ProxyExceptionsSpecifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.
CData Python Connector for Couchbase

ProxyAutoDetect

Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.

Data Type

bool

Default Value

true

Remarks

When this connection property is set to True, the connector checks your system proxy settings for existing proxy server configurations (no need to manually supply proxy server details).

This connection property takes precedence over other proxy settings. If you want to configure the connector to connect to a specific proxy server, set ProxyAutoDetect to False.

On Windows, the connector reads the proxy settings from the Internet Options in the registry, specifically the registry key HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\. On Windows 10 and later, this corresponds to the Proxy Settings found in the Windows Settings.

Note that these settings apply only to the current user of the machine. If you're running an application as a service, the connector does not read your own user's settings. You must instead manually supply the proxy settings in the connector's connection properties.

On Mac, the connector reads proxy settings from the system-configured CFNetwork settings.

On Linux, this property is unsupported, and is set to False by default.

To connect to an HTTP proxy, see ProxyServer. For other proxies, such as SOCKS or tunneling, see FirewallType.

CData Python Connector for Couchbase

ProxyServer

Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.

Data Type

string

Default Value

""

Remarks

The connector only routes HTTP traffic through the proxy server specified in this connection property when ProxyAutoDetect is set to False.

If ProxyAutoDetect is set to True (the default), the connector instead routes HTTP traffic through the proxy server specified in your system proxy settings.

CData Python Connector for Couchbase

ProxyPort

Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.

Data Type

int

Default Value

80

Remarks

The connector only routes HTTP traffic through the ProxyServer port specified in this connection property when ProxyAutoDetect is set to False.

If ProxyAutoDetect is set to True (the default), the connector instead routes HTTP traffic through the proxy server port specified in your system proxy settings.

For other proxy types, see FirewallType.

CData Python Connector for Couchbase

ProxyAuthScheme

Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.

Possible Values

BASIC, DIGEST, NONE, NEGOTIATE, NTLM

Data Type

string

Default Value

"BASIC"

Remarks

Note: The connector only uses this ProxyAuthScheme when ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the authentication method specified in your system proxy settings.

Supported authentication types :

  • BASIC: The connector performs HTTP basic authentication.
  • DIGEST: The connector performs HTTP digest authentication.
  • NTLM: The connector retrieves an NTLM token.
  • NEGOTIATE: The connector retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.
  • NONE: Signifies that the ProxyServer does not require authentication.

For all values other than NONE, you must also set the ProxyUser and ProxyPassword connection properties.

If you need to use another authentication type, such as SOCKS 5 authentication, see FirewallType.

CData Python Connector for Couchbase

ProxyUser

Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.

Data Type

string

Default Value

""

Remarks

The ProxyUser and ProxyPassword connection properties are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

After selecting one of the available authentication types in ProxyAuthScheme, set this property as follows:

ProxyAuthScheme Value Value to set for ProxyUser
BASIC The username of a user registered with the proxy server.
DIGEST The username of a user registered with the proxy server.
NEGOTIATE The username of a Windows user who is a valid user in the domain or trusted domain that the proxy server is part of, in the format user@domain or domain\user.
NTLM The username of a Windows user who is a valid user in the domain or trusted domain that the proxy server is part of, in the format user@domain or domain\user.
NONE Do not set the ProxyPassword connection property.

Note: The connector only uses this username if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the username specified in your system proxy settings.

CData Python Connector for Couchbase

ProxyPassword

Specifies the password of the user specified in the ProxyUser connection property.

Data Type

string

Default Value

""

Remarks

The ProxyUser and ProxyPassword connection properties are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

After selecting one of the available authentication types in ProxyAuthScheme, set this property as follows:

ProxyAuthScheme Value Value to set for ProxyPassword
BASIC The password associated with the proxy server user specified in ProxyUser.
DIGEST The password associated with the proxy server user specified in ProxyUser.
NEGOTIATE The password associated with the Windows user account specified in ProxyUser.
NTLM The password associated with the Windows user account specified in ProxyUser.
NONE Do not set the ProxyPassword connection property.

For SOCKS 5 authentication or tunneling, see FirewallType.

Note: The connector only uses this password if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the password specified in your system proxy settings.

CData Python Connector for Couchbase

ProxySSLType

Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.

Possible Values

AUTO, ALWAYS, NEVER, TUNNEL

Data Type

string

Default Value

"AUTO"

Remarks

This property determines when to use SSL for the connection to the HTTP proxy specified by ProxyServer. You can set this connection property to the following values :

AUTODefault setting. If ProxyServer is set to an HTTPS URL, the connector uses the TUNNEL option. If ProxyServer is set to an HTTP URL, the component uses the NEVER option.
ALWAYSThe connection is always SSL enabled.
NEVERThe connection is not SSL enabled.
TUNNELThe connection is made through a tunneling proxy. The proxy server opens a connection to the remote host and traffic flows back and forth through the proxy.

CData Python Connector for Couchbase

ProxyExceptions

Specifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Data Type

string

Default Value

""

Remarks

The ProxyServer is used for all addresses, except for addresses defined in this property. Use semicolons to separate entries.

Note: The connector uses the system proxy settings by default, without further configuration needed. If you want to explicitly configure proxy exceptions for this connection, set ProxyAutoDetect to False.

CData Python Connector for Couchbase

Logging

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.


PropertyDescription
LogfileSpecifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
VerbositySpecifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
LogModulesSpecifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.
MaxLogFileSizeSpecifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.
MaxLogFileCountSpecifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.
CData Python Connector for Couchbase

Logfile

Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.

Data Type

string

Default Value

""

Remarks

This property specifies the location and name of the log file where the connector records its operations, including authentication events, query execution, and connection details. If the specified file does not exist, the connector creates it. Ensure that the user or the service running the connector has write access to the specified path or file. Without sufficient permissions, the log file is not created.

Sensitive information from the connection string, such as passwords and tokens, is automatically masked in the logs. However, sensitive information present in the data itself may not be masked.

If you specify a relative path for Logfile, and if the Location property is set, that directory is used as the base path for the log file.

Additional properties allow you to customize logging behavior:

CData Python Connector for Couchbase

Verbosity

Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.

Data Type

string

Default Value

"1"

Remarks

This property defines the level of detail the connector includes in the log file. Higher verbosity levels increase the detail of the logged information, but may also result in larger log files and slower performance due to the additional data being captured.

The default verbosity level is 1, which is recommended for regular operation. Higher verbosity levels are primarily intended for debugging purposes. For more information on each level, refer to Logging.

When combined with the LogModules property, Verbosity can refine logging to specific categories of information.

CData Python Connector for Couchbase

LogModules

Specifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.

Data Type

string

Default Value

""

Remarks

The connector writes details about each operation it performs into the logfile specified by the Logfile connection property.

Each of these logged operations are assigned to a themed category called a module, and each module has a corresponding short code used to labels individual connector operations as belonging to that module.

When this connection property is set to a semicolon-separated list of module codes, only operations belonging to the specified modules are written to the logfile. Note that this only affects which operations are logged moving forward and doesn't retroactively alter the existing contents of the logfile. For example: INFO;EXEC;SSL;META;

By default, logged operations from all modules are included.

You can explicitly exclude a module by prefixing it with a "-". For example: -HTTP

To apply filters to submodules, identify them with the syntax <module name>.<submodule name>. For example, the following value causes the connector to only log actions belonging to the HTTP module, and further refines it to exclude actions belonging to the Res submodule of the HTTP module: HTTP;-HTTP.Res

Note that the logfile filtering triggered by the Verbosity connection property takes precedence over the filtering imposed by this connection property. This means that operations of a higher verbosity level than the level specified in the Verbosity connection property are not printed in the logfile, even if they belong to one of the modules specified in this connection property.

The available modules and submodules are:

Module Name Module Description Submodules
INFO General Information. Includes the connection string, product version (build number), and initial connection messages.
  • Connec – Information related to creating or destroying connections.
  • Messag – Generic label for messages pertaining to connections, the connection string, and product version. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
EXEC Query Execution. Includes execution messages for user-written SQL queries, parsed SQL queries, and normalized SQL queries. Success/failure messages for queries and query pages appear here as well.
  • Messag – Messages pertaining to query execution. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • Normlz – Query normalization steps. Query normalization is when the product takes the user-submitted query and rewrites the query to get the same results with optimal performance.
  • Origin – This label applies to any messages recording a user's original query (the exact, unaltered, non-normalized query executed by the user).
  • Page – Messages related to query paging.
  • Parsed – Query parsing steps. Parsing is the process of converting the user-submitted query into a standardized format for easier processing.
HTTP HTTP protocol messages. Includes HTTP requests/responses (including POST messages), as well as Kerberos related messages.
  • KERB – HTTP requests related to Kerberos.
  • Messag – Messages pertaining to HTTP protocols. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • Unpack – This label applies to messages about zipped data being returned from the service API and unpacked by the product.
  • Res – Messages containing HTTP responses.
  • Req – Messages containing HTTP requests.
WSDL Messages pertaining to the generation of WSDL/XSD files.
SSL SSL certificate messages.
  • Certif – Messages pertaining to SSL certificates.
AUTH Authentication related failure/success messages.
  • Messag – Messages pertaining to authentication. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • OAuth – Messages related to OAuth authentication.
  • Krbros – Kerberos-related authentication messages.
SQL Includes SQL transactions, SQL bulk transfer messages, and SQL result set messages.
  • Bulk – Messages pertaining to bulk query execution.
  • Cache – Messages related to reading row data from and writing row data to the product's cache for better performance.
  • Messag – Messages pertaining to SQL transactions. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
  • ResSet – Query resultsets.
  • Transc – Messages related to handling transactions, including information about the number of jobs executed and backup table handling.
META Metadata cache and schema messages.
  • Cache – Messages related to reading from and modifying column and table definitions in the product's cache for better performance.
  • Schema – Messages related to retrieving metadata from or modifying the service schema.
  • MemSto – Messages related to writing to or reading from in-memory metadata cache.
  • Storag – Messages relating to storing metadata on disk or in an external data store, rather than in memory.
FUNC Information related to executing SQL functions.
  • Errmsg – Error messages related to executing SQL functions.
TCP Incoming and outgoing raw bytes on TCP transport layer messages.
  • Send – Raw data sent via the TCP protocol.
  • Receiv – Raw data received via the TCP protocol.
FTP Messages pertaining to the File Transfer Protocol.
  • Info – Status messages related to communication in the FTP protocol.
  • Client – Messages related to actions taken by the FTP client (the product) during FTP communication.
  • Server – Messages related to actions taken by the FTP server during FTP communication.
SFTP Messages pertaining to the Secure File Transfer Protocol.
  • Info – Status messages related to communication in the SFTP protocol.
  • To_Server – Messages related to actions taken by the SFTP client (the product) during SFTP communication.
  • From_Server – Messages related to actions taken by the SFTP server during SFTP communication.
POP Messages pertaining to data transferred via the Post Office Protocol.
  • Client – Messages related to actions taken by the POP client (the product) during POP communication.
  • Server – Messages related to actions taken by the POP server during POP communication.
  • Status – Status messages related to communication in the POP protocol.
SMTP Messages pertaining to data transferred via the Simple Mail Transfer Protocol.
  • Client – Messages related to actions taken by the SMTP client (the product) during SMTP communication.
  • Server – Messages related to actions taken by the SMTP server during SMTP communication.
  • Status – Status messages related to communication in the SMTP protocol.
CORE Messages relating to various internal product operations not covered by other modules.
DEMN Messages related to SQL remoting.
CLJB Messages about bulk data uploads (cloud job).
  • Commit – Submissions for bulk data uploads.
SRCE Miscellaneous messages produced by the product that don't belong in any other module.
TRANCE Advanced messages concerning low-level product operations.
CBAS Applies to log messages generated from the Couchbase protocol.

CData Python Connector for Couchbase

MaxLogFileSize

Specifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.

Data Type

string

Default Value

"100MB"

Remarks

For values lower than 100 KB, the connector uses 100 KB as the minimum allowable size.

To control the total number of log files retained, use the MaxLogFileCount property in conjunction with this property. Together, these properties allow you to manage the size and retention of log files effectively.

CData Python Connector for Couchbase

MaxLogFileCount

Specifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.

Data Type

int

Default Value

-1

Remarks

Each log file name includes the date and time for easier identification.

This property accepts the following values:

  • A value of 2 or higher sets the maximum number of log files retained.
  • A value of 1 retains only one log file. When it reaches the maximum size, the file is deleted and replaced by a new one, leaving no history beyond the current log.
  • A value of 0 or negative indicates no limit on the number of log files, and logging continues indefinitely.

To manage log file size, use the MaxLogFileSize property. The two properties work together to control the size and retention of log files in the logging folder.

CData Python Connector for Couchbase

Schema

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.


PropertyDescription
LocationSpecifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.
BrowsableSchemasOptional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
TablesOptional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
ViewsOptional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .
DataverseWhich Analytics dataverse to scan when discovering tables.
TypeDetectionSchemeDetermines how the provider builds tables and columns from the buckets found in Couchbase.
InferNumSampleValuesThe maximum number of values for every field to scan before determining its data type. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
InferSampleSizeThe maximum number of documents to scan for the columns available in the bucket. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
InferSimilarityMetricSpecifies the similarity degree where different schemas will be considered to be the same flavor. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.
FlexibleSchemasWhether the provider allows queries to use columns that it has not discovered.
ExposeTTLSpecifies whether document TTL information should be exposed.
NumericStringsWhether to allow string values to be treated as numbers.
IgnoreChildAggregatesWhether the provider exposes aggregate columns that are also available as child tables. Ignored if TableSupport is not set to Full.
TableSupportHow much effort the provider will put into discovering tables on the Couchbase server.
NewChildJoinsModeDetermines the kind of child table model the provider exposes.
CData Python Connector for Couchbase

Location

Specifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.

Data Type

string

Default Value

"%APPDATA%\\CData\\Couchbase Data Provider\\Schema"

Remarks

The Location property is only needed if you want to either customize definitions (for example, change a column name, ignore a column, etc.) or extend the data model with new tables, views, or stored procedures.

If left unspecified, the default location is %APPDATA%\\CData\\Couchbase Data Provider\\Schema, where %APPDATA% is set to the user's configuration directory:

Platform %APPDATA%
Windows The value of the APPDATA environment variable
Linux ~/.config

CData Python Connector for Couchbase

BrowsableSchemas

Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .

Data Type

string

Default Value

""

Remarks

Listing all available database schemas can take extra time, thus degrading performance. Providing a list of schemas in the connection string saves time and improves performance.

CData Python Connector for Couchbase

Tables

Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .

Data Type

string

Default Value

""

Remarks

Listing all available tables from some databases can take extra time, thus degrading performance. Providing a list of tables in the connection string saves time and improves performance.

If there are lots of tables available and you already know which ones you want to work with, you can use this property to restrict your viewing to only those tables. To do this, specify the tables you want in a comma-separated list. Each table should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Tables=TableA,[TableB/WithSlash],WithCatalog.WithSchema.`TableC With Space`.

Note: If you are connecting to a data source with multiple schemas or catalogs, you must specify each table you want to view by its fully qualified name. This avoids ambiguity between tables that may exist in multiple catalogs or schemas.

CData Python Connector for Couchbase

Views

Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

Data Type

string

Default Value

""

Remarks

Listing all available views from some databases can take extra time, thus degrading performance. Providing a list of views in the connection string saves time and improves performance.

If there are lots of views available and you already know which ones you want to work with, you can use this property to restrict your viewing to only those views. To do this, specify the views you want in a comma-separated list. Each view should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Views=ViewA,[ViewB/WithSlash],WithCatalog.WithSchema.`ViewC With Space`.

Note: If you are connecting to a data source with multiple schemas or catalogs, you must specify each view you want to examine by its fully qualified name. This avoids ambiguity between views that may exist in multiple catalogs or schemas.

CData Python Connector for Couchbase

Dataverse

Which Analytics dataverse to scan when discovering tables.

Data Type

string

Default Value

""

Remarks

This property is empty by default, which means that all dataverses will be scanned and table names will be generated as described in DataverseSeparator.

If you assign this property to a non-blank value, then the connector will scan only the corresponding dataverse (for example, setting this to "Default" scans the Default dataverse). Since only one dataverse is being scanned, table names will not be prefixed with the dataverse name. It is recommended to set this property to "Default" if you are coming from a previous version of the connector and need backwards compatability.

If you are connecting to Couchbase 7.0 or later, this option will be treated as a compound name containing both a dataset and a scope. For example, if you have previously created collections like these:

CREATE ANALYTICS SCOPE websites.exampledotcom
CREATE ANALYTICS COLLECTION websites.exampledotcom.traffic ON examplecom_traffic_bucket
CREATE ANALYTICS COLLECTION websites.exampledotcom.ads ON examplecom_ads_bucket
You would set this option to "websites.exampledotcom".

CData Python Connector for Couchbase

TypeDetectionScheme

Determines how the provider builds tables and columns from the buckets found in Couchbase.

Data Type

string

Default Value

"DocType"

Remarks

A comma-separated list of the following options:

DocType This discovers tables by checking at each bucket and looking for different values of the "docType" field in the documents. For example, if the bucket beer-sample contains documents with "docType" = 'brewery' and "docType" = 'beer', this will generate three tables: beer-sample (containing all documents), beer-sample.brewery (containing just breweries) and beer-sample.beer (containing just beers).

Like RowScan, this will scan a sample of the documents in each flavor and determine the data type for each field. RowScanDepth determines how many documents are scanned from each flavor.

DocType=fieldName Like DocType, but this scans based off of a field called "fieldName" rather than "docType". "fieldName" must match the field name in Couchbase exactly, including case.
Infer This uses the N1QL INFER statement to determine what tables and columns exist. This does more flexible flavor detection than DocType.
RowScan This reads a sample of documents from a bucket, and heuristically determines the data type. RowScanDepth determines how many documents are scanned. It does not do any flavor detection.
None This is like RowScan, but will always return columns that have string types instead of the detected type.

CData Python Connector for Couchbase

InferNumSampleValues

The maximum number of values for every field to scan before determining its data type. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.

Data Type

string

Default Value

"10"

Remarks

The maximum number of values to scan from every field of the sampled documents before determining the field's data type. This property enables additional configuration of Automatic Schema Discovery when you are using the Couchbase Infer command -- TypeDetectionScheme must also be set to Infer to use this propery.

CData Python Connector for Couchbase

InferSampleSize

The maximum number of documents to scan for the columns available in the bucket. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.

Data Type

string

Default Value

"100"

Remarks

The maximum number of documents to scan for the columns available in the bucket. The Infer command will return column metadata by scanning a random sample of documents of the size specified here.

Setting a high value may decrease performance. Setting a low value may prevent the column and data type from being determined properly, especially when there is null data.

This property enables additional configuration of Automatic Schema Discovery when you are using the Couchbase Infer command -- TypeDetectionScheme must also be set to Infer to use this propery.

CData Python Connector for Couchbase

InferSimilarityMetric

Specifies the similarity degree where different schemas will be considered to be the same flavor. Applies to Automatic Schema Discovery when TypeDetectionScheme is set to INFER.

Data Type

string

Default Value

"0.7"

Remarks

This property specifies how similar two schemas must be to be considered to be the same flavor. As an example, consider the following rows:

Row 1: ColA, ColB, ColC, ColD
Row 2: ColA, ColB, ColE, ColF
Row 3: ColB, ColF, ColX, ColY

You can configure the columns returned for each flavor with different InferSimilarityMetric values, as in the following examples:

  • If you set InferSimilarityMetric to 1, the connector will return no flavors.
  • If you set InferSimilarityMetric to 0.5, the connector will return 2 flavors, Row1 and Row2 making up one, and Row3 making up another.
  • If you set InferSimilarityMetric to 0.25, the connector will return a single flavor containing all rows.

You can then query document flavors using dot notation, as in the following statement:

SELECT * FROM [Items.Technology]

This property enables additional configuration of Automatic Schema Discovery when you are using the Couchbase Infer command -- TypeDetectionScheme must also be set to Infer to use this propery.

CData Python Connector for Couchbase

FlexibleSchemas

Whether the provider allows queries to use columns that it has not discovered.

Data Type

bool

Default Value

false

Remarks

By default connector will only allow queries to use columns that it has found during the metadata discovery process (see TypeDetectionScheme for details). This means that the connector has the full information for each column it presents, but it also means that fields set on only a few documents may not be exposed. Disabling this option means that the connector will allow you to write a query with any columns you want. If you use columns in a query that have not been discovered the connector will assume that they are simple strings.

For example, the connector uses column type information to automatically convert dates for comparision since Couchbase cannot natively compare dates directly. If the connector detects that datecol is a date field, it can apply the STR_TO_MILLIS conversion automatically:

/* SQL */
WHERE datecol < '2020-06-12';

/* N1QL */
WHERE STR_TO_MILLIS(datecol) < STR_TO_MILLIS('2020-06-12');

When using undiscovered columns the connector cannot make this type of conversion for you. You must apply any needed conversions manually to ensure that operations behave the way you want them to.

CData Python Connector for Couchbase

ExposeTTL

Specifies whether document TTL information should be exposed.

Data Type

bool

Default Value

false

Remarks

By default the connector does not expose TTL values or consider document TTLs when performing DML operations. Enabling this option exposes TTL values in two ways:

  • All tables get a new column called Document.Expiration which contains the TTL value for each document. This column is an integer and returns whatever TTL value is stored in Couchbase directly. This column is read-write on bucket tables and read-only on child tables.
  • INSERT and UPDATE will use this field to set TTL values, or to preserve them (for update) when none is provided. Setting the field to either 0 or NULL will remove the TTL from any affected documents.

Note that enabling this features requires that your server be version 6.5.1 or later and that your CouchbaseService is set to N1QL. If either of these is not the case the connector will not connect.

CData Python Connector for Couchbase

NumericStrings

Whether to allow string values to be treated as numbers.

Data Type

bool

Default Value

true

Remarks

By default this property is enabled and the connector will treat string values as numeric if they all the values it samples during schema detection are numeric. This can cause type errors later on if the field contains non-numeric values in other documents. If this property is disabled then numeric strings are left as strings although other string-based data types like timestamps will still be detected.

For example, the "code" field in the below bucket would be affected by this setting. By default it would be considered an integer but if this property were enabled it would be treated as a string.

{ "code": "123", "message": "Please restart your computer" }
{ "code": "456", "message": "Urgent update must be applied" }

CData Python Connector for Couchbase

IgnoreChildAggregates

Whether the provider exposes aggregate columns that are also available as child tables. Ignored if TableSupport is not set to Full.

Data Type

bool

Default Value

false

Remarks

The connector will expose array fields within a bucket as a separate child table, such as in the Games_scores example described in Automatic Schema Discovery. By default the connector will also expose these array fields as JSON aggregates on the base table. For example, either of these queries would return information on game scores:

/* Return each score as an individual row */ 
SELECT value FROM Games_scores;

/* Return all scores for each Game as a JSON string */
SELECT scores FROM Games;

Since these aggregates are exposed on the base table, they will be generated even when the information they contain is redundant. For example, when performing this join the scores aggregate on Games is populated as well as the value column on Games_scores. Internally this causes two copies of the scores data to be transferred from Couchbase.

/* Retrieves score data twice, once for Games.scores and once for Games_scores.value */
SELECT * FROM Games INNER JOIN Games_scores ON Games.[Document.Id] = Games_scores.[Document.Id]

This option can be used to prevent the aggregate field from being exposed when the same information is also available from a child table. In the games example, setting this option to true means that the Games table would only expose a primary key column. The only way to retrieve information about scores would be the child table, so score data would only be read once from Couchbase.

/* Only exposes Document.Id, not scores */
SELECT * FROM Games;

/* Only retrieves score data once for Games_scores.value */
SELECT * FROM Games INNER JOIN Games_scores ON Games.[Document.Id] = Games_scores.[Document.Id]

Note that this option overrides FlattenArrays, since all data from flattened arrays is also avaialable as child tables. If this option is set then no array flattening is performed, even if FlattenArrays is set to a value over 0.

CData Python Connector for Couchbase

TableSupport

How much effort the provider will put into discovering tables on the Couchbase server.

Possible Values

Full, Basic, None

Data Type

string

Default Value

"Full"

Remarks

The available options are:

Full The connector will discover the available buckets, and look inside of each of those buckets for child tables. This provides the most flexible way to access nested data, but requires that each bucket on your server have primary indexes.
Basic The connector will discover the available buckets, but will not look inside of them for child tables. This is recommended for cases where you either want to reduce the time that schema detection takes, or if your buckets do not have primary indexes.
None The connector will only use the schema files found in the Location directory, and will not discover buckets on the server. This option should only be used after you have already created schema files. Using this option without schema files will result in no tables being available.

CData Python Connector for Couchbase

NewChildJoinsMode

Determines the kind of child table model the provider exposes.

Data Type

bool

Default Value

false

Remarks

By default the connector exposes a backwards-compatible data model that is not fully relational. In this mode non-child tables have a primary key called Document.Id, but child tables do not have a primary key. Instead they have a column called Document.Id which has the same value as the Document.Id of the parent row that contains the child row.

For example, a parent table invoices containing invoice records may look like this:

Document.Id customer
1 Adam
2 Beatrice
3 Charlie

And its child invoices_lineitems containing line items may look like this:

Document.Id item
1 laptop
1 keyboard
2 stapler
3 whiteboard
3 markers

This model has several limitations:

  • Complex JOIN results may be incorrect. In most cases the connector can translate a JOIN like SELECT * FROM invoices INNERT JOIN invoices_lineitems ON invoices.[Document.Id] = invoices_lineitems.[Document.Id] into an UNNEST. But if the JOIN is too complex then both sides are executed separately which can produce incorrect results.
  • DML operations on nested child tables are impossible because there is no way to specify what row of the middle child to use. For example, you cannot change rows in a table like invoices_lineitems_discounts because there is no way to specify the lineitem that contains the discount you are updating.
  • Some environments like SSIS may not be able to operate on child tables at all because they do not have primary keys.

The NewChildJoins data model is fully relational. In this mode non-child tables have the same Document.Id as before, but child tables are extended to have both a foreign key and a primary key. The foreign key is called Document.Parent and it refers to the Document.Id of the row in the parent table that contains the child row. The primary key is called Document.Id and it contains a path which uniquely refers to that child row.

For example, the same tables as above would look like this in the NewChildJoins model. invoices would be the same:

Document.Id customer
1 Adam
2 Beatrice
3 Charlie

However, invoices_lineitems would have both a primary and foreign key. The primary key contains the ID of the parent row as well as the child row's position in the parent.

Document.Id Document.Parent item
1$1 1 laptop
1$2 1 keyboard
2$1 2 stapler
3$1 3 whiteboard
3$2 3 markers

This fixes the limitations of the old data model:

  • Complex JOIN results are always consistent because they link foreign keys to primary keys. SELECT * FROM invoices INNERT JOIN invoices_lineitems ON invoices.[Document.Id] = invoices_lineitems.[Document.Parent]
  • DML operations on nested child tables are allowed because the Document.Id contains all the required information to pick out specific rows, regardless of the table's depth.
  • Environments which depend on primary keys can use these tables and generate JOIN queries since the relationships between Document.Id and Document.Parent columns are included in the connector metadata.

CData Python Connector for Couchbase

Caching

This section provides a complete list of the Caching properties you can configure in the connection string for this provider.


PropertyDescription
AutoCacheSpecifies whether the content of tables targeted by SELECT queries is automatically cached to the specified cache database.
CacheProviderThe namespace of an ADO.NET provider. The specified provider is used as the target database for all caching operations.
CacheDriverThe driver class of a JDBC driver. The specified driver is used to connect to the target database for all caching operations.
CacheConnectionSpecifies the connection string for the specified cache database.
CacheLocationSpecifies the path to the cache when caching to a file.
CacheToleranceNotes the tolerance, in seconds, for stale data in the specified cache database. Requires AutoCache to be set to True.
OfflineGets the data from the specified cache database instead of live Couchbase data.
CacheMetadataDetermines whether the provider caches table metadata to a file-based cache database.
CData Python Connector for Couchbase

AutoCache

Specifies whether the content of tables targeted by SELECT queries is automatically cached to the specified cache database.

Data Type

bool

Default Value

false

Remarks

When this connection property is set to True, the connector automatically caches the contents of tables targeted by SELECT queries. The content of these tables is cached to the cache database specified by the CacheConnection and CacheProvider connection properties.

See Also

For additional information, see:

  • CacheMetadata: With CacheMetadata enabled, all retrieved metadata is mirrored in the cache database. This means that any subsequent attempts by the connector to discover metadata are much faster, as this metadata is then read directly from the cache database, without needing to spend time requesting metadata from Couchbase.
  • Explicitly Caching Data: This topic provides examples for using AutoCache in Offline mode.
  • CACHE Statements: You can use the CACHE statement to explicitly cache the content of any table targeted by a SELECT query.

CData Python Connector for Couchbase

CacheProvider

The namespace of an ADO.NET provider. The specified provider is used as the target database for all caching operations.

Data Type

string

Default Value

""

Remarks

You can cache to ADO.NET providers saved in your ADO.NET global assembly cache (GAC).

CData ADO.NET providers automatically register themselves with the GAC during installation, so you don't need to do so manually.

Third-party ADO.NET providers may or may not automatically register themselves with the GAC during installation. If you want to cache to a third-party ADO.NET provider, consult the documentation for that provider to determine what steps (if any) you must take to register them with the GAC. Once they have been registered, you can supply their namespace in this connection property.

You must also set the CacheConnection connection property to provide a connection string for the specified ADO.NET provider.

The following sections show connection examples and address other requirements for several popular database providers. Refer to CacheConnection for more information on typical connection properties.

SQLite

You can use the Microsoft ADO.NET Provider for SQLite to cache to SQLite databases.

CacheProvider=Microsoft.Data.Sqlite;CacheConnection='DataSource=C:\\Users\\Public\\cache.db;'User='myusername';Password='mypassword';Server='http://couchbase40'

MySQL

To cache to MySQL, you can use the CData ADO.NET Provider for MySQL:
Cache Provider=System.Data.CData.MySQL;Cache Connection='Server=localhost;Port=3306;Database=cache;User=root;Password=123456';User=myUser;Password=myPassword;Security Token=myToken;

SQL Server

You can use the Microsoft .NET Framework Provider for SQL Server, included in the .NET Framework, to cache to SQL Server:

Cache Provider=System.Data.SqlClient;Cache Connection="Server=MyMACHINE\MyInstance;Database=SQLCACHE;User Id=root;Password=admin";User='myusername';Password='mypassword';Server='http://couchbase40'

Oracle

To cache to Oracle, you can use the Oracle Data Provider for .NET, as shown in the following example:

Cache Provider=Oracle.DataAccess.Client;Cache Connection='User Id=scott;Password=tiger;Data Source=ORCL';User='myusername';Password='mypassword';Server='http://couchbase40'

The Oracle Data Provider for .NET also requires the Oracle Database Client. When you download the Oracle Database Client, ensure that its bitness matches the bitness of your machine. When you install, select either the Runtime or Administrator installation type. The Instant Client is not sufficient.

PostgreSQL

To cache to PostgreSQL, you can use the CData ADO.NET Provider for PostgreSQL:
Cache Provider=System.Data.CData.PostgreSQL;Cache Connection='Server=localhost;Port=5432;Database=cache;User=postgres;Password=123456';User=myUser;Password=myPassword;Security Token=myToken;

CData Python Connector for Couchbase

CacheDriver

The driver class of a JDBC driver. The specified driver is used to connect to the target database for all caching operations.

Data Type

string

Default Value

""

Remarks

You can cache to any database for which you have a JDBC driver, including CData JDBC drivers.

Note: You must add the JAR file of the specified JDBC driver to the classpath. For CData JDBC drivers, you can find this JAR file in the "lib" subfolder of that driver's installation directory.

You must also set the CacheConnection connection property to provide a connection string for the specified JDBC driver.

For Linux systems and macOS, you need to create a config.ini file on the installation path of the driver (site-packages/cdata). The config.ini file has the following format (the driver and the path of the JDBC driver):

[salesforce.cpython-38-x86_64-linux-gnu.so]
CLASSPATH = /home/usrname/Downloads/lib/cdata.jdbc.postgresql.jar

Examples

The following examples show how to cache to several major databases. For more information on the JDBC URL syntax and typical connection properties, see CacheConnection.

Derby and Java DB

Java DB is the Oracle distribution of Derby. You must add the Derby JDBC driver's JAR file, derbytools.jar, to your classpath to cache to Java DB.

The Derby JDBC driver's JAR file is bundled in db-derby-10.17.1.0-bin.zip, which you can download from this page. You can find derbytools.jar in the "lib" subfolder of this zip file.

After adding derbytools.jar to the classpath, you can cache to a Java DB database as follows:

jdbc:couchbase:CacheDriver=org.apache.derby.jdbc.EmbeddedDriver;CacheConnection='jdbc:derby:sample';User='myusername';Password='mypassword';Server='http://couchbase40'
To cache to an in-memory database, use a JDBC URL like the following:
jdbc:couchbase:CacheDriver=org.apache.derby.jdbc.EmbeddedDriver;CacheConnection='jdbc:derby:memory';User='myusername';Password='mypassword';Server='http://couchbase40'

SQLite

The following is a JDBC URL for the SQLite JDBC driver:

jdbc:couchbase:CacheDriver=org.sqlite.JDBC;CacheConnection='jdbc:sqlite:C:/Temp/sqlite.db';User='myusername';Password='mypassword';Server='http://couchbase40'

MySQL

The following is a JDBC URL for the CData JDBC Driver for MySQL:

  jdbc:couchbase:Cache Driver=cdata.jdbc.mysql.MySQLDriver;Cache Connection='jdbc:mysql:Server=localhost;Port=3306;Database=cache;User=root;Password=123456';User='myusername';Password='mypassword';Server='http://couchbase40'
  

SQL Server

The following JDBC URL uses the Microsoft JDBC Driver for SQL Server:

jdbc:couchbase:Cache Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver;Cache Connection='jdbc:sqlserver://localhost\sqlexpress:7437;user=sa;password=123456;databaseName=Cache';User='myusername';Password='mypassword';Server='http://couchbase40'

Oracle

The following is a JDBC URL for the Oracle Thin Client:

jdbc:couchbase:Cache Driver=oracle.jdbc.OracleDriver;CacheConnection='jdbc:oracle:thin:scott/tiger@localhost:1521:orcldb';User='myusername';Password='mypassword';Server='http://couchbase40'
NOTE: If using a version of Oracle older than 9i, the cache driver will instead be oracle.jdbc.driver.OracleDriver .

PostgreSQL

The following JDBC URL uses the official PostgreSQL JDBC driver:

jdbc:couchbase:CacheDriver=cdata.jdbc.postgresql.PostgreSQLDriver;CacheConnection='jdbc:postgresql:User=postgres;Password=admin;Database=postgres;Server=localhost;Port=5432;';User='myusername';Password='mypassword';Server='http://couchbase40'

CData Python Connector for Couchbase

CacheConnection

Specifies the connection string for the specified cache database.

Data Type

string

Default Value

""

Remarks

The target cache database is determined by a combination of this connection property and the CacheProvider connection property. Both properties are required to use the specified cache database.

The connection string specified in this connection property is passed directly to the specified in the CacheProvider connection property. Consult the documentation for the specified for more information on its available connection properties.

Examples of common cache database settings can be found below.

SQLite

MySQL

The following are typical connection properties:

  • Server: The IP address or domain name of the server hosting the MySQL database that you want to cache to.
  • Port: The port on the specified server where your MySQL instance is running.
  • Database: The name of the MySQL database that you want to cache to. Must match the name of a MySQL database hosted on the specified server.
  • User: The username of a user registered with the selected MySQL database.
  • Password: The password associated with the specified MySQL user.

SQL Server

The following are typical SQL Server connection properties:

  • Server: The name or network address of the computer running SQL Server. To connect to a named instance instead of the default instance, specify the host name and the instance name, separated by a backslash.
  • Port: The port on the specified server where your SQL Server instance is running.
  • Database: The name of the SQL Server database you want to cache to. Must match the name of a SQL Server database hosted on the specified server.
  • Integrated Security: To use the current Windows account for authentication, set this option to True. To authenticate with User and Password instead, set this option to False.
  • User Id: The username of a user registered with the selected SQL Server database. This property is only needed if you are not using integrated security.
  • Password: The password associated with the specified SQL Server user. This property is only needed if you are not using integrated security.

Oracle

The following are typical connection properties:

  • Data Source: The connect descriptor that identifies the Oracle database. This can be a TNS connect descriptor, an Oracle Net Services name that resolves to a connect descriptor, or, after version 11g, an Easy Connect naming (the host name of the Oracle server with an optional port and service name).

  • User Id: The username of a user registered with the selected Oracle database.
  • Password: The password associated with the specified Oracle user.

PostgreSQL

The following are typical connection properties:

  • Host: The address of the server hosting the PostgreSQL database.
  • Port: The port on the specified host server where your PostgreSQL database is hosted.
  • Database: The name of the PostgreSQL database you want to cache to. Must match the name of a PostgreSQL database hosted on the specified server.
  • User name: The username of a user registered with the selected PostgreSQL database.
  • Password: The password associated with the specified user.

CData Python Connector for Couchbase

CacheLocation

Specifies the path to the cache when caching to a file.

Data Type

string

Default Value

"%APPDATA%\\CData\\Couchbase Data Provider"

Remarks

The CacheLocation is a simple, file-based cache.

If left unspecified, the default location is %APPDATA%\\CData\\Couchbase Data Provider, where %APPDATA% is set to the user's configuration directory:

Platform %APPDATA%
Windows The value of the APPDATA environment variable
Linux ~/.config

See Also

  • AutoCache: Set to implicitly create and maintain a cache for later offline use.
  • CacheMetadata: Set to persist the Couchbase catalog in CacheLocation.

CData Python Connector for Couchbase

CacheTolerance

Notes the tolerance, in seconds, for stale data in the specified cache database. Requires AutoCache to be set to True.

Data Type

int

Default Value

600

Remarks

When you execute a query for tables in the cache, the connector checks the time elapsed since the last update to the cache.

If the last update to the cache is older than the value of this connection property (measured in seconds), the connector refreshes the cache.

Otherwise, the connector returns data directly from the cache.

CData Python Connector for Couchbase

Offline

Gets the data from the specified cache database instead of live Couchbase data.

Data Type

bool

Default Value

false

Remarks

When this connection property is set to True, all queries execute against the cache database instead of the live Couchbase data.

In this mode, some SQL operations like INSERT, UPDATE, DELETE, and CACHE are disabled.

CData Python Connector for Couchbase

CacheMetadata

Determines whether the provider caches table metadata to a file-based cache database.

Data Type

bool

Default Value

false

Remarks

When this connection property is set to True, as you execute queries, table metadata in the Couchbase catalog is cached to the cache database specified by CacheConnection and CacheProvider, or, if those connection properties are not set, to the user's home directory.

The location of your home directory varies by platform:

PlatformHome Directory
Windows %APPDATA%\\CData\\Couchbase Data Provider
Mac ~/Library/Application Support/CData/Couchbase Data Provider
Unix ~/.config/CData/Couchbase Data Provider

A table's metadata is retrieved only once, when the table is queried for the first time.

When to Use CacheMetadata

When there are a large number of Couchbase tables and columns for the connector to retrieve during metadata discovery, the connector may take a while to list all table metadata.

You may experience slow metadata retrieval when:

  • Your Couchbase instance naturally has a large table count.
  • The connector has been configured, via its connection properties, to discover more tables than it would under its default configuration.
  • You make many short-lived connections to the connector.
With CacheMetadata enabled, all retrieved metadata is mirrored in the cache database. This means that any subsequent attempts by the connector to discover metadata are much faster, as this metadata is then read directly from the cache database, without needing to spend time requesting metadata from Couchbase.

When Not to Use CacheMetadata

The connector automatically persists metadata in memory for up to an hour when you first discover the metadata for a table or view, so CacheMetadata is generally not necessary.

CacheMetadata is not ideal in scenarios where you are working with volatile metadata. The first time you query a table, the connector caches its metadata to the cache database file. This cache is not dynamically updated to reflect updates to the table schema, so you must delete and rebuild the cache database file to pick up new, changed, or deleted columns.

CData Python Connector for Couchbase

Miscellaneous

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.


PropertyDescription
AllowJSONParametersAllows raw JSON to be used in parameters when QueryPassthrough is enabled.
ChildSeparatorThe character or characters used to denote child tables.
CreateTableRamQuotaThe default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.
DataverseSeparatorThe character or characters used to denote Analytics dataverses and scopes/collections.
FlattenArraysThe number of elements to expose as columns from nested arrays. Ignored if IgnoreChildAggregates is enabled.
FlattenObjectsSet FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.
FlavorSeparatorThe character or characters used to denote flavors.
GenerateSchemaFilesIndicates the user preference as to when schemas should be generated and saved.
InsertNullValuesDetermines whether an INSERT should include fields that have NULL values.
MaxRowsSpecifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
OtherSpecifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
PagesizeSpecifies the maximum number of records per page the provider returns when requesting data from Couchbase.
PeriodsSeparatorThe character or characters used to denote hierarchy.
PseudoColumnsSpecifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'.
QueryExecutionTimeoutThis sets the server-side timeout for the query, which governs how long Couchbase will execute the query before returning a timeout error.
QueryPassthroughThis option passes the query to the Couchbase server as is.
ReadonlyToggles read-only access to Couchbase from the provider.
RowScanDepthThe maximum number of rows to scan to look for the columns available in a table.
RTKSpecifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.
StrictComparisonAdjusts how precisely to translate filters on SQL input queries into Couchbase queries. This can be set to a comma-separated list of values, where each value can be one of: date, number, boolean, or string.
TimeoutSpecifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.
TransactionDurabilitySpecifies how a document must be stored for a transaction to succeed. Specifies whether to use N1QL transactions when executing queries.
TransactionTimeoutThis sets the amount of time a transaction may execute before it is timed out by Couchbase.
UpdateNullValuesDetermines whether an UPDATE writes NULL values as NULL, or removes them.
UseCollectionsForDDLWhether to assume that CREATE TABLE statements use collections instead of flavors. Only takes effect when connecting to Couchbase v7+ and GenerateSchemaFiles is set to OnCreate.
UserDefinedViewsSpecifies a filepath to a JSON configuration file that defines custom views. The provider automatically detects and uses the views specified in this file.
UseTransactionsSpecifies whether to use N1QL transactions when executing queries.
ValidateJSONParametersAllows the provider to validate that string parameters are valid JSON before sending the query to Couchbase.
CData Python Connector for Couchbase

AllowJSONParameters

Allows raw JSON to be used in parameters when QueryPassthrough is enabled.

Data Type

bool

Default Value

false

Remarks

This option affects how string parameters are handled when using direct N1QL and SQL++ queries through QueryPassthrough. For example, consider this query:

INSERT INTO `bucket` (KEY, VALUE) VALUES ("1", @x)

By default, this option is disabled and string parameters are quoted and escaped into JSON strings. That means that any value can be safely used as a string parameter, but it also means that parameters cannot be used as raw JSON documents:

/*
 * If @x is set to: test value " contains quote
 *
 * Result is a valid query
*/
INSERT INTO `bucket` (KEY, VALUE) VALUES ("1", "test value \" contains quote")

/*
 * If @x is set to: {"a": ["valid", "JSON", "value"]}
 *
 * Result contains string instead of JSON document
*/
INSERT INTO `bucket` (KEY, VALUE) VALUES ("1", "{\"a\": [\"valid\", \"JSON\", \"value\"]})

When this option is enabled, string parameters are assumed to be valid JSON. This means that raw JSON documents can be used as parameters, but it also means that all simple strings must be escaped:

/*
 * If @x is set to: test value " contains quote
 *
 * Result is an invalid query
*/
INSERT INTO `bucket` (KEY, VALUE) VALUES ("1", test value " contains quote)

/*
 * If @x is set to: {"a": ["valid", "JSON", "value"]}
 *
 * Result is a JSON document
*/
INSERT INTO `bucket` (KEY, VALUE) VALUES ("1", {"a": ["valid", "JSON", "value"]})

Please refer to ValidateJSONParameters for more details on how parameters are validated when this option is enabled.

CData Python Connector for Couchbase

ChildSeparator

The character or characters used to denote child tables.

Data Type

string

Default Value

"_"

Remarks

When creating a child table for an array underneath a bucket, the connector will generate the name of the child table by concatenating the name of the base table, along with this separator and each path element.

For example, if this document were in the bucket "customers", then the child table for the addresses field would be called "customers_addresses".

{
  "addresses": [
    {"street": "123 Main St"},
    {"street": "424 Pleasant Ct"},
    {"street": "719 Blue Way"}
  ]
}

CData Python Connector for Couchbase

CreateTableRamQuota

The default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.

Data Type

string

Default Value

"250"

Remarks

The default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.

CData Python Connector for Couchbase

DataverseSeparator

The character or characters used to denote Analytics dataverses and scopes/collections.

Data Type

string

Default Value

"."

Remarks

When using the Analytics serivce, the connector will scan all datasets from all available dataverses. To avoid potential name conflicts, it will include the dataverse name and the dataset name in the generated table name.

By default this is set to ".", so that if there is a dataset called "users" on the "Default" dataverse, then the table generated will be "Default.users".

This property is also used when generating table names for collections (on both N1QL and Analytics) on Couchbase 7 and later. For example, a bucket called "users" that has two collections called "active" and "inactive" under the "status" scope would be detected as the tables "users.status.active" and "users.status.inactive".

CData Python Connector for Couchbase

FlattenArrays

The number of elements to expose as columns from nested arrays. Ignored if IgnoreChildAggregates is enabled.

Data Type

string

Default Value

"0"

Remarks

By default, nested arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of nested arrays into columns of their own. This is only recommended for arrays that are expected to be short.

Set FlattenArrays to the number of elements you want to return from nested arrays. The specified elements are returned as columns. The zero-based index is concatenated to the column name. Other elements are ignored.

For example, you can return an arbitrary number of elements from an array of strings:

["FLOW-MATIC","LISP","COBOL"]
When FlattenArrays is set to 1, the preceding array is flattened into the following table:

Column NameColumn Value
languages.0FLOW-MATIC

CData Python Connector for Couchbase

FlattenObjects

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.

Data Type

bool

Default Value

true

Remarks

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON. The property name is concatenated onto the object name with an underscore to generate the column name.

For example, you can flatten the nested objects below at connection time:

address : {
  "street" : "123 Main St.",
  "city"   : "Nowhere",
  "state"  : "NY",
  "zip"    : "12345"
}
When FlattenObjects is set to true, the preceding object is flattened into the following table:

Column NameColumn Value
address.street123 Main St.
address.cityNowhere
address.stateNY
address.zip12345

CData Python Connector for Couchbase

FlavorSeparator

The character or characters used to denote flavors.

Data Type

string

Default Value

"."

Remarks

When the connector detects a flavored table, using either a DocType or Infer TypeDetectionScheme, it names flavored tables by concatenating the underlying bucket name, this seprator, and the value of the bucket's primary flavor.

For example, if the connector detects the flavor "docType = 'beer'" on the "beer-sample" bucket, then it will generate the table "beer-sample.beer" which contains only documents in "beer-sample" which have the "beer" doctype.

CData Python Connector for Couchbase

GenerateSchemaFiles

Indicates the user preference as to when schemas should be generated and saved.

Possible Values

Never, OnUse, OnStart, OnCreate

Data Type

string

Default Value

"Never"

Remarks

GenerateSchemaFiles enables you to save the table definitions identified by Automatic Schema Discovery. This property outputs schemas to .rsd files in the path specified by Location.

Available settings are the following:

  • Never: A schema file will never be generated.
  • OnUse: A schema file will be generated the first time a table is referenced, provided the schema file for the table does not already exist.
  • OnStart: A schema file will be generated at connection time for any tables that do not currently have a schema file.
  • OnCreate: A schema file will be generated by when running a CREATE TABLE SQL query.
Note that if you want to regenerate a file, you will first need to delete it.

Generate Schemas with SQL

When you set GenerateSchemaFiles to OnUse, the connector generates schemas as you execute SELECT queries. Schemas are generated for each table referenced in the query.

When you set GenerateSchemaFiles to OnCreate, schemas are only generated when a CREATE TABLE query is executed.

Generate Schemas on Connection

Another way to use this property is to obtain schemas for every table in your database when you connect. To do so, set GenerateSchemaFiles to OnStart and connect.

Alternatives to Static Schemas

If your data structures are volatile, consider setting GenerateSchemaFiles to Never and using dynamic schemas. See Automatic Schema Discovery for more information about dynamic schemas.

Editing Schemas

Schema files have a simple format that makes them easy to modify. See Custom Schema Definitions for more information.

CData Python Connector for Couchbase

InsertNullValues

Determines whether an INSERT should include fields that have NULL values.

Data Type

bool

Default Value

true

Remarks

By default the connector uses NULL values provided in an INSERT statement and inserts them as JSON null values.

If this option is disabled, SQL NULL values are ignored during an INSERT. In the case of array columns (FlattenArrays must be set to retrieve these), this means that array indices are shifted over to compensate for the values that have been removed.

CData Python Connector for Couchbase

MaxRows

Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.

Data Type

int

Default Value

-1

Remarks

The default value for this property, -1, means that no row limit is enforced unless the query explicitly includes a LIMIT clause. (When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting.)

Setting MaxRows to a whole number greater than 0 ensures that queries do not return excessively large result sets by default.

This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.

CData Python Connector for Couchbase

Other

Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.

Data Type

string

Default Value

""

Remarks

This property allows advanced users to configure hidden properties for specialized situations, with the advice of our Support team. These settings are not required for normal use cases but can address unique requirements or provide additional functionality. To define multiple properties, use a semicolon-separated list.

Note: It is strongly recommended to set these properties only when advised by the Support team to address specific scenarios or issues.

Caching Configuration

PropertyDescription
CachePartial=TrueCaches only a subset of columns, which you can specify in your query.
QueryPassthrough=TruePasses the specified query to the cache database instead of using the SQL parser of the connector.

Integration and Formatting

PropertyDescription
DefaultColumnSizeSets the default length of string fields when the data source does not provide column length in the metadata. The default value is 2000.
ConvertDateTimeToGMT=TrueConverts date-time values to GMT, instead of the local time of the machine. The default value is False (use local time).
RecordToFile=filenameRecords the underlying socket data transfer to the specified file.

CData Python Connector for Couchbase

Pagesize

Specifies the maximum number of records per page the provider returns when requesting data from Couchbase.

Data Type

int

Default Value

1000

Remarks

When processing a query, instead of requesting all of the queried data at once from Couchbase, the connector can request the queried data in pieces called pages.

This connection property determines the maximum number of results that the connector requests per page.

Note: Setting large page sizes may improve overall query execution time, but doing so causes the connector to use more memory when executing queries and risks triggering a timeout.

CData Python Connector for Couchbase

PeriodsSeparator

The character or characters used to denote hierarchy.

Data Type

string

Default Value

"."

Remarks

When flattening objects and arrays, the connector will use this value to separate different levels of objects and arrays. For example, if your Couchbase server returns a document like this (and FlattenObjects is enabled), then the connector will return the columns "geo.latitude" and "geo.longitude" if the periods separator is set to ".".

{
  "geo": {
    "latitude": 35.9132,
    "longitude": -79.0558
  }
}

CData Python Connector for Couchbase

PseudoColumns

Specifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'.

Data Type

string

Default Value

""

Remarks

This property allows you to define which pseudocolumns the connector exposes as table columns.

To specify individual pseudocolumns, use the following format:

Table1=Column1;Table1=Column2;Table2=Column3

To include all pseudocolumns for all tables use:

*=*

CData Python Connector for Couchbase

QueryExecutionTimeout

This sets the server-side timeout for the query, which governs how long Couchbase will execute the query before returning a timeout error.

Data Type

string

Default Value

"-1"

Remarks

Th default is -1, which disables the timeout. When enabling the timeout, the value must include both an amount and a unit, which can be one of: "ns" (nanoseconds), "us" (microseconds), "ms" (milliseconds), "s" (seconds), "m" (minutes) or "h" (hours). For example, "5m" and "300s" both set timeouts of 5 minutes.

There is a server-side timeout as well called the "index scan timeout", which will override this one if it is lower. By default the index scan timeout is 2 minutes, but it can be changed by setting the "indexer.settings.scan_timeout" property on your Couchbase server.

CData Python Connector for Couchbase

QueryPassthrough

This option passes the query to the Couchbase server as is.

Data Type

bool

Default Value

false

Remarks

When this is set, queries are passed through directly to Couchbase.

CData Python Connector for Couchbase

Readonly

Toggles read-only access to Couchbase from the provider.

Data Type

bool

Default Value

false

Remarks

When set to True, the connector allows only SELECT queries. Attempting an INSERT, UPDATE, DELETE, or stored procedure query fails with an error message.

CData Python Connector for Couchbase

RowScanDepth

The maximum number of rows to scan to look for the columns available in a table.

Data Type

int

Default Value

100

Remarks

The columns in a table must be determined by scanning table rows. This value determines the maximum number of rows that will be scanned.

Setting a high value may decrease performance. Setting a low value may prevent the data type from being determined properly, especially when there is null data.

CData Python Connector for Couchbase

RTK

Specifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.

Data Type

string

Default Value

""

Remarks

This property is typically unnecessary, as most configurations support a standard licensing mechanism.

Warning: The value of this property takes precedence over all existing licensing information. To avoid licensing errors, ensure the provided runtime key is correct.

CData Python Connector for Couchbase

StrictComparison

Adjusts how precisely to translate filters on SQL input queries into Couchbase queries. This can be set to a comma-separated list of values, where each value can be one of: date, number, boolean, or string.

Data Type

string

Default Value

""

Remarks

This option is empty by default, which means that WHERE clauses sent to Couchbase will include extra functions that convert values so that more comparisons work.

For example, leaving the "string" setting out of the list causes arrays to be converted, so that they can be compared with strings:

SELECT * FROM Bucket WHERE MyArrayColumn = '[1,2,3]'

If set to a value, queries including the relevant types of comparisons will be translated literally. This makes better use of Couchbase's indexes, but means that the types of comparisons must be in a format Couchbase can compare directly.

For example, if "date" is provided as one of the options, then dates must match the format they are stored as in Couchbase since they will not be converted automatically:

SELECT * FROM Bucket WHERE MyDateColumn = '2018-10-31T10:00:00';

CData Python Connector for Couchbase

Timeout

Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.

Data Type

int

Default Value

60

Remarks

The timeout applies to each individual communication with the server rather than the entire query or operation. For example, a query could continue running beyond 60 seconds if each paging call completes within the timeout limit.

Timeout is set to 60 seconds by default. To disable timeouts, set this property to 0.

Disabling the timeout allows operations to run indefinitely until they succeed or fail due to other conditions such as server-side timeouts, network interruptions, or resource limits on the server.

Note: Use this property cautiously to avoid long-running operations that could degrade performance or result in unresponsive behavior.

CData Python Connector for Couchbase

TransactionDurability

Specifies how a document must be stored for a transaction to succeed. Specifies whether to use N1QL transactions when executing queries.

Possible Values

None, Majority, MajorityAndPersistActive, PersistToMajority

Data Type

string

Default Value

"Majority"

Remarks

If UseTransactions is enabled, then this option can be set to determine when Couchbase will allow writes in transactions to commit. The Couchbase documentation on Durability and Transactions contains the full details, below is a high-level summary.

This option controls requirements on both quorum and persistence. The quorum may either require no bucket replicas to receive the document (None), or a majority of replicas to have the document (all others). The persistence level requires either that the document be stored in the replica memory (Majoriy) or on the replica disk (MajorityAndPersistActive, PersistToMajority).

None is only useful if the bucket you are using is not configured for replicas. The other options can be used depending on the required performance and durability tradeoffs. Persisting to more replicas is slower but provides greater resilience against a node crashing.

CData Python Connector for Couchbase

TransactionTimeout

This sets the amount of time a transaction may execute before it is timed out by Couchbase.

Data Type

string

Default Value

""

Remarks

If transactions are enabled, then the connector will default to the server's default transaction timeout setting.

When enabling the timeout, the value must include both an amount and a unit, which can be one of: "ns" (nanoseconds), "us" (microseconds), "ms" (milliseconds), "s" (seconds), "m" (minutes) or "h" (hours). For example, "5m" and "300s" both set timeouts of 5 minutes.

There are also cluster-level and node-level transaction timeouts which override this one if they are smaller. For example, if the node-level timeout is set to a minute then setting this option to "5m" will have no effect.

CData Python Connector for Couchbase

UpdateNullValues

Determines whether an UPDATE writes NULL values as NULL, or removes them.

Data Type

bool

Default Value

true

Remarks

By default the connector will use NULL values provided in an UPDATE statement and set the field in Couchbase to NULL.

If this option is disabled SQL NULL values in an UPDATE will cause the connector to mark the field as MISSING. This removes the field from the object containing it, or if the field is contained in an array (per FlattenArrays) then that element is set to NULL.

This option should be used with care as the connector may not detect that the field exists if it is removed from enough documents within a bucket.

CData Python Connector for Couchbase

UseCollectionsForDDL

Whether to assume that CREATE TABLE statements use collections instead of flavors. Only takes effect when connecting to Couchbase v7+ and GenerateSchemaFiles is set to OnCreate.

Data Type

bool

Default Value

false

Remarks

Normally the connector will assume that compound table names referenced in a CREATE TABLE statement are flavors. For compatibility, this is still the default with Couchbase v7+ even though flavors are not recommended there.

CREATE TABLE [myBucket.myFlavor](
  [Document.Id] VARCHAR PRIMARY KEY,
  docType VARCHAR,
  sometext VARCHAR,
  somenum INT
)

Enable this option to assume that CREATE TABLE statements refer to collection instead. In that scenario this query willl create the bucket and scope if necessary, before creating the colleciton and setting a primary index:

CREATE TABLE [myBucket.myScope.myCollection](
  [Document.Id] VARCHAR PRIMARY KEY,
  sometext VARCHAR,
  somenum INT
)

CData Python Connector for Couchbase

UserDefinedViews

Specifies a filepath to a JSON configuration file that defines custom views. The provider automatically detects and uses the views specified in this file.

Data Type

string

Default Value

""

Remarks

UserDefinedViews allows you to define and manage custom views through a JSON-formatted configuration file called UserDefinedViews.json. These views are automatically recognized by the connector and enable you to execute custom SQL queries as if they were standard database views. The JSON file defines each view as a root element with a child element called "query", which contains the SQL query for the view.

For example:

{
	"MyView": {
		"query": "SELECT * FROM [MyBucket].[MyScope].[Customer] WHERE MyColumn = 'value'"
	},
	"MyView2": {
		"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
	}
}

You can use this property to define multiple views in a single file and specify the filepath. For example:

UserDefinedViews=C:\Path\To\UserDefinedViews.json
When you specify a view in UserDefinedViews, the connector only sees that view.

For further information, see User Defined Views.

CData Python Connector for Couchbase

UseTransactions

Specifies whether to use N1QL transactions when executing queries.

Possible Values

Never, Always, Explicit

Data Type

string

Default Value

"Never"

Remarks

By default the connector does not use transactions for compatibility with older versions of Couchbase. All of the other options require a connection to Couchbase 7 or above. The N1QL service must also be enabled using CouchbaseService.

Setting this to Always means that all queries will use transactions. An explicit transaction may be created on the connection and queries will use that transaction while it is active. If there is no explicit transaction then queries will use implicit transactions instead.

Setting this to Explicit enables support for explicit transactions only. Explicit transactions may be created but if one is not currently active, then statements will not create an implicit transaction.

CData Python Connector for Couchbase

ValidateJSONParameters

Allows the provider to validate that string parameters are valid JSON before sending the query to Couchbase.

Data Type

bool

Default Value

true

Remarks

When AllowJSONParameters and QueryPassthrough are enabled, the query parameters given to the connector will be treated as raw JSON documents instead of arbitrary string values. This option controls what happens when invalid JSON is given to the connector in this mode.

When this option is enabled, the connector will check that all string parameters can be parsed as valid JSON. If any cannot be, an error will be raised and the query will not be run.

When this option is disabled, no check is performed and all string parameter values are substituted into the query directly. This makes executing prepared statements faster, but less safe since invalid N1QL or SQL++ may be sent to the Couchbase.

CData Python Connector for Couchbase

Third Party Copyrights

LZMA from 7Zip LZMA SDK

LZMA SDK is placed in the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original LZMA SDK code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

LZMA2 from XZ SDK

Version 1.9 and older are in the public domain.

Xamarin.Forms

Xamarin SDK

The MIT License (MIT)

Copyright (c) .NET Foundation Contributors

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

NSIS 3.10

Copyright (C) 1999-2025 Contributors THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means:

a) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and b) in the case of each subsequent Contributor:

i) changes to the Program, and

ii) additions to the Program;

where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.

"Contributor" means any person or entity that distributes the Program.

"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Program" means the Contributions distributed in accordance with this Agreement.

"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

2. GRANT OF RIGHTS

a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

3. REQUIREMENTS

A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that:

a) it complies with the terms and conditions of this Agreement; and

b) its license agreement:

i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;

ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;

iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and

iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.

When the Program is made available in source code form:

a) it must be made available under this Agreement; and

b) a copy of this Agreement must be included with each copy of the Program.

Contributors may not remove or alter any copyright notices contained within the Program.

Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.

4. COMMERCIAL DISTRIBUTION

Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. IBM is the initial Agreement Steward. IBM may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.

AdoptOpenJDK / Adoptium Temurin JRE 17.0.18_8

Copyright (c) Eclipse Foundation AISBL. All Rights Reserved.

Apache License, Version 2.0

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

  1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
  2. You must cause any modified files to carry prominent notices stating that You changed the files; and
  3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
  4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

Eclipse Distribution License - v 1.0

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the Eclipse Foundation, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Eclipse Public License - v 2.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS "Contribution" means:

  • a) in the case of the initial Contributor, the initial content Distributed under this Agreement, and
  • b) in the case of each subsequent Contributor:
    • i) changes to the Program, and
    • ii) additions to the Program;
    where such changes and/or additions to the Program originate from and are Distributed by that particular Contributor. A Contribution "originates" from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include changes or additions to the Program that are not Modified Works.
"Contributor" means any person or entity that Distributes the Program. "Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Program" means the Contributions Distributed in accordance with this Agreement.

"Recipient" means anyone who receives the Program under this Agreement or any Secondary License (as applicable), including Contributors.

"Derivative Works" shall mean any work, whether in Source Code or other form, that is based on (or derived from) the Program and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.

"Modified Works" shall mean any work in Source Code or other form that results from an addition to, deletion from, or modification of the contents of the Program, including, for purposes of clarity any new file in Source Code form that contains any contents of the Program. Modified Works shall not include works that contain only declarations, interfaces, types, classes, structures, or files of the Program solely in each case in order to link to, bind by name, or subclass the Program or Modified Works thereof.

"Distribute" means the acts of a) distributing or b) making available in any manner that enables the transfer of a copy.

"Source Code" means the form of a Program preferred for making modifications, including but not limited to software source code, documentation source, and configuration files.

"Secondary License" means either the GNU General Public License, Version 2.0, or any later versions of that license, including any exceptions or additional permissions as identified by the initial Contributor.

2. GRANT OF RIGHTS

  • a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, Distribute and sublicense the Contribution of such Contributor, if any, and such Derivative Works.
  • b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in Source Code or other form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.
  • c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to Distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.
  • d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.
  • e) Notwithstanding the terms of any Secondary License, no Contributor makes additional grants to any Recipient (other than those set forth in this Agreement) as a result of such Recipient's receipt of the Program under the terms of a Secondary License (if permitted under the terms of Section 3).

3. REQUIREMENTS 3.1 If a Contributor Distributes the Program in any form, then:

  • a) the Program must also be made available as Source Code, in accordance with section 3.2, and the Contributor must accompany the Program with a statement that the Source Code for the Program is available under this Agreement, and informs Recipients how to obtain it in a reasonable manner on or through a medium customarily used for software exchange; and
  • b) the Contributor may Distribute the Program under a license different than this Agreement, provided that such license:
    • i) effectively disclaims on behalf of all other Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;
    • ii) effectively excludes on behalf of all other Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;
    • iii) does not attempt to limit or alter the recipients' rights in the Source Code under section 3.2; and
    • iv) requires any subsequent distribution of the Program by any party to be under a license that satisfies the requirements of this section 3.
3.2 When the Program is Distributed as Source Code:
  • a) it must be made available under this Agreement, or if the Program (i) is combined with other material in a separate file or files made available under a Secondary License, and (ii) the initial Contributor attached to the Source Code the notice described in Exhibit A of this Agreement, then the Program may be made available under the terms of such Secondary Licenses, and
  • b) a copy of this Agreement must be included with each copy of the Program.
3.3 Contributors may not remove or alter any copyright, patent, trademark, attribution notices, disclaimers of warranty, or limitations of liability (‘notices') contained within the Program from any copy of the Program which they Distribute, provided that Contributors may add their own appropriate notices.

4. COMMERCIAL DISTRIBUTION Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be Distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to Distribute the Program (including its Contributions) under the new version.

Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. Nothing in this Agreement is intended to be enforceable by any entity that is not a Contributor or Recipient. No third-party beneficiary rights are created under this Agreement.

Exhibit A – Form of Secondary Licenses Notice "This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), version(s), and exceptions or additional permissions here}."

Simply including a copy of this Agreement, including this Exhibit A is not sufficient to license the Source Code under Secondary Licenses.

If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.

You may add additional accurate notices of copyright ownership.

GNU Classpath

Classpath is distributed under the terms of the GNU General Public License with the following clarification and special exception.

Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

As such, it can be used to run, create and distribute a large class of applications and applets. When GNU Classpath is used unmodified as the core class library for a virtual machine, compiler for the java languge, or for a program written in the java programming language it does not affect the licensing for distributing those programs directly.

OpenJDK Assembly Exception

The OpenJDK source code made available by Oracle America, Inc. (Oracle) at openjdk.java.net ("OpenJDK Code") is distributed under the terms of the GNU General Public License <http://www.gnu.org/copyleft/gpl.html> version 2 only ("GPL2"), with the following clarification and special exception.

Linking this OpenJDK Code statically or dynamically with other code is making a combined work based on this library. Thus, the terms and conditions of GPL2 cover the whole combination.

As a special exception, Oracle gives you permission to link this OpenJDK Code with certain code licensed by Oracle as indicated at http://openjdk.java.net/legal/exception-modules-2007-05-08.html ("Designated Exception Modules") to produce an executable, regardless of the license terms of the Designated Exception Modules, and to copy and distribute the resulting executable under GPL2, provided that the Designated Exception Modules continue to be governed by the licenses under which they were offered by Oracle.

As such, it allows licensees and sublicensees of Oracle's GPL2 OpenJDK Code to build an executable that includes those portions of necessary code that Oracle could not provide under GPL2 (or that Oracle has provided under GPL2 with the Classpath exception). If you modify or add to the OpenJDK code, that new GPL2 code may still be combined with Designated Exception Modules if the new code is made subject to this exception by its copyright holder.

Copyright (c) 2026 CData Software, Inc. - All rights reserved.
Build 26.0.9655