Allows raw JSON to be used in parameters when QueryPassthrough is enabled.

bool

false

This option affects how string parameters are handled when using direct N1QL and SQL++ queries through QueryPassthrough. For example, consider this query:

 

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:

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:

Please refer to ValidateJSONParameters for more details on how parameters are validated when this option is enabled.

The port for connecting to the Couchbase Analytics Endpoint. Defaults to 8095 for plaintext.

string

""

The port for connecting to the Couchbase Analytics Endpoint. If empty, the default ports will be assumed, 8093 for plaintext

The type of authentication to use when connecting to Couchbase.

string

"Auto"

Note that only Basic authentication is supported when using the Cloud ConnectionMode.

string

"_"

When creating a child table for an array underneath a bucket, the adapter 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".

Determines how to connect to the Couchbase server. Must be either Direct or Cloud.

string

"Direct"

By default the adapter 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 Cloud or a custom deployment that uses service records. These records will allow the adapter to determine the exact Couchbase servers that provide the appropriate CouchbaseService. You must also set the DNSServer property so that the adapter 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:

Determines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics.

string

"N1QL"

Determines the Couchbase service to connect to. Default is N1QL. Available options are N1QL and Analytics

The default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.

string

"250"

The default RAM quota, in megabytes, to use when inserting buckets via the CREATE TABLE syntax.

A file containing a list of credentials to access Couchbase. This takes priority over other forms of Authentication.

string

""

A file containing a list of credentials to access Couchbase. This takes priority over other forms of Authentication.

The dataverse to connect to when using the Analytics service.

string

"Default"

If no value is provided, the Default dataverse is used.

The character or characters used to denote Analytics dataverses.

string

"."

When using the Analytics serivce, the adapter 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".

Determines what DNS server to use when retrieving Couchbase Cloud information.

string

""

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.

Specifies whether document TTL information should be exposed.

bool

false

By default the adapter does not expose TTL values or consider document TTLs when performing DML operations. Enabling this option exposes TTL values in two ways:

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 adapter will not connect.

A password used to authenticate to a proxy-based firewall.

string

""

This property is passed to the proxy specified by FirewallServer and FirewallPort, following the authentication method specified by FirewallType.

The TCP port for a proxy-based firewall.

string

""

This specifies the TCP port for a proxy allowing traversal of a firewall. Use FirewallServer to specify the name or IP address. Specify the protocol with FirewallType.

The name or IP address of a proxy-based firewall.

string

""

This property specifies the IP address, DNS name, or host name of a proxy allowing traversal of a firewall. The protocol is specified by FirewallType: Use FirewallServer with this property to connect through SOCKS or do tunneling. Use ProxyServer to connect to an HTTP proxy.

Note that the adapter uses the system proxy by default. To use a different proxy, set ProxyAutoDetect to false.

The protocol used by a proxy-based firewall.

string

"NONE"

This property specifies the protocol that the adapter will use to tunnel traffic through the FirewallServer proxy. Note that by default the adapter connects to the system proxy; to disable this behavior and connect to one of the following proxy types, set ProxyAutoDetect to false.

 

To connect to HTTP proxies, use ProxyServer and ProxyPort. To authenticate to HTTP proxies, use ProxyAuthScheme, ProxyUser, and ProxyPassword.

The user name to use to authenticate with a proxy-based firewall.

string

""

The FirewallUser and FirewallPassword properties are used to authenticate against the proxy specified in FirewallServer and FirewallPort, following the authentication method specified in FirewallType.

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. Set FlattenArrays to the number of elements you want to return from nested arrays.

string

"0"

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:

When FlattenArrays is set to 1, the preceding array is flattened into the following table:

 

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.

bool

true

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:

When FlattenObjects is set to true, the preceding object is flattened into the following table:

 

The character or characters used to denote flavors.

string

"."

When the adapter 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 adapter 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.

Whether the provider allows queries to use columns that it has not discovered.

bool

false

By default adapter will only allow queries to use columns that it has found during the metadata discovery process (see TypeDetectionScheme for details). This means that the adapter 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 adapter 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 adapter will assume that they are simple strings.

For example, the adapter uses column type information to automatically convert dates for comparision since Couchbase cannot natively compare dates directly. If the adapter detects that datecol is a date field, it can apply the STR_TO_MILLIS conversion automatically:

When using undiscovered columns the adapter 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.

Indicates the user preference as to when schemas should be generated and saved.

string

"Never"

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.

Note that if you want to regenerate a file, you will first need to delete it.

When you set GenerateSchemaFiles to OnUse, the adapter generates schemas as you execute SELECT queries. Schemas are generated for each table referenced in the query.

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.

Schema files have a simple format that makes them easy to modify. See Custom Schema Definitions for more information.

Whether the provider exposes aggregate columns that are also available as child tables. Ignored if TableSupport is not set to Full.

