Adding a Connection to Google Sheets

1. In the application console, navigate to the Connections page.
2. At the Add Connections panel, select the icon for the connection you want to add.
3. If the Google Sheets icon is not available, click the Add More icon to download and install the Google Sheets connector from the CData site.

For required properties, see the Settings tab.

For connection properties that are not typically required, see the Advanced tab.

Connecting to Google Sheets

The following sections focus on authentication as a User, and authentication as a Service.

Authenticating as a User (OAuth)

The following subsections describe how to authenticate to Google Sheets from a User account (AuthScheme OAuth) via three common authentication flows:

• Desktop: a connection to a server on the user's local machine, frequently used for testing and prototyping. Authenticated via either embedded OAuth or custom OAuth.
• Web: access to data via a shared website. Authenticated via custom OAuth only.
• Headless Server: a dedicated computer that provides services to other computers and their users, which is configured to operate without a monitor and keyboard. Authenticated via embedded OAuth or custom OAuth.

For information about how to create a custom OAuth application, and why you might want to create one even for auth flows that have embedded OAuth credentials, see Creating a Custom OAuth Application. For a complete list of connection string properties available in Google Sheets, see Connection.

When the access token expires, the Sync App refreshes it automatically.

Automatic refresh of the OAuth access token:

To have the Sync App automatically refresh the OAuth access token, do the following:

1. The first time you connect to data, set the following connection parameters:
   • InitiateOAuth: REFRESH.
   • OAuthClientId: The client Id in your application settings.
   • OAuthClientSecret: The client secret in your application settings.
   • OAuthAccessToken: The access token returned by GetOAuthAccessToken.
   • OAuthSettingsLocation: The path where you want the Sync App to save the OAuth values, which persist across connections.
2. On subsequent data connections, set the following:
   • InitiateOAuth
   • OAuthSettingsLocation

Manual refresh of the OAuth access token:

The only value needed to manually refresh the OAUth access token is the OAuth refresh token.

1. To manually refresh the OAuthAccessToken after the ExpiresIn period (returned by GetOAuthAccessToken) has elapsed, call the RefreshOAuthAccessToken stored procedure.
2. Set the following connection properties:
   • OAuthClientId: The Client Id in your application settings.
   • OAuthClientSecret: The Client Secret in your application settings.

3. Call RefreshOAuthAccessToken with OAuthRefreshToken set to the OAuth refresh token returned by GetOAuthAccessToken.
4. After the new tokens have been retrieved, set the OAuthAccessToken property to the value returned by RefreshOAuthAccessToken. This opens a new connection.

Store the OAuth refresh token so that you can use it to manually refresh the OAuth access token after it has expired.

Required Scopes and Endpoint Domains for Google Sheets

These permissions are defined by access scopes, which determine what data your application can access and what actions it can perform.

This topic provides information about the required access scopes and endpoint domains for the Google Sheets Sync App.

Understanding Scopes

Scopes are a way to limit an application's access to a user's data. They define the specific actions that an application can perform on behalf of the user.

For example, a read-only scope might allow an application to view data, while a full access scope might allow it to modify data.

Required Scopes for Google Sheets

Understanding Endpoint Domains

Endpoint domains are the specific URLs that the application needs to communicate with in order to authenticate, retrieve records, and perform other essential operations.

Allowlisting these domains ensures that the network traffic between your application and the API is not blocked by firewalls or security settings.

Note: Most users do not need to make any special configurations. Allowlisting is typically only necessary for environments with strict security measures, such as restricted outbound network traffic.

Required Endpoint Domains for Google Sheets

Creating a Custom OAuth Application

• set AuthScheme to OAuth,
• get and set the OAuthAccessToken, and
• set the necessary configuration parameters.

(For information on getting and setting the OAuthAccessToken and other configuration parameters, see the Desktop Authentication section of "Connecting to Google Sheets".)

