Connecting to SAP ByDesign

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 SAP ByDesign can be installed and used in Python 3.10 or newer.

SAP ByDesign Version Support

The connector leverages the SAPByDesign APIs to enable bidirectional access to SAPByDesign.

See Also

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

Dependencies

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

Installation

The CData Python Connector for SAP ByDesign 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_sapbydesign_connector-26.0.9655-cp310-abi3-win_amd64.whl

Linux:

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

macOS:

pip install cdata_sapbydesign_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_sapbydesign_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_sapbydesign" 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_sapbydesign folder is trivial to find:

import os
import cdata.sapbydesign
path = os.path.abspath(cdata.sapbydesign.__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-sapbydesign-connector

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

1. Import the module as follows:
   

   import cdata.sapbydesign 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("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

This section documents how to provide authentication for your account and service type and then connect.

Authenticate a SAPByDesign Account

Set the following connection properties to connect to SAP ByDesign.

Connect to a Analytical Service

• URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
• ServiceType: If you want to retrieve the reports of a analytical service, specify ServiceType=AnalyticsService;.
• ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

  If you're not sure what service to specify, you can always query the sys_schemas to list available services.

• User: Set this to the username of your account.
• Password: Set this to the password of your account.

Analytical Service Connection String Example:

Url=https://test.sapbydesign.com;ServiceType=AnalyticsService;ServiceName=cc_home_analytics.svc;User=Test;Password=test;

Connect to a Custom Service

• URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
• ServiceType: If you have a custom service you want to retrieve data from, specify ServiceType=CustomService;.
• ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

  If you're not sure what service to specify, you can always query the sys_schemas to list available services.

• User: Set this to the username of your account.
• Password: Set this to the password of your account.

Custom Service Connection String Example:

Url=https://test.sapbydesign.com;ServiceType=CustomService;ServiceName=khsalesorder;User=Test;Password=test;

Connect to the ODataDataSource API

• URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
• ServiceType: If you want to query OData Data Source API( odata/analytics/ds) , specify ServiceType=ODataDataSource.
• ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

  If you're not sure what service to specify, you can always query the sys_schemas to list available services.

• User: Set this to the username of your account.
• Password: Set this to the password of your account.

ODataDataSource Connection String Example:

Url=https://test.sapbydesign.com;ServiceType=ODataDataSource;ServiceName=Customer.svc;User=Test;Password=test;

Authenticate with Azure AD (SSO)

If your organization uses Microsoft Entra ID (formerly Azure Active Directory) to manage user identities, you can authenticate to SAP ByDesign using Single Sign-On (SSO). This method allows users to connect without directly supplying a username or password.

To use Azure AD authentication, set the following connection properties:

• URL: Set this to the URl of your SAP ByDesign site.
• ServiceType: Specify the type of service: AnalyticsService, CustomService, or ODataDataSource.
• ServiceName: Set this to the name of the service to connect to.
• AuthScheme: Set this to AzureAD.
• InitiateOAuth: Set this to GETANDREFRESH to allow automatic token acquisition and refresh.
• OAuthClientId: Set this to the OAuth client ID of your SAP ByDesign application. This is separate from your Entra ID app registration.
• SSOProperties: A semicolon-delimited string containing Azure AD configuration details. See below for supported keys.

Azure AD Connection String Example:

URL=https://my999999.businessbydesign.cloud.sap;
ServiceType=AnalyticsService;
ServiceName=cc_home_analytics.svc;
AuthScheme=AzureAD;
InitiateOAuth=GETANDREFRESH;
OAuthClientId=SAP_APP_CLIENT_ID;
SSOProperties='AzureTenant=TENANT_ID;OAuthClientId=AZURE_AD_APP_CLIENT_ID;OAuthClientSecret=AZURE_AD_CLIENT_SECRET;CallbackURL=http://localhost:33333'

Supported SSOProperties keys:

The SSOProperties connection property contains a semicolon-delimited list of key-value pairs required for OAuth-based authentication with Microsoft Entra ID (Azure AD). These keys correspond to fields used in the OAuth 2.0 authorization code flow, which Entra ID implements for SSO. The connector uses these values to construct the necessary requests to Microsoft's identity platform.

• AzureTenant: The Entra ID (Azure AD) tenant ID, which can be a GUID or verified domain.
• OAuthClientId: The client ID of your Entra ID app registration. This is not the same as the SAP app client ID.
• OAuthClientSecret: The client secret of your Entra ID app.
• CallbackURL: (optional) The redirect URI registered in Entra ID. The default is http://localhost:33333.
• Scope: (optional) The OAuth scopes to request during authentication.

Note: There are two OAuthClientId values:

• The top-level OAuthClientId refers to the app registered in SAP ByDesign.
• The OAuthClientId inside SSOProperties refers to the app registered in Microsoft Entra ID.

For details on registering a Microsoft Entra ID application, see Creating an Entra ID (Azure AD) Application

Add a new custom ODATA service

• In the SAP ByDesign work center view, click on "Application and User Management".
• Select "OData Services".
• In the dropdown list, select "Custom OData Services".
• Now you should see a list of your current custom services. To add a new one click on "New".

SAP ByDesign URL Restrictions

The SAP ByDesign connector enforces URL restrictions to avoid exceeding the maximum of allowed URI length, which causes the service to throw "URI Too Long" error"

By default, the length of the columns in the projection is limited to 1000 characters. If the columns selected in the projection surpass this limit, the driver drops the projection specification and retrieves all fields. This may impact performance because of service response delay and increased payload.

In the case of the analytical service (ServiceType=AnalyticsService), the driver throws an error indicating you must reduce the number of columns in the projection. In addition, the server-side filter length is restricted to 1000 characters for the same reasons. If the generated filter length surpasses this limit, the driver drops the additional filters and handles them client-side.

In SAP ByDesign, you can configure or disable these limitations by using the MaxSelectLength and MaxFilterLength hidden connection properties. These properties both default to 1000 characters. If your service does not have these restrictions, set the properties to -1 to disable the length limitations.

SAP IAS

SAP IAS (SAP Identity Authentication Service) is SAP's cloud-based identity provider that enables secure user authentication across SAP and third-party applications. It is a user-based authentication mechanism and requires you to set AuthScheme to SAPIAS or to SAPIASPassword.

To enable SAP IAS authentication, you must first register and configure a custom SAP IAS application as described in SAP IAS SAML App Configuration guide.

Desktop Applications

You can authenticate from a desktop application using a custom IAS application registered in SAP Identity Authentication Service (IAS).

To authenticate via SAP IAS, set the following connection properties:

• AuthScheme: SAPIAS.
• InitiateOAuth: GETANDREFRESH.
• OAuthClientId: The API Key of your SAP ByDesign OAuth2 client application.
• SAPIASBaseURL: The base URL of the SAP Identity Authentication Service (IAS) tenant.
• SSOProperties: A semicolon separated list of key-value pairs containing:
  • OAuthClientId: The client Id assigned to your custom SAP IAS application.
  • OAuthClientSecret: The client secret assigned to your custom SAP IAS application.
  (e.g. OAuthClientId=793cf9b4;OAuthClientSecret=K77FErG5S8B;)
• CallbackURL: The redirect URI you defined when you registered your custom IAS application.

When you connect, the connector opens the SAP IAS OAuth authorization endpoint in your default browser. Log in and authorize the application.

The connector completes the OAuth flow by obtaining an SAML assertion from SAP IAS and exchanging it for an SAP ByDesign access token. This token is then used to authenticate API requests to SAP ByDesign. The OAuth credentials are saved to the location specified by the OAuthSettingsLocation. property and persist across connections.

When the access token expires, the connector automatically refreshes it using the refresh token provided by SAP IAS.

Web Applications

To authenticate via SAP Identity Authentication Service (IAS) using a Web application, you must register a custom OpenId client in SAP IAS. You can then use the connector to obtain and manage OAuth tokens used to access SAP ByDesign.

Get a SAP IAS OAuth Access Token

First, set these connection properties to obtain the OAuthAccessToken:

• AuthScheme: SAPIAS.
• OAuthClientId: The API Key of your SAP ByDesign OAuth2 client application.
• SAPIASBaseURL: The base URL of the SAP Identity Authentication Service (IAS) tenant.
• SSOProperties: A semicolon separated list of key-value pairs containing:
  • OAuthClientId: The client Id assigned to your custom SAP IAS application.
  • OAuthClientSecret: The client secret assigned to your custom SAP IAS application.
  (e.g. OAuthClientId=793cf9b4;OAuthClientSecret=K77FErG5S8B;)

To complete the OAuth exchange:

1. Call the GetOAuthAuthorizationUrl stored procedure and set the CallbackUrl input parameter to the redirect URI you configured when registering your custom IAS application.
2. Open the generated authorization URL in a browser, log in, and authorize the application. You will be redirected to the specified callback URL, which includes a code parameter in the query string.
3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL. If necessary, set the Permissions parameter to request custom permissions.

Once the access and refresh tokens are obtained, the connector can use them to authenticate with SAP ByDesign and refresh tokens automatically as needed.

Automatic Refresh of the SAP IAS OAuth Access Token

To enable automatic token refresh, set the following properties on the initial connection:

• AuthScheme: SAPIAS.
• InitiateOAuth: REFRESH.
• OAuthClientId: The API Key of your SAP ByDesign OAuth2 client application.
• SAPIASBaseURL: The base URL of the SAP Identity Authentication Service (IAS) tenant.
• SSOProperties: A semicolon separated list of key-value pairs containing:
  • OAuthClientId: The client Id assigned to your custom SAP IAS application.
  • OAuthClientSecret: The client secret assigned to your custom SAP IAS application.
  (e.g. OAuthClientId=793cf9b4;OAuthClientSecret=K77FErG5S8B;)
• OAuthAccessToken: The access token returned by GetOAuthAccessToken.
• OAuthRefreshToken: The refresh token returned by GetOAuthAccessToken.
• OAuthSettingsLocation: The location where the connector saves the OAuth token values, which persist across connections.

On subsequent data connections, the values for OAuthAccessToken and OAuthRefreshToken are taken from OAuthSettingsLocation, and do not need to be set on the connection.

Headless Machines

To configure the connector with a user account on a headless machine, you must first complete authentication on a separate device that has a web browser.

Install the connector on a machine with browser access and perform the standard browser-based authentication flow, as described in the Desktop Applications section above. After successfully authenticating, the connector will store the resulting OAuth values in the file specified by the OAuthSettingsLocation property. By default, this file is named OAuthSettings.txt.

Once you’ve verified that the connection works, copy the OAuthSettings.txt file to your headless machine.

On the headless machine, configure the following connection properties:

• AuthScheme: SAPIAS.
• InitiateOAuth: REFRESH.
• OAuthClientId: The API Key of your SAP ByDesign OAuth2 client application.
• SAPIASBaseURL: The base URL of the SAP Identity Authentication Service (IAS) tenant.
• OAuthSettingsLocation: The location of your OAuth settings file. Make sure this location gives read and write permissions to the connector to enable the automatic refreshing of the access token.
• SSOProperties: A semicolon separated list of key-value pairs containing:
  • OAuthClientId: The client Id assigned to your custom SAP IAS application.
  • OAuthClientSecret: The client secret assigned to your custom SAP IAS application.
  (e.g. OAuthClientId=793cf9b4;OAuthClientSecret=K77FErG5S8B;)

Alternative: Password Grant Flow (No Browser Prompt)

As an alternative to the interactive Code Grant flow, you can use the OAuth Password Grant flow, which allows the application to authenticate without prompting the user in a browser. This flow is ideal for headless, background, or automated server-side applications.

To use the Password Grant flow, set the following connection properties:

• AuthScheme: SAPIASPassword.
• OAuthClientId: The API Key of your SAP ByDesign OAuth2 client application.
• SAPIASBaseURL: The base URL of the SAP Identity Authentication Service (IAS) tenant.
• SSOProperties: A semicolon separated list of key-value pairs containing:
  • OAuthClientId: The client Id assigned to your custom SAP IAS application.
  • OAuthClientSecret: The client secret assigned to your custom SAP IAS application.
  (e.g. OAuthClientId=793cf9b4;OAuthClientSecret=K77FErG5S8B;)
• User: The IAS username to authenticate with.
• Password: The corresponding password for the specified user.

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 SAP ByDesign 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:
  

  [sapbydesign.cpython-311-x86_64-linux-gnu.so]

• For Mac:
  

  [sapbydesign.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.sapbydesign 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

Creating an Entra ID (Azure AD) Application

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

SAP ByDesign supports OAuth-based authentication using Microsoft Entra ID. If you will connect via a web application and want to authenticate via Entra ID, you must first register a custom OAuth application in the Entra Admin Center, as described below.

If you will connect via a desktop application or headless machine, you can authenticate using SAP ByDesign's built-in embedded application credentials, which use CData branding. However, custom OAuth applications are also compatible with desktop and headless authentication flows, and may be preferable for production deployments or environments requiring strict policy control.

Registering the Application

To register an OAuth application in Microsoft Entra ID, follow these steps:

1. Go to https://portal.azure.com.
2. In the left-hand navigation pane, select Microsoft Entra ID > App registrations.
3. Click New registration.
4. Enter a name for the application.
5. Specify the types of accounts this application should support:
   • For private-use applications, select Accounts in this organization directory only.
   • For distributed applications, select one of the multi-tenant options.

   Note: If you select Accounts in this organizational directory only, when you connect with CData Python Connector for SAP ByDesign, you must set AzureTenant to the tenant's ID (either GUID or verified domain). Otherwise, authentication will fail.

6. Set Select a platform to Web, and set the redirect URI to http://localhost:33333 (default), or use another URI appropriate for your deployment. When using a custom redirect URI set a CallbackURL connection property; in those cases, set it to match this URI exactly.
7. Click Register. The application management screen opens. Record these values for later use:
   • Application (client) ID is used for OAuthClientId
   • Directory (tenant) ID is used for AzureTenant
8. Go to Certificates & Secrets. Click New Client Secret, set the desired expiration, and save the generated value. This value will only be shown once — record it to use with OAuthClientSecret.

9. To confirm, click Add permissions.

Navigation Properties As Views

Navigation properties are properties on an entity that is itself either a single related entity or list of related entities.
By default, these are exposed as views, although they may be hidden by setting NavigationPropertiesAsViews to false.
This property will only have an effect when working with ServiceType=CustomService as there are no navigation properties when dealing with other services.

SAP IAS SAML App Configuration

SAP ByDesign supports the OAuth 2.0 SAML flow, which requires a signed SAML assertion issued by an external Identity Provider (IdP). This assertion is then exchanged for an access token when making requests to the SAP ByDesign API.

This guide outlines how to configure a SAML application in SAP Identity Authentication Service (IAS) to generate the required SAML assertion, which can then be exchanged for an SAP ByDesign access token as part of the authentication flow.

1. Retrieve the SAP IAS Signing Certificate.
   • In SAP IAS Admin page, navigate to: Applications & Resources > Tenant Settings > SAML 2.0 Configuration.
   • Under Signing Certificates, click the lens icon to view the active certificate.
   • Copy the entire certificate content under the Certificate Information section, this will be used to validate the SAML assertion signature.
2. Create an OAuth2 Client App in SAP ByDesign.
   • Navigate to Admin Center > Manage OAuth2 Client Applications.
   • Create a new application using the Register Client Application button.
   • Fill in the Application Name and the Application URL fields to your preferred values.
   • Paste the signing certificate content under the *X.509 Certificate field.
   • After saving, copy the generated API Key, this will be used as the OAuthClientId in your connection configuration.
3. Create a SAML Application in SAP IAS (if not already created).
   • In SAP IAS Admin Console, go to: Applications & Resources > Applications > Create.
   • Enter the below properties:
     • Display Name: (custom name)
     • Protocol: SAML 2.0
     • Home URL: Leave empty
     • Parent App: Leave as None
   • Click Create.
4. SAML 2.0 Configuration (skip this step if already done on existing app).
   • In SAP IAS Admin page, open the already existing or created SAML application used for SSO.
   • Go to Trust > Single Sign-On > SAML 2.0 Configuration.
   • Set the URL for Principal Propagation to <SAP ByDesign base url>/oauth/token (e.g. https://apisalesdemo2.successfactors.eu/oauth/token).
   • Under Subject Name Identifier, choose a value that matches the username of the API user in both SAP IAS and SAP ByDesign.
   • Under Default Name ID Format, select the Unspecified (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) option.
   • Under Assertion Attributes, add a new attribute with the name api_key, and set the value to the API Key of the SAP ByDesign IAS app.
5. Enable Token Exchange Grant Flow.
   • Temporarily switch the application protocol to OpenID Connect, by clicking on the Edit button at the top right corner of the application screen and selecting the SAML 2.0 protocol type.
   • Go to Trust > Single Sign-On > OpenID Connect Configuration.
   • Enable your preferred Grant Types. The connector supports the grants below. The recommended are:
     • Authorization Code (with or without PKCE) or Password
     • Token Exchange (RFC 8693): Required to get the SAML assertion.
     • Refresh: Optional, but recommended if you want the connector to automatically refresh the access token.
   • Save and change the app back to the SAML2.0 protocol. Otherwise the SAML Token Exchange flow will not work with this app.
6. Configure Client Authentication.
   • Go to Applications > Application APIs > Client Authentication.
   • Create a client secret by clicking on the Add button on the Secrets section.
   • Copy the Client ID and Client Secret — these will be passed in the connector's SSOProperties:
     • OAuthClientId: The client Id of your SAP IAS OpenId application.
     • OAuthClientSecret: The client Secret you added to your SAP IAS OpenId application.

After completing the configuration steps above, you are ready to set the required connection properties and establish a connection using the connector.

General Changes

Date	Version	Source	Category	Type	Description
2026-05-27	26.0.9643	General	Connection	Removed	Removed the deprecated ReplaceInvalidTypesWithNull connection property. Use the ReplaceInvalidValuesWithNull property instead.
2026-05-22	26.0.9638	Python		Removed	Remove support for Intel x64 architecture on macOS
2026-05-07	26.0.9623	General	Data Model	Added	Added the ColumnCapabilities column to the sys_tablecolumns system table. This column is a bit mask denoting the column's write capabilities.
2026-05-07	26.0.9623	Python		Changed	Updated embedded JRE to jre-17.0.19+10 (Linux x64 / MacOs x64).
2026-04-15	26.0.9601	General	Query Exec	Changed	String comparisons using GREATER, LESS, and CONTAINS operators are now case-insensitive by default.
2026-04-01	26.0.9587	SAP ByDesign	Data Model	Changed	When IncludeLinkedColumns is enabled, additional "Linked" columns are exposed. Previously, these were described as foreign key references, but they represent entire related rows. These columns no longer return reference values.
2026-01-13	25.0.9509	General		Added	Added support for the REGEXP_REPLACE() string function.
2026-01-12	25.0.9508	SAP ByDesign		Added	Added the **SAPIAS** (SAP Identity Authentication Service using the OAuth code grant flow) and **SAPIASPassword** (SAP Identity Authentication Service using the OAuth password grant flow) options to the AuthScheme connection property.
2025-12-21	25.0.9486	Python		Added	Added support for custom loggers in Python connectors on Linux and macOS.
2025-12-05	25.0.9470	General		Added	Added support for the INSERT INTO SELECT statement, with driver-side execution for providers that do not support the operation natively.
2025-10-30	25.0.9434	Python		Changed	Updated embedded JRE to jre-17.0.17+10 (Linux x64 / MacOs x64).
2025-10-06	25.0.9410	General		Added	Support for parsing datetime formats using ".S" and ",S" for milliseconds and nanoseconds.
2025-09-12	25.0.9386	General		Added	Added the IsInsertable, IsUpdateable, and IsDeleteable columns to the sys_tables table.
2025-09-10	25.0.9384	General		Changed	All columns in statically defined Views are now reported as read-only.
2025-09-03	25.0.9377	General		Changed	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-01	25.0.9375	General		Added	Added support for using the CAST function with infinity values. This function can cast "inf" and "-inf" to DOUBLE, FLOAT, or REAL.
2025-08-21	25.0.9364	General		Changed	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-13	25.0.9356	General		Changed	Changed the maximum number of pages held in memory from 15 to 5 for the page providers to decrease heap usage.
2025-07-18	25.0.9330	SAP ByDesign		Removed	Removed the OAuthGrantType property. The grant type is now set implicitly through the 'AuthScheme' property. For example, you can use the 'OAuthPassword' AuthScheme instead of AuthScheme=OAuth with OAuthGrantType=Password.
2025-07-07	25.0.9319	Python		Removed	Removed the 32-bit version of Windows Python.
2025-07-04	25.0.9316	SAP ByDesign		Removed	Removed the UseIdURL connection property because it has been deprecated.
2025-07-02	25.0.9314	Python		Removed	Removed support for Python 3.9.
2025-06-25	25.0.9307	General		Removed	Removed the "ADLS Gen 1" value from the ConnectionType property.
2025-06-25	25.0.9307	Python		Added	Added support for Python 3.13 in Windows, Linux, and Mac editions.
2025-06-25	25.0.9307	Python		Removed	Removed support for Python 3.8 as it is no longer supported.
2025-06-20	25.0.9302	General		Added	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-18	25.0.9300	General		Changed	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-27	25.0.9278	General		Removed	Removed the "Proprietary" enum option from ProxyAuthscheme.
2025-05-12	25.0.9263	Python		Changed	Updated embedded JRE to jre-17.0.15+6 (Linux x64 / MacOS x64) and jre-17.0.15+6 (MacOS aarch64).
2025-03-27	25.0.9217	SAP ByDesign		Added	In tables/views whose corresponding OData entity is marked with hasStream:true in its API metadata responses, the "MediaReadLink" column is added to the table/view metadata. When present, this column displays the link to the OData entity's media stream.
2025-02-15	24.0.9177	General		Added	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-12-12	24.0.9112	SAP ByDesign		Added	Added the MaxReportDimension connection property. This property sets the default number of dimensions that are requested by the driver when executing SELECT * queries.
2024-11-27	24.0.9097	General		Added	Added ThreadId to LogModule output. Logfile lines now include the Thread ID associated with the action being performed.
2024-11-27	24.0.9097	SAP ByDesign		Changed	Changed the default ServiceType to AnalyticsService.
2024-11-27	24.0.9097	SAP ByDesign		Removed	Removed the None option because it is not a valid service type.
2024-09-17	24.0.9026	SAP ByDesign		Added	One column (ColumnType) is added to the sys_tablecolumns table. The column indicates whether the field is a standard column (SYSTEM), a navigation property (LINKEDCOLUMN), a navigation key (NAVIGATIONKEY), a reference column (REFERENCECOLUMN), or a navigation parent key (NAVIGATIONPARENTCOLUMN).
2024-09-10	24.0.9019	SAP ByDesign		Added	Added the AuthScheme connection property to support Single Sign-On (SSO) with Azure Active Directory.
2024-06-05	24.0.8922	Python		Added	Added support for Python 3.12.
2024-05-27	24.0.8913	SAP ByDesign		Added	The MaxSelectLength and ExpandAsterisk connection properties have been exposed for all platforms.
2024-05-09	24.0.8895	General		Changed	The ROUND function previously did not accept negative precision values. That feature has now been restored.
2024-03-15	23.0.8840	General		Added	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-29	23.0.8733	General		Changed	The ROUND function doesn't accept the negative precision values anymore.
2023-11-29	23.0.8733	General		Changed	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-28	23.0.8732	General		Added	Added the HMACSHA256 formatter to allow for secrets to be decoded if it is in base64 format
2023-08-29	23.0.8641	Python		Added	Added support for SQLAlchemy 2.0.
2023-06-20	23.0.8571	General		Added	Added the new sys_lastresultinfo system table.
2023-05-19	23.0.8539	Python		Added	Added support for Python 3.11 on Windows, Linux and Mac.
2023-05-16	23.0.8536	Python		Removed	Removed support for Python 3.7 on Windows and Linux
2023-04-25	23.0.8515	General		Removed	Removed support for the SELECT INTO CSV statement. The core code doesn't support it anymore.
2022-12-14	22.0.8383	General		Changed	Added the Default column to the sys_procedureparameters table.
2022-11-15	22.0.8354	Python		Changed	Updated embedded JRE to jre8u345-b01(Linux x64 / MacOS x64) and jre-17.0.5+8(MacOS aarch64).
2022-11-14	22.0.8353	SAP ByDesign		Added	Added support for OLAPType column in sys_tablecolumns table. It indicates whether a field is a dimension or a measure.
2022-09-30	22.0.8308	General		Changed	Added the IsPath column to the sys_procedureparameters table.
2022-05-18	22.0.8173	Python		Added	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-18	22.0.8173	Python		Removed	Removed support for Python 3.6 on Windows and Linux
2022-04-29	22.0.8154	SAP ByDesign		Added	In 2022, each SapByDesign service is represented as a separate schema. This allows users to query multiple schemas in a single connection. Added support for the ServiceName and ServiceType connection properties.
2022-04-29	22.0.8154	SAP ByDesign		Removed	The AnalyticsService & CustomService connection properties are removed. Instead, ServiceType should be used to specify the type of service to connect with. The Services view has been removed. Instead, to query the services/schemas, use sys_schemas.
2021-09-02	21.0.7915	General		Added	Added support for the STRING_SPLIT table-valued function in the CROSS APPLY clause.
2021-08-07	21.0.7889	General		Changed	Added the KeySeq column to the sys_foreignkeys table.
2021-08-06	21.0.7888	General		Changed	Added the new sys_primarykeys system table.
2021-04-25	21.0.7785	General		Added	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-23	21.0.7783	General		Changed	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-16	21.0.7776	General		Added	Non-conditional updates between two columns is now available to all drivers. For example: UPDATE Table SET Col1=Col2
2021-04-16	21.0.7776	General		Changed	Reduced the length to 255 for varchar primary key and foreign key columns.
2021-04-16	21.0.7776	General		Changed	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-16	21.0.7776	General		Changed	Updated index naming convention to avoid duplicates.

This section provides a walk-through for writing SAP ByDesign 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 SAP ByDesign, see Package Installation and Establishing a Connection.

For information on how to connect with the sapbydesign.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 SAP ByDesign with INSERT, UPDATE, and DELETE statements, see Modifying Data .

Connecting with the cdata.sapbydesign 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.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

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

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 Id, Name FROM Account")
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 Id, Name FROM Account WHERE Industry = ?"
params = ["Floppy Disks"]
cur = conn.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

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 Account (Id, Name) 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 Account SET Name = ? 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 Account WHERE Id = ?"
params = ["1"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

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:

• From SQLAlchemy
• From Pandas
• From Matplotlib
• From Petl

Complete List of SAP ByDesign Integration Quickstarts

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

The CData Python Connector for SAP ByDesign 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 SAP ByDesign 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.

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("sapbydesign:///?URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

Format 2

from sqlalchemy import create_engine
engine = create_engine("sapbydesign://User:Password@/?ServiceType=servicetype;ServiceName=servicename;URL=https://my999999.businessbydesign.cloud.sap;")

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

from sqlalchemy import create_engine
engine = create_engine("sapbydesign_2:///?URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

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 Account(Base):
	__tablename__ = "Account"
	Id = Column(String, primary_key=True)
	Id = Column(String)
	Name = 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)
Account = abase.classes.Account

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)
Account_table = Table("Account", meta)
insp.reflect_table(Account_table, ["Id","Name"])

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("sapbydesign:///?URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
factory = sessionmaker(bind=engine)
session = factory()
for instance in session.query(Account).filter_by(Industry="Floppy Disks"):
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	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:

Account_table = Account.metadata.tables["Account"]
for instance in session.execute(Account_table.select().where(Account_table.c.Industry == "Floppy Disks")):
	print("Id: ", instance.Id)
	print("FullName: ", instance.Name)
	print("City: ", instance.BillingCity)
	print("---------")

Implicit Joining

If mapped classes of related SAP ByDesign 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:

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(Account).order_by(Account.AnnualRevenue)
for instance in rs:
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	print("---------")

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

rs = session.execute(Account_table.select().order_by(Account_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(Account.Id).label("CustomCount"), Account.Id).group_by(Account.Id)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Id: ", instance.Id)
	print("---------")

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

rs = session.execute(Account_table.select().with_only_columns([func.count(Account_table.c.Id).label("CustomCount"), Account_table.c.Id]).group_by(Account_table.c.Id))
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(Account).limit(25).offset(100)
for instance in rs:
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("Name: ", instance.Name)
	print("---------")

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

rs = session.execute(Account_table.select().limit(25).offset(100))
for instance in rs:

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(Account.Id).label("CustomCount"), Account.Id).group_by(Account.Id)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Id: ", instance.Id)
	print("---------")

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

rs = session.execute(Account_table.select().with_only_columns([func.count(Account_table.c.Id).label("CustomCount"), Account_table.c.Id])group_by(Account_table.c.Id))
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(Account.AnnualRevenue).label("CustomSum"), Account.Id).group_by(Account.Id)
for instance in rs:
	print("Sum: ", instance.CustomSum)
	print("Id: ", instance.Id)
	print("---------")

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

rs = session.execute(Account_table.select().with_only_columns([func.sum(Account_table.c.AnnualRevenue).label("CustomSum"), Account_table.c.Id]).group_by(Account_table.c.Id))
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(Account.AnnualRevenue).label("CustomAvg"), Account.Id).group_by(Account.Id)
for instance in rs:
	print("Avg: ", instance.CustomAvg)
	print("Id: ", instance.Id)
	print("---------")

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

rs = session.execute(Account_table.select().with_only_columns([func.avg(Account_table.c.AnnualRevenue).label("CustomAvg"), Account_table.c.Id]).group_by(Account_table.c.Id))
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(Account.AnnualRevenue).label("CustomMax"), func.min(Account.AnnualRevenue).label("CustomMin"), Account.Id).group_by(Account.Id)
for instance in rs:
	print("Max: ", instance.CustomMax)
	print("Min: ", instance.CustomMin)
	print("Id: ", instance.Id)
	print("---------")

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

rs = session.execute(Account_table.select().with_only_columns([func.max(Account_table.c.AnnualRevenue).label("CustomMax"), func.min(Account_table.c.AnnualRevenue).label("CustomMin"), Account_table.c.Id]).group_by(Account_table.c.Id))
for instance in rs:

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:

Account_table = Account.metadata.tables["Account"]

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(Account_table.insert(), {"Id": "Jon Doe", "Name": "John"})

Update

The following example modifies an existing record in the table:

session.execute(Account_table.update().where(Account_table.c.Id == "1").values(Id="Jon Doe", Name="John"))

Delete

The following example removes an existing record from the table:

session.execute(Account_table.delete().where(Account_table.c.Id == "1"))

When combined with the connector, Pandas can be used to generate data frames that contain your SAP ByDesign 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("sapbydesign:///?URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

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
	   Id,
	   Name,
     $exNumericCol;
	FROM Account;""", 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({"Id": ["Jon Doe"], "Name": ["John"]})
df.to_sql("Account", con=engine, if_exists="append", index=False)

Matplotlib contains a number of tools that can graphically model SAP ByDesign 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 SAP ByDesign data. For example, the following plot generates and displays a bar graph relating Id and AnnualRevenue values:

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

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 SAP ByDesign, you can use the connector's connect function to create a connection using a valid SAP ByDesign connection string. If you prefer not to use a direct connection, you can use a SQLAlchemy engine.

import petl as etl
import cdata.sapbydesign as mod
cnxn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")

Extract, Transform, and Load the SAP ByDesign Data

Create a SQL query string and store the query results in a DataFrame.

sql = "SELECT	Id, Name FROM Account "
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 SAP ByDesign tables using Petl's appenddb function.

table1 = [['Id','Name'],['Jon Doe','John']]
etl.appenddb(table1,cnxn,'Account')

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:

• Tables and Views
• Columns
• Procedures

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.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tables"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Views

import cdata.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_views"
cur.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

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.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tablecolumns WHERE TableName = 'Account'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Procedures

A system table called "sys_procedures" is queried to obtain the available stored procedures that are executed:

import cdata.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
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.sapbydesign as mod
conn = mod.connect("URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'SelectEntries'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

This section details a selection of advanced features of the SAP ByDesign 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 SAP ByDesign 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.

The CData Python Connector for SAP ByDesign 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 Account 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.

Customizing the SSL Configuration

To enable TLS, set the following:

• URL: Prefix the connection string with https://

With this configuration, 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.

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:

• 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.

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.

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.

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.

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 Account Table

The following example caches the Account table in the file specified by the CacheLocation property of the connection string.

SELECT Id, Name FROM Account WHERE Industry = 'Floppy Disks'

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.

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 Account WHERE Industry = 'Floppy Disks'

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 Account WHERE Industry = 'Floppy Disks'
  

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 Account#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 Account WHERE Industry='Floppy Disks' ORDER BY Name 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.

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

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 SAP ByDesign 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 SAP ByDesign Query Evaluation component examines SQL queries and returns information indicating what parts of the query the connector is not capable of executing natively.

The SAP ByDesign 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.

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:

1	Setting Verbosity to 1 logs the query, the number of rows returned by it, the start of execution and the time taken, and any errors.
2	Setting Verbosity to 2 logs everything included in Verbosity 1, cache queries, and additional information about the request.
3	Setting Verbosity to 3 also logs HTTP headers, as well as the body of the request and the response.
4	Setting Verbosity to 4 also logs transport-level communication with the data source. This includes SSL negotiation.
5	Setting 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.	—

Exception Handling

Exceptions can be surfaced from either the API or the CData Python Connector for SAP ByDesign. 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.

The CData Python Connector for SAP ByDesign 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 SAP ByDesign API.

INSERT Statements

See INSERT Statements for a syntax reference and examples, as well as retrieving the new records' Ids.

UPDATE Statements

The primary key Id is required to update a record. See UPDATE 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.

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').

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 Account

2. Rename a column:
   

   SELECT [Name] AS MY_Name FROM Account

3. Cast a column's data as a different data type:
   

   SELECT CAST(AnnualRevenue AS VARCHAR) AS Str_AnnualRevenue FROM Account

4. Search data:
   

   SELECT * FROM Account WHERE Industry = 'Floppy Disks'

5. Return the number of items matching the query criteria:
   

   SELECT COUNT(*) AS MyCount FROM Account 

6. Return the number of unique items matching the query criteria:
   

   SELECT COUNT(DISTINCT Name) FROM Account 

7. Return the unique items matching the query criteria:
   

   SELECT DISTINCT Name FROM Account 

8. Sort a result set in ascending order:
   

   SELECT Id, Name FROM Account  ORDER BY Name ASC

9. Restrict a result set to the specified number of rows:
   

   SELECT Id, Name FROM Account 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 Account WHERE Industry = @param

See Explicitly Caching Data for information on using the SELECT statement in offline mode.

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.

Window Functions

See Window Functions for SELECT examples containing window functions.

Table-Valued Functions

See Table-Valued Functions for SELECT examples with table-valued functions.

COUNT

Returns the number of rows matching the query criteria.

SELECT COUNT(*) FROM Account WHERE Industry = 'Floppy Disks'

COUNT(DISTINCT)

Returns the number of distinct, non-null field values matching the query criteria.

SELECT COUNT(DISTINCT Id) AS DistinctValues FROM Account WHERE Industry = 'Floppy Disks'

AVG

Returns the average of the column values.

SELECT Name, AVG(AnnualRevenue) FROM Account WHERE Industry = 'Floppy Disks'  GROUP BY Name

MIN

Returns the minimum column value.

SELECT MIN(AnnualRevenue), Name FROM Account WHERE Industry = 'Floppy Disks' GROUP BY Name

MAX

Returns the maximum column value.

SELECT Name, MAX(AnnualRevenue) FROM Account WHERE Industry = 'Floppy Disks' GROUP BY Name

SUM

Returns the total sum of the column values.

SELECT SUM(AnnualRevenue) FROM Account WHERE Industry = 'Floppy Disks'

The CData Python Connector for SAP ByDesign 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

Window functions allow you to create computed fields from a group of rows (a window) that return a result for each row, as opposed to one computed result for a set of rows, as is the case with aggregate functions. The connector supports the following window function syntax.

Note: Window function support is an experimental feature of the connector. This functionality extends beyond the connector's core scope of being SQL-92 compliant. As such, performance with window functions may not be optimal.

Window Function Clauses

OVER

The OVER clause defines the window over which window functions are performed.

SELECT A, B, <window function> OVER (<window frame>) FROM TableName

The <window function> refers to any supported window function clause, and the <window frame> refers to one or more clauses that specify the logic by which the window is defined.

PARTITION BY

The PARTITION BY clause subdivides a window into sub-windows called partitions. For each unique value in the column specified in the PARTITION BY clause, every record with that value collectively forms an individual partition.

SELECT A, B, <window function> OVER (PARTITION BY A ORDER BY B) From Account

The <window function> refers to any supported window function clause.

Window Functions

The connector supports math, ranking, and analytic window functions.

Math

These window functions perform mathematical operations on the records within the window.

COUNT()

Calculates the number of records in each partition. The calculated column is of the data type "int".

In each partition, every record will display the total number of records in that partition.

SELECT Name, Role, Earnings, COUNT() OVER (PARTITION BY Role) FROM Employees

COUNT_BIG()

Calculates the number of records in each partition. The calculated column is of the data type "bigint".

In each partition, every record will display the total number of records in that partition.

SELECT Name, Role, Earnings, COUNT_BIG() OVER (PARTITION BY Role) FROM Employees

MIN(numeric_column)

Calculates the minimum value of a numerical column per partition.

In each partition, every record will display the minimum value of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, MIN(Earnings) OVER (PARTITION BY Role) FROM Employees

MAX(numeric_column)

Calculates the maximum value of a numerical column per partition.

In each partition, every record will display the maximum value of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, MAX(Earnings) OVER (PARTITION BY Role) FROM Employees

SUM(numeric_column)

Calculates the sum of a numerical column per partition.

In each partition, every record will display the sum of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, SUM(Earnings) OVER (PARTITION BY Role) FROM Employees

AVG(numeric_column)

Calculates the average value of a numerical column per partition.

In each partition, every record will display the average value of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, AVG(Earnings) OVER (PARTITION BY Role) FROM Employees

MEDIAN(numeric_column)

Calculates the median value of a numerical column per partition.

In each partition, every record will display the median value of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, MEDIAN(Earnings) OVER (PARTITION BY Role) FROM Employees

STDEV(numeric_column)

Calculates the standard deviation of a numerical column per partition.

In each partition, every record will display the standard deviation of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, STDEV(Earnings) OVER (PARTITION BY Role) FROM Employees

STDEVP(numeric_column)

Calculates the population standard deviation of a numerical column per partition.

In each partition, every record will display the population standard deviation of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, STDEVP(Earnings) OVER (PARTITION BY Role) FROM Employees

VAR(numeric_column)

Calculates the statistical standard variance of a numerical column per partition.

In each partition, every record will display the statistical standard variance of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, VAR(Earnings) OVER (PARTITION BY Role) FROM Employees

VARP(numeric_column)

Calculates the variance population of a numerical column per partition.

In each partition, every record will display the variance population of numeric_column across the records in that partition.

SELECT Name, Role, Earnings, VARP(Earnings) OVER (PARTITION BY Role) FROM Employees

Ranking

These window functions rank records that fall within the window and its partitions.

RANK()

Assigns a rank number to each record in a window based on the value of the column specified in the required ORDER BY clause.

If two or more records have an equal value in the in ranked column, they all receive the same rank number and the rank count increments internally, skipping ahead one rank number for each record with a duplicate value in the ORDER BY column.

SELECT Id, Name, RANK() OVER (ORDER BY Name) AS Rank FROM Account

If you add a PARTITION BY clause, a separate set of ranks is calculated for each partition.

SELECT Id, Name, RANK() OVER (PARTITION BY Id ORDER BY Name) AS Rank FROM Account

DENSE_RANK()

Operates like the RANK() function, but it doesn't increment the internal rank counter for each record with a duplicate value in the ranked column.

This means that, while records with identical values in the ORDER BY column still share a rank number, the function never skips a rank number.

SELECT Id, Name, DENSE_RANK() OVER (PARTITION BY Id ORDER BY Name) AS Rank FROM Account

If you add a PARTITION BY clause, a separate set of ranks is calculated for each partition.

SELECT Id, Name, DENSE_RANK() OVER (PARTITION BY Id ORDER BY Name) AS Rank FROM Account

ROW_NUMBER()

Calculates a row number for each record. An ORDER BY clause in the OVER clause is required.

SELECT Name, Role, Earnings, ROW_NUMBER() OVER (ORDER BY Role) FROM Employees

If you define multiple partitions with PARTITION BY, a new set of row numbers are calculated for each partition.

SELECT Name, Role, Earnings, ROW_NUMBER() OVER (PARTITION BY Role ORDER BY Earnings) FROM Employees

NTILE()

Distributes rows of an ordered partition into a specified number of approximately equal groups, or buckets. It assigns each group a bucket number starting from one. For each row in a group, the NTILE() function assigns a bucket number representing the group to which the row belongs.

The syntax of NTILE() is:

NTILE(buckets) OVER (
    [PARTITION BY partition_expression, ... ]
    ORDER BY sort_expression [ASC | DESC], ...
)

The following are paramaters that NTILE() supports:

• buckets: The number of buckets into which the rows are divided. The buckets can be an expression or subquery that evaluates to a positive integer. It cannot be a window function.
• PARTITION BY: distributes rows of a result set into partitions to which the NTILE() function is applied.
• ORDER BY is clause that specifies the logical order of rows in each partition to which the NTILE() is applied.

If the number of rows is not divisible by the buckets, the NTILE() function returns groups of two sizes with the difference by one. The larger groups always precede the smaller group in the order set by ORDER BY in the OVER() clause.

If the total of rows is divisible by the number of buckets, the function divides the rows evenly among buckets. The following statement creates a new table named ntile_demo that stores 10 integers:

CREATE TABLE sales.ntile_demo (
	v INT NOT NULL
);
	
INSERT INTO sales.ntile_demo(v) 
VALUES(1),(2),(3),(4),(5),(6),(7),(8),(9),(10);	
	
SELECT * FROM sales.ntile_demo;

This statement uses the NTILE() function to divide ten rows into three groups:

SELECT 
	v, 
	NTILE (3) OVER (
		ORDER BY v
	) buckets
FROM 
	sales.ntile_demo;

Analytical

These window functions perform analytical operations on the records within the window.

PERCENT_RANK()

Calculates the relative rank SQL Percentile of each row. It returns values greater than zero, but the maximum value is one. It does not count any NULL values. This function is nondeterministic.

The syntax of PERCENT_RANK() is:

PERCENT_RANK() OVER (
      [PARTITION BY partition_expression, ... ]
      ORDER BY sort_expression [ASC | DESC], ...
  )
  

This syntax uses the following parameters.

• PARTITION BY: By default, SQL Server treats the whole data set as a single set. You can specify the PARTITION BY clause to divide data into multiple sets. The Percent_Rank function performs the analytical calculations on each set. This parameter is optional.
• ORDER BY: Sorts the data in either ascending or descending order. This parameter is required.

Table-valued functions are functions that return a table (rowset).

Note: Table-valued function support is an experimental feature of the connector. This functionality extends beyond the connector's core scope of being SQL-92 compliant. As such, performance with these functions may not be optimal.

Table-Valued Function Clauses

CROSS APPLY

The CROSS APPLY operator is used to perform a subquery on each row of a table or resultset produced by a preceding table expression.

<table_expression_1> CROSS APPLY <table_expression_2>

The second table expression can reference results from the first table expression to create derived columns or an altered recordset via a table-valued function.

Each resulting record is an instance of the record it's splitting, with all the same column values, except for the column(s) containing the value split by the function.

WITH

The WITH clause is used alongside certain table-valued functions to match against constructs within the structure being split (keys, element names, attribute names, etc.) and/or to specify metadata for the columns generated from the function.

SELECT A.ColumnName, X.DerivedColumnName FROM TableName A CROSS APPLY <table-valued function> WITH (DerivedColumnName varchar(255)) AS X

Table-Valued Functions

STRING_SPLIT(input_text,delimiter)

Takes each record in the recordset of the preceding table expression, splits the column containing delimiters (input_text) into substrings separated by the delimiter, and returns one record per substring.

• input_text: A column whose value you want to parse.
• delimiter: The character used to split the value of the column specified in input_text.

Suppose there is a column called "SplitColumn" with the following content:

One-Two-Three

To unpack this value across multiple records:

SELECT A.ID, X.Value FROM [TableWithDelimitedStringField] A CROSS APPLY STRING_SPLIT(A.SplitColumn,'-') WITH (Value VARCHAR(255)) AS X

-- Results:
-----------
|ID|Value|
|1|One|
|1|Two|
|1|Three|

JSONTABLE(json_content,[jsonpath])

For each record in the recordset of the preceding table expression, returns one record for each instance of a key in a JSON array (json_content) that matches the key(s) specified in the WITH clause, at the scope specified by the "jsonpath" input.

• json_content: A JSON "table" (array of objects). The contents can nest, but this must be a single JSON array, not any other JSON structure, at the root level.
  • The values of every instance of the key(s) provided in the WITH clause are retrievable only for substructures which are immediate children of the root-level JSON array.
• jsonpath: An optional JSONPath query defining the scope, within the json_content array, that you want to pull content from. The JSON key(s) identified in the WITH clause must exist at the scope defined in this parameter. This defaults to the JSON root ($).

Consider a sample table with a single record, including an ID column and column with JSON content called "JSONColumn" with the following content:

[
	{
		"name": "Samuel",
		"email": "sam@gmail.com",
		"extrainfo": {
			"city": "Seattle"
		}
	},
	{
		"name": "Katherine",
		"email": "kat@gmail.com",
	},
	{
		"name": "George",
		"email": "george23@gmail.com",
	},
	{
		"name": "Carlos",
		"email": "carlos32@gmail.com",
	}
]

To extract all values for a certain key, specify the scope in the JSONTABLE function and provide the desired key(s) in the WITH clause.

SELECT A.ID, X.name FROM [TableWithJSONField] A CROSS APPLY JSONTABLE(A.JSONColumn) WITH (name VARCHAR(255)) AS X

-- Results: 
|ID|name|
---------
|1 |Samuel|
|1 |Katherine|
|1 |George|
|1 |Carlos|

XMLTABLE(xml_content,[xpath,child_type])

For each record in the resultset of the preceding table expression, returns one record for each of the elements and/or attributes in an XML structure (xml_content) that match the tag name(s) and/or attribute name(s) specified in the WITH clause, at the scope specified in the "xpath" input.

• xml_content: A column containing an XML structure.
• xpath: An optional XPath that specifies the scope within the XML structure at which the connector extracts content matching the tag/attribute name(s) specified in the WITH clause.
  • When extracting the content of sub-elements, the connector can retrieve all content from tags at the root level, (depth 0) immediate children of the root (depth 1), and children of those children (depth 2).
  • When extracting element attribute content, the connector can retrieve all content from tags containing the specified attribute at the root level (depth 0) and from immediate children of root-level elements (depth 1).
• child_type: An optional parameter that specifies the part(s) of the parent element (specified in the xpath input) that the column(s) provided in the WITH clause are checked against to identify content.
  • You can supply the following values:
    • 0: The column(s) in the WITH clause are checked for matches against the parent element's attribute names and sub-element tag names.
    • 1: The column(s) in the WITH clause are checked for matches against the parent element's attribute names.
    • 2: The column(s) in the WITH clause are checked for matches against the parent element's sub-element tag names.
  • When not supplied, this defaults to 0.

Extracting Sub-Element Values

Consider a sample table with a single record, including an ID column and a column with XML content called "XMLContent" with the following content:

<shoppingList>
    <item>
        <name>Apples</name>
        <quantity>3</quantity>
        <unit>Kg</unit>
    </item>
    <item>
        <name>Bread</name>
        <quantity>2</quantity>
        <unit>Loaf</unit>
		<extrainfo>
			<Type>Whole-Grain</Type>
		</extrainfo>
    </item>
    <item>
        <name>Milk</name>
        <quantity>1</quantity>
        <unit>Carton</unit>
    </item>
    <item>
        <name>Eggs</name>
        <quantity>12</quantity>
        <unit></unit>
    </item>
</shoppingList>

To extract sub-element content, specify the scope in the XMLTABLE function and provide the desired element name(s) in the WITH clause. Note that this will not work if the XMLTABLE function's child_type input is set to 1.

SELECT A.ID, X.name FROM [TableWithXMLField] A CROSS APPLY XMLTABLE(A.XMLContent,'//*/item') WITH (name VARCHAR(255)) AS X

-- Results: 
|ID|name|
---------
|1|Apples|
|1|Bread|
|1|Milk|
|1|Eggs|

Extracting Values Using Element Tag Attributes

Suppose you have this sample table with a single record, including an ID column and a column with XML content called "XMLContent" with the following content:

<restaurant>
  <dish type="appetizer">
    <name lang="en">Caprese Salad</name>
    <chef>Chef Giovanni</chef>
    <price currency="USD">9.99</price>
  </dish>
  <dish type="main-course">
    <name lang="fr">Boeuf Bourguignon</name>
    <chef>Chef Marie</chef>
    <price currency="EUR">19.99</price>
  </dish>
  <dish type="dessert">
    <name lang="es">Tres Leches Cake</name>
    <chef>Chef Alejandro</chef>
    <price currency="MXN">89.99</price>
  </dish>
</restaurant>

To extract attribute content, specify the scope in the XMLTABLE function and provide the desired attribute name(s) in the WITH clause. Note that this will not work if the XMLTABLE function's child_type input is set to 2.

SELECT A.ID, X.type FROM [TableWithXMLField] A CROSS APPLY XMLTABLE(A.XMLContent,'//*/dish') WITH (type VARCHAR(255)) AS X

-- Results: 
|ID|type|
---------
|1|appetizer|
|1|main-course|
|1|dessert|

CSVTABLE(csv_content,[delimiter])

For each record in the resultset of the preceding table expression, reads from a column that contains a CSV table (csv_content) and for each record in that CSV table, returns one record containing the value of the CSV column(s) specified in the WITH clause.

• csv_content: A column containing a CSV table.
• delimiter: An optional custom delimiter (instead of a comma) which splits the CSV content contained in the csv_content input.

Consider a sample table with a single record, including an ID column and a column containing CSV table called "CSVContent" with the following content:

Name;Category;Price
Apple;Fruit;0.99
Spaghetti;Pasta;5.49
Chicken Breast;Meat;8.99
Broccoli;Vegetable;2.49

To select every value in the "Name" column and account for the custom delimiter (;):

SELECT A.ID, X.Name FROM [TableWithCSVField] A CROSS APPLY CSVTABLE(A.CSVContent,';') WITH (Name VARCHAR(255)) AS X

-- Results:
|ID|Name|
-----------
|1|Apple|
|1|Spaghetti|
|1|Chicken Breast|
|1|Broccoli|

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 Account (Name) VALUES ('John')

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 Account SET Name='John' WHERE Id = @myId

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 Account WHERE Id = @myId

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 Account

Use the following cache statement to cache all rows of a table into the cache table CachedAccount:

CACHE CachedAccount SELECT * FROM Account

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 CachedAccount SELECT * FROM Account 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 Id and Name even though the cache table CachedAccount has all the columns in Account.

CACHE CachedAccount SCHEMA ONLY SELECT * FROM Account
CACHE CachedAccount SELECT Id, Name FROM Account

Overview

This section shows the available API objects and provides more information on executing SQL to SAP ByDesign APIs.

Key Features

• The connector models SAP ByDesign Analytics Services as relational views. Entities defined on a Custom Service are modeled using a combination of tables and views, allowing you to write SQL to query SAP ByDesign data.
• Live connectivity to these objects means any changes to your SAP ByDesign account are immediately reflected when using the connector.

Tables

Tables are dynamically defined entities available on the ServiceType=CustomService.

Views

Views are dynamically defined either from the Navigation Properties off a ServiceType=CustomService, or from the queries on an ServiceType=AnalyticsService, ServiceType=ODataDataSource.

Analytics Services

To retrieve reports of an analytics service, you must specify the URL ServiceType=AnalyticsService property. For example: Url=https://my999999.businessbydesign.cloud.sap;ServiceType=AnalyticsService;ServiceName=cc_home_analytics.svc; . All the reports are exposed as views. Note that client-side filtering will be disables if one tries to perform an unsupported by the SAP ByDesign API filter on a dimension and at the same time does not include that dimension in the SELECT clause. If you want to make use of client-side filtering (executing filters that are not supported by the SAP ByDesign API), you need to include the dimension in the SELECT clause.

Also, if the query is a star query and the number of the dimensions is higher than 15, the driver will use only the default dimension and ignore the others. This is done because it is really hard to give sense to a result set with too many dimensions. This use case is common when the driver is used in various tools. The default dimension is chosen dynamically randomly by the driver.

The connector exposes tables for every entity set and singleton defined on the SAP ByDesign root URL. Entities on these tables may be inserted, updated, or deleted using standard SQL insert, update, or delete statements.

Executing Deep Inserts with SQL

The connector supports OData deep inserts, in which you simultaneously create a base entity and link it to related entities, by specifying navigation properties. To specify Navigation Properties for an entity, you create a temporary table for the navigation property and then reference the temporary table in the insert to the base table. Reference the temporary table in the appropriate navigation property column on the base table. Each navigation property column is prefixed with the word "Linked".

Note that you must define the temporary tables and insert to the base entity within the same connection.

Example: Deep Inserts

For example, consider a table, Orders. To create a new Order, you specify the Products ordered, Customer, Employee, and Shipper. To do so, you need to specify the following navigation properties.

Creating Temporary Tables

Insert the related entities into temporary tables that correspond to each navigation property. You can specify an existing entity's primary key or you can insert a new entity.

• Customer: The following statement creates a new Customer:
  

  INSERT INTO Customers#TEMP (CustomerID, CompanyName, ContactName, ContactTitle, Address, City, PostalCode, Country, Phone, Fax) 
  VALUES ('VINET', 'Vins et alcools Chevalier', 'Paul Henriot', 'Accounting Manager', '59 rue de l''Abbaye', 'Reims', '51100', 'France', '26.47.15.10', '26.47.15.11')

• Order Details: The following statements add two Products to the Order:
  

  INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (72, 34.80, 5, 0)
  
  INSERT INTO Order_Details#TEMP (ProductID, UnitPrice, Quantity, Discount) VALUES (42, 9.80, 10, 0)

• Employee: The following statement specifies the existing Employee:
  

  INSERT INTO Employees#TEMP (EmployeeID) 
  VALUES (5)

• Shipper: The following statement specifies the existing Shipper:
  

  INSERT INTO Shippers#TEMP (ShipperID) VALUES (3) 

The CData Python Connector for SAP ByDesign will assume that the Shipper and Employee already exist and will only link to the existing references since only the primary keys were specified for either. When more than just the primary key is defined, such as the examples for Customer and Order_Details, the CData Python Connector for SAP ByDesign will attempt to create new entries - triggering the deep insert.

Inserting the Entity

In the INSERT statement for the base entity, reference the temporary tables in the LinkedOrder_Details, LinkedCustomer, LinkedEmployee, and LinkedShipper columns:

INSERT INTO Orders (CustomerID, EmployeeID, ShipVia, ShipName, ShipAddress, ShipCity, ShipPostalCode, ShipCountry, OrderDate, LinkedOrder_Details, LinkedCustomer, LinkedEmployee, LinkedShipper) VALUES ('VINET', 5, 3, 'Paul Henriot', '59 rue de l''Abbaye', 'Reims', '51100', 'France', '07/04/1996', 'Order_Details#TEMP', 'Customers#TEMP', 'Employees#TEMP', 'Shippers#TEMP')

In OData, a navigation property is a property on an entity that is itself either a single entity or list of entities.

A single-entity navigation property signifies a one-to-one relationship; for example, an OData service might allow a Product to have only one Category. In this service, Category might be a navigation property on Products.

An entity set navigation property signifies a one-to-many relationship; for example, many Products can belong in the same Category. In this service, Products might be a navigation property on Categories.

Modeling Navigation Properties

By default, the connector models Navigation Properties as separate views. The views are named in the format ParentTable_NavigationProperty. You can disable this behavior with NavigationPropertiesAsViews.

Working with Navigation Properties Relationally

Navigation properties in OData link related entities. Similarly, in a relational database, a foreign key serves to link tables. For example, a Product record might have a CategoryId column, which uniquely identifies what Category the Product belongs to. However, there is no requirement in OData that an entity must contain a foreign key reference to a related entity. This means sometimes you will get navigation properties without having a foreign key reference to that entity on the parent or back to the parent from the related entity. In cases without a foreign key reference, the navigation property's existence is the only thing that can be used to identify a relationship between the two entities.

Select

NavigationPropertiesAsViews is useful for accessing data in OData services that lack foreign key references. Likewise, it can be used to retrieve related entites that do not exist by themselves such as LineItems on an Invoice. See tables for more information on querying navigation properties.

Insert

The connector supports OData deep inserts. See Tables for more information on specifying navigation properties when you create an entity.

Querying Navigation Properties

For an example of working with a navigation property as a view, consider BusinessPartners. The BusinessPartners entity set has an Orders navigation property. The CData Python Connector for SAP ByDesign will display a view called BusinessPartners_Orders for this service. Retrieving data from BusinessPartners_Orders will display all of the Orders associated with a given BusinessPartner. The BusinessPartners_Orders view has a primary key made up of the primary key of the parent entity and the primary key of the related entity.

Stored procedures are function-like interfaces that extend the functionality of the connector beyond simple SELECT/INSERT/UPDATE/DELETE operations with SAP ByDesign.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from SAP ByDesign, along with an indication of whether the procedure succeeded or failed.

CData Python Connector for SAP ByDesign Stored Procedures

Name	Description
GetOAuthAccessToken	Get an authentication token from SAP ByDesign.
GetOAuthAuthorizationUrl	Usage information for the operation GetOAuthAuthorizationURL.rsb.
RefreshOAuthAccessToken	Internal procedure to get new token from Azure IdP.

Get an authentication token from SAP ByDesign.

Input

Name	Type	Required	Description
AuthMode	String	False	Specifies the authentication mode. The allowed values are APP, WEB. The default value is WEB.
Verifier	String	False	An authorization code that will be exchanged for a token.
CallbackURL	String	False	The URL to which the system will redirect after authentication is complete.
State	String	False	A parameter used to maintain state between the request and callback, often used to prevent CSRF attacks.

Result Set Columns

Name	Type	Description
OAuthAccessToken	String	The access token.
OAuthRefreshToken	String	The refresh token.
ExpiresIn	String	The remaining lifetime on the access token. A -1 denotes that it will not expire.

Usage information for the operation GetOAuthAuthorizationURL.rsb.

Input

Name	Type	Required	Description
CallbackURL	String	False	The URL to which the system will redirect after authentication is complete.
State	String	False	A parameter used to maintain state between the request and callback, often used to prevent CSRF attacks.

Result Set Columns

Name	Type	Description
Url	String	The generated url.

Internal procedure to get new token from Azure IdP.

Input

Name	Type	Required	Description
OAuthRefreshToken	String	True	An active refresh token.

Result Set Columns

Name	Type	Description
OAuthAccessToken	String	The access token.
OAuthRefreshToken	String	The refresh token.
ExpiresIn	String	The remaining lifetime on the access token. A -1 denotes that it will not expire.

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 SAP ByDesign:

• sys_catalogs: Lists the available databases.
• sys_schemas: Lists the available schemas.
• sys_tables: Lists the available tables and views.
• sys_tablecolumns: Describes the columns of the available tables and views.
• sys_procedures: Describes the available stored procedures.
• sys_procedureparameters: Describes stored procedure parameters.
• sys_keycolumns: Describes the primary and foreign keys.
• sys_indexes: Describes the available indexes.

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.

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.

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.

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.

Describes the columns of the available tables and views.

The following query returns the columns and data types for the Account table:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName = 'Account' 

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.

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.

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 SAP ByDesign 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.

Describes the primary and foreign keys.

The following query retrieves the primary key for the Account table:

         SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Account' 
          

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.

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.

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.

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.

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.

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.

Name	Description	Possible Values
AGGREGATE_FUNCTIONS	Supported aggregation functions.	AVG, COUNT, MAX, MIN, SUM, DISTINCT
COUNT	Whether COUNT function is supported.	YES, NO
IDENTIFIER_QUOTE_OPEN_CHAR	The opening character used to escape an identifier.	[
IDENTIFIER_QUOTE_CLOSE_CHAR	The closing character used to escape an identifier.	]
SUPPORTED_OPERATORS	A list of supported SQL operators.	=, >, <, >=, <=, <>, !=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL, AND, OR
GROUP_BY	Whether GROUP BY is supported, and, if so, the degree of support.	NO, NO_RELATION, EQUALS_SELECT, SQL_GB_COLLATE
OJ_CAPABILITIES	The supported varieties of outer joins supported.	NO, LEFT, RIGHT, FULL, INNER, NOT_ORDERED, ALL_COMPARISON_OPS
OUTER_JOINS	Whether outer joins are supported.	YES, NO
SUBQUERIES	Whether subqueries are supported, and, if so, the degree of support.	NO, COMPARISON, EXISTS, IN, CORRELATED_SUBQUERIES, QUANTIFIED
STRING_FUNCTIONS	Supported 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_FUNCTIONS	Supported 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_FUNCTIONS	Supported 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_TABLES	Indicates tables skipped during replication.
REPLICATION_TIMECHECK_COLUMNS	A 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_PATTERN	String value indicating what string is valid for an identifier.
SUPPORT_TRANSACTION	Indicates if the provider supports transactions such as commit and rollback.	YES, NO
DIALECT	Indicates the SQL dialect to use.
KEY_PROPERTIES	Indicates the properties which identify the uniform database.
SUPPORTS_MULTIPLE_SCHEMAS	Indicates if multiple schemas may exist for the provider.	YES, NO
SUPPORTS_MULTIPLE_CATALOGS	Indicates if multiple catalogs may exist for the provider.	YES, NO
DATASYNCVERSION	The CData Data Sync version needed to access this driver.	Standard, Starter, Professional, Enterprise
DATASYNCCATEGORY	The CData Data Sync category of this driver.	Source, Destination, Cloud Destination
SUPPORTSENHANCEDSQL	Whether enhanced SQL functionality beyond what is offered by the API is supported.	TRUE, FALSE
SUPPORTS_BATCH_OPERATIONS	Whether batch operations are supported.	YES, NO
SQL_CAP	All 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_OPTIONS	A string value specifies the preferred cacheOptions.
ENABLE_EF_ADVANCED_QUERY	Indicates if the driver directly supports advanced queries coming from Entity Framework. If not, queries will be handled client side.	YES, NO
PSEUDO_COLUMNS	A string array indicating the available pseudo columns.
MERGE_ALWAYS	If the value is true, The Merge Mode is forcibly executed in Data Sync.	TRUE, FALSE
REPLICATION_MIN_DATE_QUERY	A select query to return the replicate start datetime.
REPLICATION_MIN_FUNCTION	Allows a provider to specify the formula name to use for executing a server side min.
REPLICATION_START_DATE	Allows a provider to specify a replicate startdate.
REPLICATION_MAX_DATE_QUERY	A select query to return the replicate end datetime.
REPLICATION_MAX_FUNCTION	Allows a provider to specify the formula name to use for executing a server side max.
IGNORE_INTERVALS_ON_INITIAL_REPLICATE	A list of tables which will skip dividing the replicate into chunks on the initial replicate.
CHECKCACHE_USE_PARENTID	Indicates whether the CheckCache statement should be done against the parent key column.	TRUE, FALSE
CREATE_SCHEMA_PROCEDURES	Indicates 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.

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.

Describes the available system information.

The following query retrieves all columns:

SELECT * FROM sys_information

Columns

Name	Type	Description
Product	String	The name of the product.
Version	String	The version number of the product.
Datasource	String	The name of the datasource the product connects to.
NodeId	String	The unique identifier of the machine where the product is installed.
HelpURL	String	The URL to the product's help documentation.
License	String	The license information for the product. (If this information is not available, the field may be left blank or marked as 'N/A'.)
Location	String	The file path location where the product's library is stored.
Environment	String	The version of the environment or rumtine the product is currently running under.
DataSyncVersion	String	The tier of CData Sync required to use this connector.
DataSyncCategory	String	The category of CData Sync functionality (e.g., Source, Destination).

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

---

Property	Description
AuthScheme	The type of authentication to use when connecting to SAP ByDesign.
URL	URL to your system host name.
ServiceType	Specify the type of the service to get reports from. Used together with the URL and ServiceName connection properties to determine the service from where to retrieve data from.
User	Specifies the authenticating user's user ID.
Password	Specifies the authenticating user's password.

Azure Authentication

---

Property	Description
AzureTenant	Identifies the SAP ByDesign tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.

SSO

---

Property	Description
SSOProperties	Additional properties required to connect to the identity provider, formatted as a semicolon-separated list.

SSL

---

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

Firewall

---

Property	Description
FirewallType	Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
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.
FirewallPort	Specifies the TCP port to be used for a proxy-based firewall.
FirewallUser	Identifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPassword	Specifies the password of the user account authenticating to a proxy-based firewall.

Proxy

---

Property	Description
ProxyAutoDetect	Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServer	Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPort	Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthScheme	Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUser	Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPassword	Specifies the password of the user specified in the ProxyUser connection property.
ProxySSLType	Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
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.

Logging

---

Property	Description
Logfile	Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
Verbosity	Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
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.
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.
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.

Connection

---

Property	Description
ServiceName	Specify the SAP ByDesign service name to connect with.

Schema

---

Property	Description
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.
BrowsableSchemas	Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
Tables	Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
Views	Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

Caching

---

Property	Description
AutoCache	Specifies whether the content of tables targeted by SELECT queries is automatically cached to the specified cache database.
CacheProvider	The namespace of an ADO.NET provider. The specified provider is used as the target database for all caching operations.
CacheDriver	The driver class of a JDBC driver. The specified driver is used to connect to the target database for all caching operations.
CacheConnection	Specifies the connection string for the specified cache database.
CacheLocation	Specifies the path to the cache when caching to a file.
CacheTolerance	Notes the tolerance, in seconds, for stale data in the specified cache database. Requires AutoCache to be set to True.
Offline	Gets the data from the specified cache database instead of live SAP ByDesign data.
CacheMetadata	Determines whether the provider caches table metadata to a file-based cache database.

OAuth

---

Property	Description
InitiateOAuth	Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.
OAuthClientId	Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret	Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthAccessToken	Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthSettingsLocation	Specifies the location of the settings file where OAuth values are saved.
SAPIASBaseURL	The base URL of the SAP Identity Authentication Service (IAS) tenant used for authentication.
OAuthVerifier	Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
OAuthRefreshToken	Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthExpiresIn	Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthTokenTimestamp	Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

Miscellaneous

---

Property	Description
ExpandAsterisk	Indicates whether the asterisk should be expanded in the $select query parameter.
MaxReportDimensions	The default number of dimensions to select from queried reports.
MaxRows	Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
MaxSelectLength	Specifies a maximum length for columns in $select projections to prevent [414] URI Too Long errors. Set to -1 to disable. Not supported when ServiceType is AnalyticsService.
NavigationPropertiesAsViews	A boolean indicating navigation properties should be promoted to full views.
Other	Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
Readonly	Toggles read-only access to SAP ByDesign from the provider.
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.
Timeout	Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.
UseDisplayNames	Boolean determining whether or not to use SAP labels.
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.

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

---

Property	Description
AuthScheme	The type of authentication to use when connecting to SAP ByDesign.
URL	URL to your system host name.
ServiceType	Specify the type of the service to get reports from. Used together with the URL and ServiceName connection properties to determine the service from where to retrieve data from.
User	Specifies the authenticating user's user ID.
Password	Specifies the authenticating user's password.

The type of authentication to use when connecting to SAP ByDesign.

Possible Values

Basic, AzureAD, SAPIAS, SAPIASPassword

Data Type

string

Default Value

"Basic"

Remarks

• Basic: Set this to use BASIC user / password authentication.
• AzureAD: Set this to perform SSO authentication with AzureAD. Refer to the connection property SSOProperties for more information.
• SAPIAS: Set this to perform SSO authentication through SAP Identity Authentication Service (SAP IAS) using the OAuth Authorization Code grant flow. Please see the connection property SSOProperties for more information.
• SAPIASPassword: Set this to perform SSO authentication through SAP Identity Authentication Service (SAP IAS) using the OAuth Password grant flow. Please see the connection property SSOProperties for more information.

URL to your system host name.

Data Type

string

Default Value

""

Remarks

URL to your system host name.

Specify the type of the service to get reports from. Used together with the URL and ServiceName connection properties to determine the service from where to retrieve data from.

Possible Values

AnalyticsService, CustomService, ODataDataSource

Data Type

string

Default Value

"AnalyticsService"

Remarks

• AnalyticsService : If you want to retrieve reports from analytic service.
• CustomService : If you want to want to retrieve data from the custom service you have configured in the UI.
• ODataDataSource: If you want to query the DataSources (OData Data Source API -> odata/analytics/ds ).

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.

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.

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

---

Property	Description
AzureTenant	Identifies the SAP ByDesign tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.

Identifies the SAP ByDesign tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.

Data Type

string

Default Value

""

Remarks

A tenant is a digital container for your organization's users and resources, managed through Microsoft Entra ID (formerly Azure AD). Each tenant is associated with a unique directory ID, and often with a custom domain (for example, microsoft.com or contoso.onmicrosoft.com).

To find the directory (tenant) ID in the Microsoft Entra Admin Center, navigate to Microsoft Entra ID > Properties and copy the value labeled "Directory (tenant) ID".

This property is required in the following cases:

• When AuthScheme is set to AzureServicePrincipal or AzureServicePrincipalCert
• When AuthScheme is AzureAD and the user account belongs to multiple tenants

You can provide the tenant value in one of two formats:

• A domain name (for example, contoso.onmicrosoft.com)
• A directory (tenant) ID in GUID format (for example, c9d7b8e4-1234-4f90-bc1a-2a28e0f9e9e0)

Specifying the tenant explicitly ensures that the authentication request is routed to the correct directory, which is especially important when a user belongs to multiple tenants or when using service principal–based authentication.

If this value is omitted when required, authentication may fail or connect to the wrong tenant. This can result in errors such as unauthorized or resource not found.

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

---

Property	Description
SSOProperties	Additional properties required to connect to the identity provider, formatted as a semicolon-separated list.

Additional properties required to connect to the identity provider, formatted as a semicolon-separated list.

Data Type

string

Default Value

""

Remarks

Additional properties required to connect to the identity provider, formatted as a semicolon-separated list.

SSO configuration is discussed further in Establishing a Connection.

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

---

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

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.

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

---

Property	Description
FirewallType	Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
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.
FirewallPort	Specifies the TCP port to be used for a proxy-based firewall.
FirewallUser	Identifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPassword	Specifies the password of the user account authenticating to a proxy-based firewall.

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 SAP ByDesign. Traffic flows back and forth via the proxy at this location.
SOCKS4	1080	The port where the connector opens a connection to SAP ByDesign. 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 SAP ByDesign. 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.

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.

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.

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.

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.

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

---

Property	Description
ProxyAutoDetect	Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServer	Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPort	Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthScheme	Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUser	Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPassword	Specifies the password of the user specified in the ProxyUser connection property.
ProxySSLType	Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
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.

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.

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.

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.

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.

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.

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.

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 :

AUTO	Default 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.
ALWAYS	The connection is always SSL enabled.
NEVER	The connection is not SSL enabled.
TUNNEL	The 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.

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.

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

---

Property	Description
Logfile	Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
Verbosity	Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
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.
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.
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.

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:

• Use Verbosity to control the level of detail of the log file.
• Manage log file size with MaxLogFileSize and control the number of retained log files with MaxLogFileCount.
• Filter specific log modules by adjusting the LogModules property.

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.

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.	—

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.

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.

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

---

Property	Description
ServiceName	Specify the SAP ByDesign service name to connect with.

Specify the SAP ByDesign service name to connect with.

Data Type

string

Default Value

""

Remarks

Specify the SAP ByDesign service name to connect with. Leave this empty to retrieve all services.

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

---

Property	Description
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.
BrowsableSchemas	Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
Tables	Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
Views	Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

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\\SAPByDesign 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\\SAPByDesign 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

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.

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.

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.

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

---

Property	Description
AutoCache	Specifies whether the content of tables targeted by SELECT queries is automatically cached to the specified cache database.
CacheProvider	The namespace of an ADO.NET provider. The specified provider is used as the target database for all caching operations.
CacheDriver	The driver class of a JDBC driver. The specified driver is used to connect to the target database for all caching operations.
CacheConnection	Specifies the connection string for the specified cache database.
CacheLocation	Specifies the path to the cache when caching to a file.
CacheTolerance	Notes the tolerance, in seconds, for stale data in the specified cache database. Requires AutoCache to be set to True.
Offline	Gets the data from the specified cache database instead of live SAP ByDesign data.
CacheMetadata	Determines whether the provider caches table metadata to a file-based cache database.

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 SAP ByDesign.
• 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.

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;'URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

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";URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

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';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

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;

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:sapbydesign:CacheDriver=org.apache.derby.jdbc.EmbeddedDriver;CacheConnection='jdbc:derby:sample';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

To cache to an in-memory database, use a JDBC URL like the following:

jdbc:sapbydesign:CacheDriver=org.apache.derby.jdbc.EmbeddedDriver;CacheConnection='jdbc:derby:memory';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

SQLite

The following is a JDBC URL for the SQLite JDBC driver:

jdbc:sapbydesign:CacheDriver=org.sqlite.JDBC;CacheConnection='jdbc:sqlite:C:/Temp/sqlite.db';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

MySQL

The following is a JDBC URL for the CData JDBC Driver for MySQL:

  jdbc:sapbydesign:Cache Driver=cdata.jdbc.mysql.MySQLDriver;Cache Connection='jdbc:mysql:Server=localhost;Port=3306;Database=cache;User=root;Password=123456';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;
  

SQL Server

The following JDBC URL uses the Microsoft JDBC Driver for SQL Server:

jdbc:sapbydesign:Cache Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver;Cache Connection='jdbc:sqlserver://localhost\sqlexpress:7437;user=sa;password=123456;databaseName=Cache';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

Oracle

The following is a JDBC URL for the Oracle Thin Client:

jdbc:sapbydesign:Cache Driver=oracle.jdbc.OracleDriver;CacheConnection='jdbc:oracle:thin:scott/tiger@localhost:1521:orcldb';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

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:sapbydesign:CacheDriver=cdata.jdbc.postgresql.PostgreSQLDriver;CacheConnection='jdbc:postgresql:User=postgres;Password=admin;Database=postgres;Server=localhost;Port=5432;';URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

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.

Specifies the path to the cache when caching to a file.

Data Type

string

Default Value

"%APPDATA%\\CData\\SAPByDesign Data Provider"

Remarks

The CacheLocation is a simple, file-based cache.

If left unspecified, the default location is %APPDATA%\\CData\\SAPByDesign 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 SAP ByDesign catalog in CacheLocation.

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.

Gets the data from the specified cache database instead of live SAP ByDesign 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 SAP ByDesign data.

In this mode, some SQL operations like INSERT, UPDATE, DELETE, and CACHE are disabled.

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 SAP ByDesign 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:

Platform	Home Directory
Windows	%APPDATA%\\CData\\SAPByDesign Data Provider
Mac	~/Library/Application Support/CData/SAPByDesign Data Provider
Unix	~/.config/CData/SAPByDesign 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 SAP ByDesign 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 SAP ByDesign 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 SAP ByDesign.

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.

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

---

Property	Description
InitiateOAuth	Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.
OAuthClientId	Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret	Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthAccessToken	Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthSettingsLocation	Specifies the location of the settings file where OAuth values are saved.
SAPIASBaseURL	The base URL of the SAP Identity Authentication Service (IAS) tenant used for authentication.
OAuthVerifier	Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
OAuthRefreshToken	Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthExpiresIn	Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthTokenTimestamp	Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.

Possible Values

OFF, REFRESH, GETANDREFRESH

Data Type

string

Default Value

"OFF"

Remarks

OAuth is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. The OAuth flow defines the method to be used for:

• Logging in users.
• Exchanging user credentials for an OAuth access token to be used for authentication.
• Providing limited access to applications.

The options for initiating and maintaining OAuth access are named for the parts of that flow that the connector handles:

OFF	The connector provides no automatic OAuth flow initiation. The OAuth flow is handled entirely by the user. This means that the user must refresh the token manually, and reconnect with an updated OAuthAccessToken property when the current token expires.
GETANDREFRESH	The connector handles the entire OAuth flow (both GET and REFRESH). This means that if a token already exists, the connector refreshes it when necessary; if no token currently exists, the connector obtains it by prompting the user to login.
REFRESH	The user obtains the OAuth Access Token and sets up the sequence for refreshing the OAuth Access Token. (The user is never prompted to log in to authenticate.) After the user logs in, the connector handles the refresh of the OAuth Access Token.

For more information on how to set up OAuth and use this property when configuring a connection, see Establishing a Connection.

Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.

Data Type

string

Default Value

""

Remarks

This property is required in two cases:

• When using a custom OAuth application, such as in web-based authentication flows, service-based authentication, or certificate-based flows that require application registration.
• If the driver does not provide embedded OAuth credentials.

(When the driver provides embedded OAuth credentials, this value may already be provided by the connector and thus not require manual entry.)

OAuthClientId is generally used alongside other OAuth-related properties such as OAuthClientSecret and OAuthSettingsLocation when configuring an authenticated connection.

OAuthClientId is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can usually find this value in your identity provider’s application registration settings. Look for a field labeled Client ID, Application ID, or Consumer Key.

While the client ID is not considered a confidential value like a client secret, it is still part of your application's identity and should be handled carefully. Avoid exposing it in public repositories or shared configuration files.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).

Data Type

string

Default Value

""

Remarks

This property (sometimes called the application secret or consumer secret) is required when using a custom OAuth application in any flow that requires secure client authentication, such as web-based OAuth, service-based connections, or certificate-based authorization flows. It is not required when using an embedded OAuth application.

The client secret is used during the token exchange step of the OAuth flow, when the driver requests an access token from the authorization server. If this value is missing or incorrect, authentication fails with either an invalid_client or an unauthorized_client error.

OAuthClientSecret is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can obtain this value from your identity provider when registering the OAuth application.

Notes:

• This value should be stored securely and never exposed in public repositories, scripts, or unsecured environments.
• Client secrets may also expire after a set period. Be sure to monitor expiration dates and rotate secrets as needed to maintain uninterrupted access.

For more information on how this property is used when configuring a connection, see Establishing a Connection

Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.

Data Type

string

Default Value

""

Remarks

OAuthAccessToken is a temporary credential that authorizes access to protected resources. It is typically returned by the identity provider after the user or client application completes an OAuth authentication flow. This property is most commonly used in automated workflows or custom OAuth implementations where you want to manage token handling outside of the driver.

The OAuth access token has a server-dependent timeout, limiting user access. The timeout is set using the OAuthExpiresIn property. However, it can be reissued between requests to keep access alive as long as the user keeps working.

If InitiateOAuth is set to REFRESH, we recommend that you also set both OAuthExpiresIn and OAuthTokenTimestamp. The connector uses these properties to determine when the token expires so it can refresh most efficiently. If OAuthExpiresIn and OAuthTokenTimestamp are not specified, the connector refreshes the token immediately.

Note: Access tokens should be treated as sensitive credentials and stored securely. Avoid exposing them in logs, scripts, or configuration files that are not access-controlled.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the location of the settings file where OAuth values are saved.

Data Type

string

Default Value

"%APPDATA%\\CData\\SAPByDesign Data Provider\\OAuthSettings.txt"

Remarks

Storing OAuth settings in a central location avoids the need for users to enter OAuth connection properties manually each time they log in. It also enables credentials to be shared across connections or processes.

You can store OAuth values in a central file for shared access to those values, in either of the following ways:

• Set InitiateOAuth to either GETANDREFRESH or REFRESH and specify a filepath to the OAuth settings file.
• Use memory storage to load the credentials into static memory.

The following sections provide more detail on each of these methods.

Specifying the OAuthSettingsLocation Filepath

The default OAuth setting location is %APPDATA%\\CData\\SAPByDesign Data Provider\\OAuthSettings.txt, with %APPDATA% set to the user's configuration directory. Default values vary, depending on the user's operating system.

• Windows (ODBC and Power BI): registry://%DSN%
• Windows: %APPDATA%CDataSAPByDesign Data Provider\OAuthSettings.txt
• Mac: %APPDATA%/CData/SAPByDesign Data Provider/OAuthSettings.txt
• Linux: %APPDATA%/CData/SAPByDesign Data Provider/OAuthSettings.txt

Loading Credentials Via Memory Storage

Memory locations are specified by using a value starting with memory://, followed by a unique identifier for that set of credentials (for example, memory://user1). The identifier can be anything you choose, but it should be unique to the user.

Unlike file-based storage, where credentials persist across connections, memory storage loads the credentials into static memory and the credentials are shared between connections using the same identifier for the life of the process. To persist credentials outside the current process, you must manually store the credentials prior to closing the connection. This enables you to set them in the connection when the process is started again.

To retrieve OAuth property values, query the sys_connection_props system table. If there are multiple connections using the same credentials, the properties are read from the previously closed connection.

Supported Storage Types

• memory://: Stores OAuth tokens in-memory (unique identifier, shared within same process, etc.)
• registry://: Only supported in the Windows ODBC and Power BI editions. Stores OAuth tokens in the registry under the DSN settings. Must end in a DSN name like registry://CData Python Connector for SAP ByDesign Data Source, or registry://%DSN%.
• %DSN%: The name of the DSN you are connecting with.
• Default (no prefix): Stores OAuth tokens within files. The value can be either an absolute path, or a path starting with %APPDATA% or %PROGRAMFILES%.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

The base URL of the SAP Identity Authentication Service (IAS) tenant used for authentication.

Data Type

string

Default Value

""

Remarks

Specifies the base URL of the SAP Identity Authentication Service (IAS) tenant. This URL is used to initiate the OAuth 2.0 authentication flow to obtain access tokens.

Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.

Data Type

string

Default Value

""

Remarks

For detailed instructions about how to obtain the OAuthVerifier value, see Establishing a Connection.

Specifies the OAuth refresh token used to request a new access token after the original has expired.

Data Type

string

Default Value

""

Remarks

The refresh token is used to obtain a new access token when the current one expires. It enables seamless authentication for long-running or automated workflows without requiring the user to log in again. This property is especially important in headless, CI/CD, or server-based environments where interactive authentication is not possible.

The refresh token is typically obtained during the initial OAuth exchange by calling the GetOAuthAccessToken stored procedure. After that, it can be set using this property to enable automatic token refresh, or passed to the RefreshOAuthAccessTokenproc; stored procedure if you prefer to manage the refresh manually.

When InitiateOAuth is set to REFRESH, the driver uses this token to retrieve a new access token automatically. After the first refresh, the driver saves updated tokens in the location defined by OAuthSettingsLocation, and uses those values for subsequent connections.

Note: The OAuthRefreshToken should be handled securely and stored in a trusted location. Like access tokens, refresh tokens can expire or be revoked depending on the identity provider’s policies.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.

Data Type

string

Default Value

""

Remarks

The OAuth Access Token is assigned to an authenticated user, granting that user access to the network for a specified period of time. The access token is used in place of the user's login ID and password, which stay on the server.

An access token created by the server is only valid for a limited time. OAuthExpiresIn is the number of seconds the token is valid from when it was created. For example, a token generated at 2024-01-29 20:00:00 UTC that expires at 2024-01-29 21:00:00 UTC (an hour later) would have an OAuthExpiresIn value of 3600, no matter what the current time is.

To determine how long the user has before the Access Token will expire, check OAuthTokenTimestamp.

Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

Data Type

string

Default Value

""

Remarks

The OAuth access token is assigned to an authenticated user, granting that user access to the network for a specified period of time. The access token is used in place of the user's login ID and password, which stay on the server.

An access token created by the server is only valid for a limited time. OAuthTokenTimestamp is the Unix timestamp when the server created the token. For example, OAuthTokenTimestamp=1706558400 indicates the OAuthAccessToken was generated by the server at 2024-01-29 20:00:00 UTC.

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

---

Property	Description
ExpandAsterisk	Indicates whether the asterisk should be expanded in the $select query parameter.
MaxReportDimensions	The default number of dimensions to select from queried reports.
MaxRows	Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
MaxSelectLength	Specifies a maximum length for columns in $select projections to prevent [414] URI Too Long errors. Set to -1 to disable. Not supported when ServiceType is AnalyticsService.
NavigationPropertiesAsViews	A boolean indicating navigation properties should be promoted to full views.
Other	Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
Readonly	Toggles read-only access to SAP ByDesign from the provider.
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.
Timeout	Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.
UseDisplayNames	Boolean determining whether or not to use SAP labels.
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.