bool

false

The adapter 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 adapter 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:

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.

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.

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.

The maximum number of values for every field to scan before determining its data type.

string

"10"

The maximum number of values for every field to scan before determining its data type.

The maximum number of documents to scan for the columns available in the bucket.

string

"100"

Since Couchbase is schemaless, this property controls the maximum number of values of each field that will be scanned to determine datatype of a column.

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.

Specifies the similarity degree where different schemas will be considered to be the same flavor.

string

"0.7"

Specifies the similarity degree where different schemas will be considered to be the same flavor.

A path to the directory that contains the schema files defining tables, views, and stored procedures.

string

""

The path to a directory which contains the schema files for the adapter (.rsd files for tables and views, .rsb files for stored procedures). The Location property is only needed if you would like to customize definitions (e.g., change a column name, ignore a column, etc.) or extend the data model with new tables, views, or stored procedures.

The schema files are deployed alongside the adapter assemblies. You must also ensure that Location points to the folder that contains the schema files. The folder location can be a relative path from the location of the executable.

Core modules to be included in the log file.

string

""

Only the modules specified (separated by ';') will be included in the log file. By default all modules are included.

Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time.

string

"-1"

Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time.

The port for connecting to the Couchbase N1QL Endpoint. Default 8093 for plaintext and 18093 for SSL.

string

""

The port for connecting to the Couchbase N1QL Endpoint. If empty, default ports will be assumed, 8093 for plaintext and 18093 for SSL, based on the value specified in UseSSL.

The other parameters necessary to connect to a data source, such as username and password, when applicable.

string

""

The Other property is a semicolon-separated list of name-value pairs used in connection parameters specific to a data source.

The number of results to return per page of data retrieved from the Couchbaseserver.

string

"1000"

The number of results to return per page of data retrieved from the Couchbase server.

The password used to authenticate to Couchbase.

string

""

The password used to authenticate to Couchbase.

The character or characters used to denote hierarchy.

string

"."

In order to flatten out hierarchical structures, the adapter needs some specifier that states the path to a column through the hierarchy. If this value is "." and a column comes back with the name address.city, this indicates that there is a mapped attribute with a child called city. If your data has columns that already use a single period within the attribute name, set the PeriodsSeparator to a different character or characters.

The authentication type to use to authenticate to the ProxyServer proxy.

string

"BASIC"

This value specifies the authentication type to use to authenticate to the HTTP proxy specified by ProxyServer and ProxyPort.

Note that the adapter will use the system proxy settings by default, without further configuration needed; if you want to connect to another proxy, you will need to set ProxyAutoDetect to false, in addition to ProxyServer and ProxyPort. To authenticate, set ProxyAuthScheme and set ProxyUser and ProxyPassword, if needed.

The authentication type can be one of the following:

BASIC: The adapter performs HTTP BASIC authentication.

DIGEST: The adapter performs HTTP DIGEST authentication.

NEGOTIATE: The adapter retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.

PROPRIETARY: The adapter does not generate an NTLM or Kerberos token. You must supply this token in the Authorization header of the HTTP request.

If you need to use another authentication type, such as SOCKS 5 authentication, see Firewall Type.

This indicates whether to use the system proxy settings or not. Set ProxyAutoDetect to FALSE to use custom proxy settings. This takes precedence over other proxy settings.

bool

true

By default, the adapter uses the system HTTP proxy. Set this to false if you want to connect to another proxy.

To connect to an HTTP proxy, see Proxy Server.

For other proxies, such as SOCKS or tunneling, see Firewall Type.

A semicolon separated list of hosts or IPs that will be exempt from connecting through the ProxyServer .

string

""

The ProxyServer will be used for all addresses, except for addresses defined in this property. Use semicolons to separate entries.

Note that the adapter will use the system proxy settings by default, without further configuration needed; if you want to explicitly configure proxy exceptions for this connection, you will need to set ProxyAutoDetect to false, and configure ProxyServer and ProxyPort. To authenticate, set ProxyAuthScheme and set ProxyUser and ProxyPassword, if needed.

A password to be used to authenticate to the ProxyServer proxy.

string

""

This property is used to authenticate to an HTTP proxy server that supports NTLM (Windows), Kerberos, or HTTP authentication. To specify the HTTP proxy, you can set ProxyServer and ProxyPort. To specify the authentication type, set ProxyAuthScheme.

If you are using HTTP authentication, additionally set ProxyUser and ProxyPassword to HTTP proxy.

If you are using NTLM authentication, set ProxyUser and ProxyPassword to your Windows password. You may also need these to complete Kerberos authentication.

For SOCKS 5 authentication or tunneling, see Firewall Type.

By default, the adapter uses the system proxy. If you want to connect to another proxy, set ProxyAutoDetect to false.