However, a custom OAuth connection is required for Users who connect via the Web, and for connecting on behalf of users via a Service Account. Custom OAuth applications are also useful if you want to:

• control branding of the authentication dialog;
• control the redirect URI that the application redirects the user to after the user authenticates; or
• customize the permissions that you are requesting from the user.

Procedure

1. Navigate to the Google Cloud Console.
2. At the left navigation pane, select Library. The console opens the Library page.
3. Use the Search service to find Google Sheets API. Select "Google Sheets API" from the search results.
4. On the Google Sheets API page, click ENABLE.

User Accounts

1. Create a new project or select an existing project.
2. At the left navigation pane, select Credentials.
3. If the selected project does not have a consent screen, click CONFIGURE CONSENT SCREEN. If you are not using a Google Workspace account, you are restricted to creating an External-type Consent Screen, which requires specifying a support email and developer contact email. Additional information is optional.
4. On the Credentials page, select Create Credentials > OAuth Client ID.
5. In the Application Type menu, select Web application.
6. Specify a name for your OAuth custom web application.
7. Under Authorized redirect URIs, click ADD URI and enter a redirect URI.
8. Click Enter.
9. Click CREATE.

When the application is complete, the Cloud Console returns you to the Credentials page. A window opens that displays your client Id and client secret.

Although the client secret is accessible from from the Google Cloud Console, we recommend you write down the client secret. You need both the client secret and client Id to specify the OAuthClientId and OAuthClientSecret.

Service Accounts

When using AuthScheme=OAuthJWT, you must create a Service account.

At the Google Cloud Console:

• To complete the service account flow, generate a private key in the Google Cloud Console. In the service account flow, the driver exchanges a JSON Web token (JWT) for the OAuthAccessToken. The private key is required to sign the JWT. The driver grants the same permissions to the Service Account.

• Now create a new Service Account:
  
  1. Create a new project or select an existing project.
  2. At the left navigation pane, select Credentials.
  3. Navigate to Create Credentials > Service account. The Cloud Console displays the Create Service Account page.
  4. Enter the Service account name, the Service account ID, and, optionally, a description.
  5. Click DONE. The Cloud Console returns you to the Credentials page.
  6. In the Service Accounts area, select the service accout you just created.
  7. Click the KEYs tab, then click ADD KEY > Create new key.
  8. Select any supported Key type, such as OAuthJWTCert or OAuthJWTCertType.
  9. Click CREATE.

The key is automatically downloaded to your local device, and any additional information specific to the key is displayed.

This section details a selection of advanced features of the Google Sheets Sync App.

User Defined Views

The Sync App 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 Sync App 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 Sync App for compliance with Firewall and Proxy, including Windows proxies and HTTP proxies. You can also set up tunnel connections.

Query Processing

For further information, see Query Processing.

Logging

Customizing the SSL Configuration

By default, the Sync App 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.

Connecting Through a Firewall or Proxy

HTTP Proxies

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 Sync App 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:

• To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
• To tunnel the connection, set FirewallType to TUNNEL.
• To authenticate, specify FirewallUser and FirewallPassword.
• To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Spreadsheets as Tables

The Sync App models spreadsheets and ranges as relational tables.

Tables

Tables shows various configuration options to reflect your spreadsheets' organization in the tables; for example, you will find guides for working with headers and querying ranges as tables.

Columns provides more information on column discovery.

Stored Procedures

The Sync App enables you to represent a top-left-oriented spreadsheet or a user-specified range as a database table. You can control how tables are listed by setting the Header property.

Top-Left Oriented Tables

• Top-left-oriented tables are represented with the name of the worksheet.
• The default format requires that the table is top-left-oriented and that the first row of data in the worksheet contains the column names. This means that the default value of true for the Header connection string property is required.
• Headers should not contain special characters.
• By default the Sync App will return all rows until the first empty row. Note: an empty row between data will prevent further data from being returned.