The TCP port the ProxyServer proxy is running on.

string

"80"

The port the HTTP proxy is running on that you want to redirect HTTP traffic through. Specify the HTTP proxy in ProxyServer. For other proxy types, see Firewall Type.

The hostname or IP address of a proxy to route HTTP traffic through.

string

""

The hostname or IP address of a proxy to route HTTP traffic through. The adapter can use the HTTP, Windows (NTLM), or Kerberos authentication types to authenticate to an HTTP proxy.

If you need to connect through a SOCKS proxy or tunnel the connection, see Firewall Type.

By default, the adapter uses the system proxy. If you need to use another proxy, set ProxyAutoDetect to false.

The SSL type to use when connecting to the ProxyServer proxy.

string

"AUTO"

This property determines when to use SSL for the connection to an HTTP proxy specified by ProxyServer. This value can be AUTO, ALWAYS, NEVER, or TUNNEL. The applicable values are the following:

 

A user name to be used to authenticate to the ProxyServer proxy.

string

""

The ProxyUser and ProxyPassword options are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

You can select one of the available authentication types in ProxyAuthScheme. If you are using HTTP authentication, set this to the username of a user recognized by the HTTP proxy. If you are using Windows or Kerberos authentication, set this property to a username in one of the following formats:

This sets the server-side timeout for the query, which governs how long Couchbase will execute the query before returning a timeout error.

string

"-1"

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.

You can use this property to enforce read-only access to Couchbase from the provider.

bool

false

If this property is set to true, the adapter will allow only SELECT queries. INSERT, UPDATE, DELETE, and stored procedure queries will cause an error to be thrown.

The maximum number of documents to scan for the columns available in the bucket.

string

"100"

Since Couchbase is schemaless, this property controls the maximum number of documents that will be scanned to determine columns for the bucket.

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.

The address of the Couchbase server to which you are connecting.

string

""

The address of the Couchbase server to which you are connecting.

The TLS/SSL client certificate store for SSL Client Authentication (2-way SSL).

string

""

The name of the certificate store for the client certificate.

The SSLClientCertType field specifies the type of the certificate store specified by SSLClientCert. If the store is password protected, specify the password in SSLClientCertPassword.

SSLClientCert is used in conjunction with the SSLClientCertSubject field in order to specify client certificates. If SSLClientCert has a value, and SSLClientCertSubject is set, a search for a certificate is initiated. See SSLClientCertSubject for more information.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

 

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (for example, PKCS12 certificate store).

The password for the TLS/SSL client certificate.

string

""

If the certificate store is of a type that requires a password, this property is used to specify that password to open the certificate store.

The subject of the TLS/SSL client certificate.

string

"*"

When loading a certificate the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property. If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks the first certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For example, "CN=www.server.com, OU=test, C=US, E=support@company.com". The common fields and their meanings are shown below.

 

If a field value contains a comma, it must be quoted.

The type of key store containing the TLS/SSL client certificate.

string

""

This property can take one of the following values:

 

The certificate to be accepted from the server when connecting using TLS/SSL.

string

""

If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine will be rejected.

This property can take the forms:

 

 

If not specified, any certificate trusted by the machine will be accepted. Use '*' to signify to accept all certificates (not recommended for security concerns).

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.

string

""

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:

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:

How much effort the provider will put into discovering tables on the Couchbase server.

string

"Full"

The available options are:

 

The value in seconds until the timeout error is thrown, canceling the operation.

string

"60"

If the Timeout property is set to 0, operations do not time out: They run until they complete successfully or encounter an error condition.

If Timeout expires and the operation is not yet complete, the adapter throws an exception.

Determines how the provider builds tables and columns from the buckets found in Couchbase.

Data Type

"DocType"

The available options are:

The user who is authenticating to Couchbase.

string

""

The user who is authenticating to Couchbase.

This property is used to determine the port for connecting to the Couchbase N1QL Endpoint. If false, the default, default ports will be assumed, 8093 for plaintext and 18093 for SSL, based on the value specified in UseSSL.

bool

false

This property is used to determine the port for connecting to the Couchbase N1QL Endpoint. If false, the default, default ports will be assumed, 8093 for plaintext and 18093 for SSL, based on the value specified in UseSSL.

Allows the provider to validate that string parameters are valid JSON before sending the query to Couchbase.

bool

true

When AllowJSONParameters and QueryPassthrough are enabled, the query parameters given to the adapter will be treated as raw JSON documents instead of arbitrary string values. This option controls what happens when invalid JSON is given to the adapter in this mode.

When this option is enabled, the adapter 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.

The port for connecting to the Couchbase Web Console. Default 8091 for plaintext and 18091 for SSL.

string

""

The port for connecting to the Couchbase Web Console. If left empty, default ports will be assumed, 8091 for plaintext and 18091, based on the value specified in UseSSL.