Due to a limitation of Google's Spreadsheet API, all column headers must be non empty.

User-Specified Range

Note: Range notation is only available in a SELECT or UPDATE statement. Ranges are not supported for DELETE and INSERT commands.

You can specify column names or generate column names automatically by setting the Header property. This property affects how you use columns in commands.

Header=True (Default)

• Columns are determined by the first row of the Google spreadsheet. If no values are provided for the first row of the spreadsheet, the Sync App will create unique, alphabetized column names that are available only within the scope of that request.
• The Sync App also adds an Id column for each row that corresponds to the unique URI of the row on the Google servers. This is used during update and delete operations.

Header=False

• Columns will be dynamically assigned based on either the specified range or the size of the worksheet. The autogenerated column names are alphabetical.
• The Id column for each row will represent the row number from the top of the sheet. For example, if you specify a range A3:E6, rows 3, 4, 5, and 6 will be returned.

Views are similar to tables in the way that data is represented; however, views are read-only.

Queries can be executed against a view as if it were a normal table.

Google Sheets Connector for CData Sync Views

Query the folders contained in a user's Google Drive.

Select

The Sync App will use the Google Sheets API to process WHERE clause conditions built with the server side supported columns and operators. The rest of the filter is executed client side within the Sync App.

The columns and operators that support server side filtering are:

• Name supports the 'CONTAINS,=,!=' operators.
• Description supports the 'CONTAINS' operator.
• ModifiedTime supports the '<=,<,=,!=,>,>=' operators.
• OwnerEmail supports the 'IN' operator.
• Starred supports the '=,!=' operators.
• Trashed supports the '=,!=' operators.
• ParentIds supports the 'IN' operator.
• DriveId supports the '=' operator. It is used to get all the folders from the specified Drive.

  Note: You must set the connection property SupportsAllDrives to 'true', in order to query from a specific Drive.

All the columns that support server side filtering can be paired with the AND and OR logical operators. For example, the following queries are processed server side:

SELECT * FROM Folders WHERE Name = 'example folder'

SELECT * FROM Folders WHERE OwnerEmail IN ('[email protected]', '[email protected]') AND ModifiedTime >= '2020-04-01T05:30:00'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

Returns a list of a user's sheets and their relevant information.

Columns

Returns a list of a user's spreadsheets and their relevant information.

Columns

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.

Authentication

Connection

OAuth

JWT OAuth

SSL

Firewall

Proxy

Logging

Schema

Miscellaneous

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

The type of authentication to use when connecting to Google Sheets.

Remarks

• Token: Set this to perform Token Based Authentication via the APIKey property.
• OAuth: Set this to perform OAuth authentication using a standard user account.
• OAuthJWT: Set this to perform OAuth authentication using an OAuth service account.
• GCPInstanceAccount: Set this to get Access Token from Google Cloud Platform instance.

If your client application does not use OAuth 2.0, then it must include an API key when it calls an API that's enabled within a Google Cloud Platform project.

Remarks

If your client application does not use OAuth 2.0, then it must include an API key when it calls an API that's enabled within a Google Cloud Platform project.

This section provides a complete list of the Connection properties you can configure in the connection string for this provider.

A comma-separated list of the names or Ids of the spreadsheets to be viewed.

Remarks

A comma-separated list of the names or Ids of the spreadsheets to be viewed. Query the Spreadsheets view to retrieve this data.

Note: In case you are providing the names of the spreadsheets, make sure to provide the exact spreadsheet name, including the leading and/or trailing spaces. Also, you should not add extra spaces before and after the comma separator. If any of the spreadsheet names includes a comma, escape it by using a backslash '\'.

A comma separated list of the folders' names from which to retrieve spreadsheets in the format FolderName='name1,name2'.

Remarks

A comma separated list of the folders' names from which to retrieve spreadsheets in the format FolderName='name1,name2'.

A comma separated list of the folders' ids from which to retrieve spreadsheets in the format FolderId='id1,id2,id3'.

Remarks

A comma separated list of the folders' ids from which to retrieve spreadsheets in the format FolderId='id1,id2,id3'.

Indicates whether or not the trashed files will be listed.

Remarks

If true, the driver will list the files/spreadsheets that have been trashed.

Indicates whether or not the hidden sheets will be listed.

Remarks

If true, the driver will skip the hidden sheets.

Determines whether or not to retrieve Drive items.

Remarks

If you set this property to 'true', you can query from any Drive spreadsheets.

Indicates whether or not to use Ids as Spreadsheet and Sheet name.

Remarks

Indicates whether or not to use Ids as Spreadsheet and Sheet name. To select in a sheet instead of SpreadsheetName_SheetName use: SpreadsheetId_SheetId. Ex: SELECT * FROM 11696gdF5QUL1EnYikYiUeMTHRqA1111KbdYDoINqI_1151117664

A drive's names or ids from which to retrieve spreadsheets in the format TeamDrive='Shared drive 2, Shared drive 3', or TeamDrive='0BKwyFj1j9FOsUk9EVO, 0ANMIP9RIe1LQUk9PVA'.

Remarks

A drive's names or ids from which to retrieve spreadsheets in the format TeamDrive='Shared drive 2, Shared drive 3', or TeamDrive='0BKwyFj1j9FOsUk9EVO, 0ANMIP9RIe1LQUk9PVA'.

Boolean determining if the exposed sheets are limited to only the sheets shared to the user's domain or not.

Remarks

If true, the driver will retrieve and expose only the sheets shared to the user's domain, excluding the sheets owned by the user. If false, the driver will retrieve both, the files owned by and shared to the user.

Used in case FolderId/FolderName properties are defined. If set to True this makes the driver return all the Spreadsheets inside nested folders, else the driver will return only the files directly to that foder. By default this is set to false.

Remarks

Used in case FolderId/FolderName properties are defined. If set to True this makes the driver return all the Spreadsheets inside nested folders, else the driver will return only the files directly to that foder. By default this is set to false.

When enabled, fields where the provider detects error values will be returned as NULL. If disabled, the provider throws an error if an error value is detected in any field.

Remarks

If this property is set to true, the Sync App returns fields containing value errors as NULL.

When this property is set to false, the Sync App throws an error if a value error is discovered.

The Sync App checks for the following error values:

• #NULL!
• #N/A
• #DIV/0!
• #VALUE!
• #REF!
• #NAME?
• #NUM!
• #ERROR!

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

Specifies the client Id that was assigned the custom OAuth application was created. (Also known as the consumer key.) This ID registers the custom application with the OAuth authorization server.

Remarks

OAuthClientId is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

Specifies the client secret that was assigned when the custom OAuth application was created. (Also known as the consumer secret ). This secret registers the custom application with the OAuth authorization server.

Remarks

OAuthClientSecret is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

A space-delimited list of service account emails for delegated requests.

Remarks

The service account emails must be specified in a space-delimited list.

Each service account must be granted the roles/iam.serviceAccountTokenCreator role on its next service account in the chain.

The last service account in the chain must be granted the roles/iam.serviceAccountTokenCreator role on the requesting service account. The requesting service account is the one specified in the RequestingServiceAccount property.

Note that for delegated requests, the requesting service account must have the permission iam.serviceAccounts.getAccessToken, which can also be granted through the serviceAccountTokenCreator role.

A service account email to make a delegated request.

Remarks

The service account email of the account for which the credentials are requested in a delegated request. With the list of delegated service accounts in DelegatedServiceAccounts, this property is used to make a delegated request.

You must have the IAM permission iam.serviceAccounts.getAccessToken on this service account.

This section provides a complete list of the JWT OAuth properties you can configure in the connection string for this provider.

The JWT Certificate store.

Remarks

The name of the certificate store for the client certificate.

The OAuthJWTCertType field specifies the type of the certificate store specified by OAuthJWTCert. If the store is password protected, specify the password in OAuthJWTCertPassword.

OAuthJWTCert is used in conjunction with the OAuthJWTCertSubject field in order to specify client certificates. If OAuthJWTCert has a value, and OAuthJWTCertSubject is set, a search for a certificate is initiated. Please refer to the OAuthJWTCertSubject field for details.

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 (i.e. PKCS12 certificate store).

The type of key store containing the JWT Certificate.

Remarks

This property can take one of the following values:

The password for the OAuth JWT certificate used to access a certificate store that requires a password. If the certificate store does not require a password, leave this property blank.

Remarks

This property specifies the password needed to open the certificate store, but only if the store type requires one. To determine if a password is necessary, refer to the documentation or configuration for your specific certificate store.

This is not required when using the GOOGLEJSON OAuthJWTCertType. Google JSON keys are not encrypted.

The subject of the OAuth JWT certificate used to locate a matching certificate in the store. Supports partial matches and the wildcard '*' to select the first certificate.

Remarks

The value of this property is used to locate a matching certificate in the store. The search process works as follows:

• If an exact match for the subject is found, the corresponding certificate is selected.
• If no exact match is found, the store is searched for certificates whose subjects contain the property value.
• If no match is found, no certificate is selected.

You can set the value to '*' to automatically select the first certificate in the 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, [email protected]. Common fields include:

If a field value contains a comma, enclose it in quotes. For example: "O=ACME, Inc.".

The issuer of the Java Web Token.

Remarks

The issuer of the Java Web Token. Enter the value of the service account email address.

This is not required when using the GOOGLEJSON OAuthJWTCertType. Google JSON keys contain a copy of the issuer account.

The user subject for which the application is requesting delegated access.

Remarks

The user subject for which the application is requesting delegated access. Enter the email address of the user for which the application is requesting delegated access.

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

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

Remarks

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 is rejected.

This property can take the following forms:

If not specified, any certificate trusted by the machine is accepted.

Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.

This section provides a complete list of the Firewall properties you can configure in the connection string for this provider.

Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.

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 Sync App 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.

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

Identifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.

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.

Specifies the TCP port to be used for a proxy-based firewall.

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.

Identifies the user ID of the account authenticating to a proxy-based firewall.

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.

Specifies the password of the user account authenticating to a proxy-based firewall.

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.

This section provides a complete list of the Proxy properties you can configure in the connection string for this provider.

Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.

Remarks

When this connection property is set to True, the Sync App 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. Set to False if you want to manually configure the Sync App to connect to a specific proxy server.

To connect to an HTTP proxy, see ProxyServer. For other proxies, such as SOCKS or tunneling, see FirewallType.

The hostname or IP address of the proxy server that you want to route HTTP traffic through.

Remarks

The Sync App 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, which is the default, the Sync App instead routes HTTP traffic through the proxy server specified in your system proxy settings.

The TCP port on your specified proxy server (set in the ProxyServer connection property) that has been reserved for routing HTTP traffic to and from the client.

Remarks

The Sync App only routes HTTP traffic through the proxy server port specified in this connection property when ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True, which is the default, the Sync App instead routes HTTP traffic through the proxy server port specified in your system proxy settings.

For other proxy types, see FirewallType.

Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.

Remarks

The authentication type can be one of the following:

• BASIC: The Sync App performs HTTP BASIC authentication.
• DIGEST: The Sync App performs HTTP DIGEST authentication.
• NTLM: The Sync App retrieves an NTLM token.
• NEGOTIATE: The Sync App retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.
• NONE: Set this when 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.

The username of a user account registered with the proxy server specified in the ProxyServer connection property.

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:

The Sync App only uses this username if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True, which is the default, the Sync App instead uses the username specified in your system proxy settings.

The password associated with the user specified in the ProxyUser connection property.

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:

For SOCKS 5 authentication or tunneling, see FirewallType.

The Sync App only uses this password if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True, which is the default, the Sync App instead uses the password specified in your system proxy settings.

The SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.

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 :

A semicolon separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Remarks

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

Note that the Sync App 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.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

Specifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.

Remarks

This property lets you customize the log file content by specifying the logging modules to include. Logging modules categorize logged information into distinct areas, such as query execution, metadata, or SSL communication. Each module is represented by a four-character code, with some requiring a trailing space for three-letter names.

For example, EXEC logs query execution, and INFO logs general provider messages. To include multiple modules, separate their names with semicolons as follows: INFO;EXEC;SSL.

The Verbosity connection property takes precedence over the module-based filtering specified by this property. Only log entries that meet the verbosity level and belong to the specified modules are logged. Leave this property blank to include all available modules in the log file.

For a complete list of available modules and detailed guidance on configuring logging, refer to the Advanced Logging section in Logging.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

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.

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\\GoogleSheets Data Provider\\Schema, where %APPDATA% is set to the user's configuration directory:

Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .

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.

Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .

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.

Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

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.

Determines how to determine the data types of columns.

Remarks

Indicates whether or not the first row should be used as a column header.

Remarks

If true, the first row will be used as a column header. Otherwise, the pseudo column names (A, B, C, etc.) will be used.

The Header property is used in conjunction with the Orientation property. When Header is set to false and Orientation is set to Columns, column names are reported as R1, R2, R3, etc.

Set this property to control the name of the primary key.

Remarks

Determines the name of the primary key column which holds the row number. The default value of the primary key is Id.

Set this property if there is a column named ID in the table you are quering, or if you prefer to change the name of the primary key.

Define the tables within the Google Spreadsheet.

Remarks

This property is used to define the ranges within a sheet that will appear as tables. The value is a comma-separated list of name-value pairs in the form [Table Name]=[Spreadsheet Name]_[Sheet Name]![Range] or [Table Name]=[Spreadsheet Name]_[Sheet Name]![Range]. Table Name is the name of the table you want to use for the data and will be used when issuing queries. Sheet Name is the name of the sheet within the Google Spreadsheet and Range is the range of cells that contain the data for the table.

Here is an example DefineTables value: DefineTables="Table1=Spreadsheet1_Sheet1!A1:N25,Table2=Spreadsheet1_Sheet2!C3:M53,Table4=xIsPcLs2-bF3AavQcSLCfzs3kGc_Sheet4!C20:N60".

Indicates whether the data in the sheet is laid out horizontally or vertically.

Remarks

By default, the Sync App models vertically oriented spreadsheet data -- rows arranged vertically below a header row.

Set this to "Horizontal" if the rows are arranged left to right. The first column contains the column names and subsequent columns become rows.

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

If set to true, the driver will automatically expand the dimensions in case the updated/insert/deleted value is outside the range of the sheet.

Remarks

If set to true, the driver will automatically expand the dimensions in case the updated/insert/deleted value is outside the range of the sheet.

Configuration properties to provide when using Workload Identity Federation via AWS.

Remarks

The properties are formatted as a semicolon-separated list of Key=Value properties, where the value is optionally quoted. For example, this setting authenticates in AWS using a user's root keys:

AWSWorkloadIdentityConfig="AuhtScheme=AwsRootKeys;AccessKey='AKIAABCDEF123456';SecretKey=...;Region=us-east-1"

Determines how dates, times, and durations should be represented in the output. This is ignored if the ValueRenderOption is FormattedValue. The default datetime render option is SerialNumber.

Remarks

Determines how existing data is changed when new data is input.

Remarks

INSERT INTO Spreadsheet1_Sheet1(Id,Name, Amount) VALUES (2,'Test', 10)

Specifies the maximum rows returned for queries without aggregation or GROUP BY.

Remarks

This property sets an upper limit on the number of rows the Sync App returns for queries that do not include aggregation or GROUP BY clauses. This limit ensures that queries do not return excessively large result sets by default.

When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting. If MaxRows is set to "-1", no row limit is enforced unless a LIMIT clause is explicitly included in the query.

This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.

Indicates whether to read empty cells as null or as empty.

Remarks

NullValueMode controls how empty Google Sheets cells are modelled. An empty cell is a cell that has not been set and thus contains a null string. If NullValueMode is set to ReadAsNull, NULL is reported for an empty cell; if NullValueMode is set to ReadAsEmpty, an empty string is reported for an empty cell.

Specifies additional hidden properties for specific use cases. These are not required for typical provider functionality. Use a semicolon-separated list to define multiple properties.

Remarks

This property allows advanced users to configure hidden properties for specialized scenarios. These settings are not required for normal use cases but can address unique requirements or provide additional functionality. Multiple properties can be defined in 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.

Specify multiple properties in a semicolon-separated list.

Integration and Formatting

Specifies the maximum number of results to return from Google Sheets, per page. This setting overrides the default page size set by the datasource, which is optimized for most use cases.

Remarks

You may want to adjust the default pagesize to optimize results for a particular object or service endpoint you are querying. Be aware that increasing the page size may improve performance, but it could also result in higher memory consumption per page.

Boolean determining if percentage columns should be considered as decimal.

Remarks

Boolean determining if percentage columns should be considered as decimal.

Specifies the pseudocolumns to expose as table columns. Use the format 'TableName=ColumnName;TableName=ColumnName'. The default is an empty string, which disables this property.

Remarks

This property allows you to define which pseudocolumns the Sync App 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: "*=*"

The maximum number of rows to scan to look for the columns available in a table.

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.

Indicates whether or not the empty rows should be pushed.

Remarks

If true, the empty rows will be pushed at the output.

Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error. The default is 60 seconds. Set to 0 to disable the timeout.

Remarks

This property controls the maximum time, in seconds, that the Sync App waits for an operation to complete before canceling it. If the timeout period expires before the operation finishes, the Sync App cancels the operation and throws an exception.

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.

Setting this property to 0 disables the timeout, allowing 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. Use this property cautiously to avoid long-running operations that could degrade performance or result in unresponsive behavior.

Specifies a filepath to a JSON configuration file defining custom views. The provider automatically detects and uses the views specified in this file.

Remarks

This property allows you to define and manage custom views through a JSON-formatted configuration file called UserDefinedViews.json. These views are automatically recognized by the Sync App 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 Spreadsheet1_Sheet1 WHERE MyColumn = 'value'"
	},
	"MyView2": {
		"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
	}
}

You can define multiple views in a single file and specify the filepath using this property. For example: UserDefinedViews=C:\Path\To\UserDefinedViews.json. When you use this property, only the specified views are seen by the Sync App.

Refer to User Defined Views for more information.

Boolean determining if simple names should be used for tables and columns.

Remarks

Google Sheets tables and columns can use special characters in names that are normally not allowed in standard databases. UseSimpleNames makes the Sync App easier to use with traditional database tools.

Setting UseSimpleNames to true will simplify the names of tables and columns returned. It will enforce a naming scheme such that only alphanumeric characters and the underscore are valid for the displayed table and column names. Any nonalphanumeric characters will be converted to an underscore.

Determines how inserted values should be treated.

Remarks

Determines how values should be rendered in the output.

Remarks

The ID of your Workload Identity Federation pool.

Remarks

The ID of your Workload Identity Federation pool.

The ID of the Google Cloud project that hosts your Workload Identity Federation pool.

Remarks

The ID of the Google Cloud project that hosts your Workload Identity Federation pool.

The ID of your Workload Identity Federation pool provider.

Remarks

The ID of your Workload Identity Federation pool provider.