Connecting to QuickBooks Online

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

QuickBooks Online Version Support

The connector models the QuickBooks Online Accounting APIs as a relational database.

See Also

• Using the Connector: Establish connections and query QuickBooks Online through Python code.
• From SQLAlchemy: Use SQLAlchemy to establish a connection with dialect URL, and interact with QuickBooks Online 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 QuickBooks Online 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_quickbooksonline_connector-26.0.9666-cp310-abi3-win_amd64.whl

Linux:

pip install cdata_quickbooksonline_connector-26.0.9666-cp310-abi3-linux_x86_64.whl

macOS:

pip install cdata_quickbooksonline_connector-26.0.9666-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_quickbooksonline_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_quickbooksonline" 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_quickbooksonline folder is trivial to find:

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

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

1. Import the module as follows:
   

   import cdata.quickbooksonline 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("InitiateOAuth=GETANDREFRESH;")

Authenticating to QuickBooks Online

QuickBooks Online supports connecting and authenticating via a desktop application, a web browser, or a headless machine. The CData Python Connector for QuickBooks Online includes embedded OAuth credentials that simplify connection from the desktop or a headless machine and provide limited functionality. However, to experience fuller functionality via desktop or headless machine connections OR to connect via the web, you must create a custom OAuth application, as described in Creating a Custom OAuth Application.

The following subsections describe how to authenticate to QuickBooks Online from all OAuth workflows. For information about how to create a custom OAuth application, see Creating a Custom OAuth Application. For a complete list of connection string properties available in QuickBooks Online, see Connection.

Desktop Applications

The properties required for connection depend on whether you want to connect via the embedded OAuth credentials (limited use) or connect via a custom OAuth Application (full functionality):

Before you connect, set the required properties:

• InitiateOAuth (all users): GETANDREFRESH. Used to automatically get and refresh the OAuthAccessToken.
• OAuthClientId (custom OAuth only): The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
• OAuthClientSecret (custom OAuth only): The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
• CallbackURL (custom OAuth only): The redirect URI defined when you registered your custom OAuth application (see Creating a Custom OAuth Application).

When you connect, the connector opens QuickBooks Online's OAuth endpoint in your default browser. Log in and grant permissions to the application.

After you grant permissions to the application, the connector completes the OAuth process:

1. The connector obtains an access token from QuickBooks Online and uses it to request data.
2. The OAuth values are saved in the path specified in OAuthSettingsLocation. These values persist across connections.

When the access token expires, the connector refreshes it automatically.

Web Applications

Authenticating via the Web requires you to create and register a custom OAuth application with QuickBooks Online, as described in Creating a Custom OAuth Application. You can then use the connector to get and manage the OAuth token values.

This section describes how to get the OAuth access token, how to have the driver refresh the OAuth access token automatically, and how to refresh the OAuth access token manually.

Get the OAuth access token:

1. To obtain the OAuthAccessToken, set these connection properties:
   • OAuthClientId: The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthClientSecret: The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

2. Call stored procedures to complete the OAuth exchange:
   • Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and the CallbackURL to the Redirect URI you specified in your custom OAuth application settings. The stored procedure returns the URL to the OAuth endpoint.
   • Navigate to the URL that the stored procedure returned in Step 1. Log in and authorize the web application. You are redirected back to the callback URL.
   • 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 redirect URI.

After you obtain the access and refresh tokens, you can connect to data and refresh the OAuth access token automatically.

Automatic refresh of the OAuth access token:

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

1. The first time you connect to data, set these connection parameters:
   • InitiateOAuth: REFRESH.
   • OAuthClientId: The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthClientSecret: The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthAccessToken: The access token returned by GetOAuthAccessToken.
   • OAuthSettingsLocation: The path where you want the connector to save the OAuth values, which persist across connections.

2. On subsequent data connections, set:
   • InitiateOAuth
   • OAuthSettingsLocation

Manual refresh of the OAuth access token:

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

1. To manually refresh the OAuthAccessToken after the ExpiresIn period (returned by GetOAuthAccessToken) has elapsed, call the RefreshOAuthAccessToken stored procedure.
2. Set these connection properties:
   • OAuthClientId: The Client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthClientSecret: The Client Secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

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

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

Headless Machines

If you need to log in to a resource that resides on a headless machine, you must authenticate on another device that has an internet browser. You can do this in either of the following ways:

• Option 1: Obtain the OAuthVerifier value.
• Option 2: Install the connector on a machine with an internet browser and transfer the OAuth authentication values after you authenticate through the usual browser-based flow.

After you execute either Option 1 or Option 2, configure the driver to automatically refresh the access token on the headless machine.

Option 1: Obtaining and Exchanging a Verifier Code

To obtain a verifier code, you must authenticate at the OAuth authorization URL as follows:

1. Authenticate from the machine with an internet browser, and obtain the OAuthVerifier connection property.

   If you are using the embedded OAuth application, call the GetOAuthAuthorizationURL stored procedure. Open the URL returned by the stored procedure in a browser.

   If you are using a custom OAuth application, set these properties:

   • InitiateOAuth: OFF.
   • OAuthClientId: The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthClientSecret: The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

2. Call the GetOAuthAuthorizationURL stored procedure. The stored procedure returns the CallbackURL established when the custom OAuth application was registered (see Creating a Custom OAuth Application).

   Copy this URL and paste it into a new browser tab.

3. Log in and grant permissions to the connector. The OAuth application redirects you the redirect URI, with a parameter called code appended. Note the value of this parameter; you will need it later, to configure the OAuthVerifier connection property.

4. Exchange the OAuth verifier code for OAuth refresh and access tokens. On the headless machine, to obtain the OAuthAccessToken, set these connection properties:

   • InitiateOAuth (all users): REFRESH.
   • OAuthVerifier (all users): The noted verifier code (the value of the code parameter in the redirect URI).
   • OAuthSettingsLocation (all users): persist the encrypted OAuth authentication values to the specified file.
   • OAuthClientId (custom OAuth only): The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
   • OAuthClientSecret (custom OAuth only): The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

   • Test the connection to generate the OAuth settings file.

   • You are ready connect after you re-set these properties:

     • InitiateOAuth (all users): REFRESH.
     • OAuthSettingsLocation (all users): The file containing the encrypted OAuth authentication values. To enable the automatic refreshing of the access token, be sure that this file gives read and write permissions to the connector.
     • OAuthClientId (custom OAuth only):: The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
     • OAuthClientSecret (custom OAuth only):: The client secret aassigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

Option 2: Transferring OAuth Settings

Prior to connecting on a headless machine, you must install and create a connection with the driver on a device that supports an internet browser. Set the connection properties as described above in "Desktop Applications".

After completing the instructions in "Desktop Applications", the resulting authentication values are encrypted and written to the path specified by OAuthSettingsLocation. The default filename is OAuthSettings.txt.

Test the connection to generate the OAuth settings file, then copy the OAuth settings file to your headless machine.

To connect to data via the headless machine, set these connection properties:

• InitiateOAuth (all users): REFRESH.
• OAuthSettingsLocation (all users): The path to the OAuth settings file you copied from the machine with the browser. To enable automatic refreshing of the access token, ensure that this file gives read and write permissions to the connector.
• OAuthClientId (custom OAuth only): The client Id assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).
• OAuthClientSecret (custom OAuth only): The client secret assigned when you registered your custom OAuth application (see Creating a Custom OAuth Application).

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 QuickBooks Online 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:
  

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

• For Mac:
  

  [quickbooksonline.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.quickbooksonline 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 a Custom OAuth Application

To experience fuller functionality via desktop or headless machine connections OR to connect via the web, you must create a custom OAuth application. And since custom OAuth applications seamlessly support all three commonly-used auth flows, you might want to create custom OAuth applications (use your own OAuth Application Credentials) for those auth flows anyway.

Custom OAuth applications are useful if you want to:

• Control branding of the authentication dialog.
• Control the redirect URI that the application redirects the user to after the user authenticates.
• Customize the permissions that you are requesting from the user.

Procedure

This procedure registers a new application for authenticating via OAuth 2.0, and obtains the OAuth client credentials, the OAuthClientId, and OAuthClientSecret.

1. Log into your Intuit developer account.
2. From the Menu at the top, select Dashboard.
3. Under the Apps tab, click Create an App.
4. Specify QuickBooks Online and Payments as the platform you want to develop for.
5. Provide a name for your new application.
6. Select the scopes for the APIs to be accessed.

After the application is created successfully:

1. Navigate to the Keys & OAuth tab. Under Development, locate the Client ID and Client Secret. Record these for later use.
2. Edit the application's CallbackURL property to reflect your desired Redirect URI; for example, http://localhost:33333.
   Record the Redirect URI for later use.

General Changes

Date	Version	Source	Category	Type	Description
2026-06-11	26.0.9658	QuickBooks Online	Data Model	Removed	Removed the GroupBy input from the GetReport, CreateReportSchema, CreateTransactionListReport, and CreateInventoryValuationDetailReport stored procedures. Removed support for the US region in the TaxPayment view.
2026-05-28	26.0.9644	QuickBooks Online	Data Model	Added	Added two new columns to the RecurringInvoiceTransactions table: Invoice_BillEmailCc_Address and Invoice_BillEmailBcc_Address.
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-30	26.0.9616	QuickBooks Online	Data Model	Changed	Changed the data type of the Latitude and Longitude columns from String to Integer in the Attachables and AttachmentRefs tables.
2026-04-24	26.0.9610	QuickBooks Online	Data Model	Removed	In the Customers and Vendors tables, removed the Source column. In the CompanyInfo table, removed the CompanyAddr_Lat, CompanyAddr_Long, CustomerCommunicationAddr_Lat, CustomerCommunicationAddr_Long, LegalAddr_Lat and LegalAddr_Long columns.
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-08	26.0.9594	QuickBooks Online	Security	Changed	TLS 1.3 is now supported by default for HTTP connections.
2026-01-13	25.0.9509	General		Added	Added support for the REGEXP_REPLACE() string function.
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-17	25.0.9421	QuickBooks Online		Changed	API limit for embedded credentials has been enabled, restricting users to 5,000 API calls per month. The default embedded OAuth credentials have been replaced. The driver now uses a new embedded OAuth application with updated default Client ID and Client Secret values. The previously embedded OAuth credentials are no longer used by default.
2025-10-06	25.0.9410	General		Added	Support for parsing datetime formats using ".S" and ",S" for milliseconds and nanoseconds.
2025-09-15	25.0.9389	QuickBooks Online		Added	Added the AllowDuplicateDocNumber connection property.
2025-09-15	25.0.9389	QuickBooks Online		Removed	Removed the duplicate IsProject field from the Customers table, and the duplicate SalesFormsPrefs_EstimateMessage field from the Preferences table.
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-29	25.0.9372	QuickBooks Online		Added	Added the CreateReportSchema and GetReport stored procedures.
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-16	25.0.9359	QuickBooks Online		Changed	Changed the following reports to JSON from XML: APAgingDetail, APAgingSummary, ARAgingDetail, ARAgingSummary, SheetDetail, SheetSummary, CustomerBalanceDetail, CustomerBalance, CustomerIncome, CustomerSales, ExpensesByVendor, GeneralLedgerDetail, CreateInventoryValuationDetail, InventoryValuationSummary, SalesByClass, SalesByDepartment, SalesByProduct, StatementOfCashFlow, TaxSummary, TransactionList, TransactionListWithSplits, TrialBalance, VendorBalanceDetail, VendorBalance.
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-25	25.0.9337	QuickBooks Online		Added	Added the ReimburseCharges view.
2025-07-22	25.0.9334	QuickBooks Online		Added	Added the NoRefOnly, Inactive, and CustomFields columns to the AttachableRefs table. Added the LineNum, LinkedTxnAggregate, Line_ItemBasedExpenseLineDetail_TaxInclusiveAmt, Line_ItemBasedExpenseLineDetail_MarkUpIncomeAccountRef, and Line_ItemBasedExpenseLineDetail_PriceLevelRef columns to the BillLineItems table. Added the Line_LinkedTxn_TxnLineId column to the BillPaymentLineItems table. Added the RecurDataRef and IncludeInAnnualTPAR columns to the Bills table. Added the PrivateNote, VendorRef, Memo, PrintStatus, and CheckNum columns to the CreditCardPayments table. Added the InvoiceRef, ProjectRef, PaymentMethodRef, HomeBalance, RecurDataRef, TaxExemptionRef, and Balance columns to the CreditMemos table. Added the GSTIN, BusinessNumber, GSTRegistrationType, Source, and IsProject columns to the Customers table. Added the SyncToken column to the CustomerTypes table. Added the TxnSource, RecurDataRef, and HomeTotalAmt columns to the Deposits table. Added the PrimaryPhone, CostRate, and V4IDPseudonym columns to the Employees table. Added the ProjectRef, RecurDataRef, TaxExemptionRef, FreeFormAddress, ShipAddr_Id, ShipAddr_Line1, ShipAddr_Line2, ShipAddr_Line3, ShipAddr_Line4, ShipAddr_Line5, ShipAddr_City, ShipAddr_Country, ShipAddr_CountrySubDivisionCode, ShipAddr_Lat, ShipAddr_PostalCode, and ShipAddr_Long columns to the Estimates table. Added the SyncToken, Metadata_CreateTime, and CustomField columns to the ExchangeRates table. Added the ProjectRef (MinorVersion 69), RecurDataRef, TaxExemptionRef, FreeFormAddress, and HomeBalance columns to the Invoices table. Added the ItemCategoryType, Source, AbatementRate, UQCDisplayText, UQCId, ReverseChargeRate, and ServiceType columns to the Items table. Added the TaxRateRef, GlobalTaxCalculation, RecurDataRef, and HomeTotalAmt columns to the JournalEntries table. Added the ProjectRef column to the JournalEntryLineItems table. Added the ProjectRef, TxnSource, and TaxExemptionRef columns to the Payments table. Added the ProductAndServicesPrefs_RevenueRecognitionEnabled, ProductAndServicesPrefs_RecognitionFrequencyType, AccountingInfoPrefs_TaxForm, SalesFormsPrefs_SalesEmailBcc, SalesFormsPrefs_SalesEmailCc, SalesFormsPrefs_UsingProgressInvoicing, SalesFormsPrefs_EmailCopyToCompany, SalesFormsPrefs_UsingPriceLevels, SalesFormsPrefs_AutoApplyCredit, VendorAndPurchasesPrefs_DefaultMarkupAccount, VendorAndPurchasesPrefs_DefaultTerms, VendorAndPurchasesPrefs_DefaultMarkup, VendorAndPurchasesPrefs_TPAREnabled, TaxPrefs_PartnerTaxEnabled, and TimeTrackingPrefs_UsingSalesTax columns to the Preferences table. Added the POEmail (Vendor Email attribute) and EmailStatus columns to the PurchaseOrders table. Added the LinkedTxn, TxnSource, PaymentMethodRef, IncludeInAnnualTPAR, and RecurDataRef columns to the Purchases table. Added the TxnSource, ProjectRef, RecurDataRef, and TaxExemptionRef columns to the RefundReceipts table. Added the TxnSource, ProjectRef, CreditCardPayment (object), HomeBalance, DeliveryInfo (object), RecurDataRef, and FreeFormAddress columns to the SalesReceipts table. Added the TaxAgencyConfig column to the TaxAgency table. Added the Hidden and TaxCodeConfigType columns to the TaxCodes table. Added the TxnDate column to the TaxPayment table. Added the OriginalTaxRate column to the TaxRates table. Added the BreakHours, BreakMinutes, ProjectRef, and TimeChargeId columns to the TimeActivities table. Added the RecurDataRef column to the Transfers table. Added the LinkedTxn, IncludeInAnnualTPAR, Balance, and RecurDataRef columns to the VendorCredits table. Added the APAccountRef, Source, GSTIN, T4AEligible, BusinessNumber, HasTPAR, TaxReportingBasis, CostRate, BillRate, T5018Eligible, GSTRegistrationType, VendorPaymentBankDetail, and TaxSlipType columns to the Vendors table.
2025-07-07	25.0.9319	Python		Removed	Removed the 32-bit version of Windows Python.
2025-07-07	25.0.9319	QuickBooks Online		Removed	Removed columns LinkedTxnAggregate, BillAddr_Note, and DepositToAccountRef, DepositToAccountRef_Name from CreditMemoLineItems. Removed columns BillAddr_Note, DepositToAccountRef, and DepositToAccountRef_Name from CreditMemos. Removed column ShipAddr_Note from Customers. Removed columns ClassRef, ClassRef_Name, and ApplyTaxAfterDiscount from DepositLineItems. Removed columns ClassRef, ClassRef_Name, and ApplyTaxAfterDiscount from Deposits. Removed column PrimaryAddr_Note from Employees. Removed columns BillAddr_Note, ShipAddr_Note, and Balance from EstimateLineItems. Removed columns BillAddr_Note, ShipAddr_Note, and Balance from EstimateLinkedTransactions. Removed columns BillAddr_Note, ShipAddr_Note, and Balance from Estimates. Removed columns TxnStatus, BillAddr_Note, and ShipAddr_Note from InvoiceLineItems. Removed columns TxnStatus, BillAddr_Note, and ShipAddr_Note from InvoiceLinkedTransactions. Removed columns BillAddr_Note and ShipAddr_Note from Invoices. Removed column Time from JournalCode. Removed columns TxnStatus, TxnTaxDetail_TxnTaxCodeRef, TxnTaxDetail_TotalTax, TxnTaxDetail_TaxLineAggregate, RemitToRef, RemitToRef_Name, ARAccountRef, ARAccountRef_Name, CreditCardPayment_Number, CreditCardPayment_Type, CreditCardPayment_CommercialCardCode, CreditCardPayment_CCTxnMode, CreditCardPayment_CCTxnType, and CreditCardPayment_PrevCCTransId from PaymentLineItems. Removed columns TxnStatus, TxnTaxDetail_TxnTaxCodeRef, TxnTaxDetail_TotalTax, TxnTaxDetail_TaxLineAggregate, RemitToRef, RemitToRef_Name, ARAccountRef, ARAccountRef_Name, CreditCardPayment_Number, CreditCardPayment_Type, CreditCardPayment_CommercialCardCode, CreditCardPayment_CCTxnMode, CreditCardPayment_CCTxnType, and CreditCardPayment_PrevCCTransId from Payments. Removed columns Line_ItemBasedExpenseLineDetail_RatePercent and Status from PurchaseLineItems. Removed columns VendorAddr_Note, ShipAddr_Note, and TaxCodeRef from PurchaseOrderLineItems. Removed columns VendorAddr_Note, ShipAddr_Note, and TaxCodeRef from PurchaseOrders. Removed column Status from Purchases. Removed columns BillAddr_Note, ShipAddr_Note, CreditCardPayment_CreditChargeResponse_CCTransId, CreditCardPayment_CreditChargeResponse_AuthCode, CreditCardPayment_CreditChargeResponse_TxnAuthorizationTime, SalesTermRef, SalesTermRef_Name, DueDate, ShipMethodRef, and ShipMethodRef_Name from RefundReceiptLineItems. Removed columns BillAddr_Note, ShipAddr_Note, CreditCardPayment_CreditChargeResponse_CCTransId, CreditCardPayment_CreditChargeResponse_AuthCode, CreditCardPayment_CreditChargeResponse_TxnAuthorizationTime, SalesTermRef, SalesTermRef_Name, DueDate, ShipMethodRef, and ShipMethodRef_Name from RefundReceipts. Removed columns TxnStatus, BillAddr_Note, and ShipAddr_Note from SalesReceiptLineItems. Removed columns TxnStatus, BillAddr_Note, and ShipAddr_Note from SalesReceipts. Removed columns CurrencyRef and CurrencyRef_Name from Transfers.
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-06-18	25.0.9300	QuickBooks Online		Changed	Since QuickBooks will deprecate support for minor versions 74 and earlier in the Summer of 2025, we have updated the default minor version we support to version 75 or later.
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-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.
2025-01-15	24.0.9146	QuickBooks Online		Added	Added the IncludeUnrealizedGainOrLoss attribute to the following stored procedures: CreateProfitAndLossDetailReport, CreateProfitAndLossSummaryReport, and CreateBalanceSheetSummaryReport.
2025-01-14	24.0.9145	QuickBooks Online		Added	Added the TaxClassification and TaxPayment views. Added the CreateTaxSummaryReport stored procedure.
2025-01-06	24.0.9137	QuickBooks Online		Added	Added the VoidPayment and VoidSalesReceipt stored procedures.
2024-12-27	24.0.9127	QuickBooks Online		Added	Added the ThrowMoreDataError connection property. This property throws an exception if the date range in the report exceeds the allowed range message returned by the API.
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-04	24.0.9074	QuickBooks Online		Added	Added support for the stored procedure: CreateInventoryValuationDetailReport.
2024-10-16	24.0.9055	QuickBooks Online		Added	Added access to a standard QuickBooks Online report, BalanceSheetDetail.
2024-10-04	24.0.9043	QuickBooks Online		Added	Added the DownloadNote stored procedure.
2024-07-15	24.0.8962	QuickBooks Online		Added	Added the 'Columns' input to the CreateTransactionListWithSplitsReport stored procedure.
2024-06-05	24.0.8922	Python		Added	Added support for Python 3.12.
2024-05-31	24.0.8917	QuickBooks Online		Added	Added the TransactionTypeId and AccountId columns to the report generated by the CreateJournalReport stored procedure.
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-10-26	23.0.8699	QuickBooks Online		Added	Added ReportPrefs_ReportBasis and ReportPrefs_CalcAgingReportFromTxnDate columns to Preferences table.
2023-10-09	23.0.8682	QuickBooks Online		Added	Added ArchiveMode connection property. By default, QuickBooks Online only returns non-deleted records from a SELECT query. With this property set to True, the driver returns records that are marked as deleted in addition to normal records. It's applicable for the following tables: Accounts, Customers, items, Employees, Departments, Class, and PaymentMethods.
2023-08-29	23.0.8641	Python		Added	Added support for SQLAlchemy 2.0.
2023-07-07	23.0.8588	QuickBooks Online		Added	Added a column Invoice_GroupSalesItemLineAggregate in RecurringInvoiceTransactionsLineItems table.
2023-07-07	23.0.8588	QuickBooks Online		Added	Added a column Purchase_LineId in RecurringPurchaseTransactionsLineItems table.
2023-06-20	23.0.8571	General		Added	Added the new sys_lastresultinfo system table.
2023-06-16	23.0.8567	QuickBooks Online		Added	Added a column InvoiceLink in Invoices 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-05-03	23.0.8523	QuickBooks Online		Removed	Removed India specific fields as QuickBooks Online products are no longer be available in India.
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-12-08	22.0.8377	QuickBooks Online		Added	Added the WriteToFile parameter in CreateAccountListReport, CreateAPAgingDetailReport, CreateAPAgingSummaryReport, CreateARAgingDetailReport, CreateARAgingSummaryReport, CreateBalanceSheetSummaryReport, CreateCustomerBalanceDetailReport, CreateCustomerBalanceReport, CreateCustomerIncomeReport, CreateCustomerSalesReport, CreateExpensesByVendorReport, CreateGeneralLedgerDetailReport, CreateInventoryValuationSummaryReport, CreateJournalReport, CreateProfitAndLossDetailReport, CreateProfitAndLossSummaryReport, CreateSalesByClassReport, CreateSalesByDepartmentReport, CreateSalesByProductReport, CreateStatementOfCashFlowReport, CreateTransactionListReport, CreateTransactionListWithSplitsReport, CreateTrialBalanceReport, CreateVendorBalanceDetailReport, CreateVendorBalanceReport SP. This defaults to true and must be disabled to write the schema to FileStream or FileData.
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-10-26	22.0.8334	QuickBooks Online		Added	Added FileData output attribute to print the BASE64 downloaded file content in the CreateAPAgingDetailReport, CreateAPAgingSummaryReport, CreateARAgingDetailReport, CreateARAgingSummaryReport, CreateAccountListReport, CreateBalanceSheetSummaryReport, CreateCustomerBalanceDetailReport, CreateCustomerIncomeReport, CreateCustomerSalesReport, CreateExpensesByVendorReport, CreateGeneralLedgerDetailReport, CreateInventoryValuationSummaryReport, CreateJournalReport, CreateProfitAndLossDetailReport, CreateSalesByClassReport, CreateStatementOfCashFlowReport, CreateTransactionListReport, CreateTransactionListWithSplitsReport, CreateTrialBalanceReport, CreateVendorBalanceDetailReport, CreateVendorBalanceReport schema stored procedure.
2022-10-06	22.0.8314	QuickBooks Online		Added	Added Insert support to the TaxCodes and TaxRates tables.
2022-09-30	22.0.8308	General		Changed	Added the IsPath column to the sys_procedureparameters table.
2022-09-28	22.0.8306	QuickBooks Online		Added	Added FileStream input attribute to add output streams in the CreateJournalReport, CreateProfitAndLossDetailReport, CreateSalesByClassReport, CreateStatementOfCashFlowReport, TransactionListReport, CreateTransactionListWithSplitsReport, CreateTrialBalanceReport, CreateVendorBalanceReport, CreateAccountListReport, CreateAPAgingDetailReport, CreateARAgingDetailReport, CreateBalanceSheetSummaryReport, CreateCustomerBalanceDetailReport, CreateCustomerIncomeReport, CreateCustomerSalesReport, CreateExpensesByVendorReport, CreateGeneralLedgerDetailReport, CreateInventoryValuationSummaryReport schema stored procedure.
2022-09-01	22.0.8279	QuickBooks Online		Added	Added FileStream as an input parameter to support output streams on the DownloadAttachment, and DownloadPDF stored procedures. Added Content as an input parameter to support input streams in the UploadAttachment stored procedures.
2022-08-17	22.0.8264	QuickBooks Online		Added	Added the TaxExemptionReasonId column to the Customers table.
2022-06-02	22.0.8188	QuickBooks Online		Added	Added TransactionLocationType column to BillPayments, Bills, CreditMemos, Deposits, Estimates, Invoices, JournalEntries, Payments, PurchaseOrders, Purchases, RefundReceipts, SalesReceipts, TimeActivities, Transfers and VendorCredits tables.
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-18	21.0.8143	QuickBooks Online		Added	Added the AllowOnlineACHPayment column to the Invoice table.
2022-03-18	21.0.8112	QuickBooks Online		Added	Added the tables RecurringCreditMemoTransactions, RecurringCreditMemoTransactionsLineItems, RecurringDepositTransactions, RecurringDepositTransactionsLineItems, RecurringPurchaseTransactions, RecurringPurchaseTransactionsLineItems, RecurringRefundReceiptTransactions, RecurringRefundReceiptTransactionsLineItems, RecurringSalesReceiptTransactions, RecurringSalesReceiptTransactionsLineItems, RecurringTransferTransactions, RecurringVendorCreditTransactions and RecurringVendorCreditTransactionsLineItems.
2022-01-28	21.0.8063	QuickBooks Online		Added	Added the connection property IncludeCustomFields. Set this value to true in order to retrieve custom field values.
2022-01-19	21.0.8054	QuickBooks Online		Added	Added the tables RecurringEstimateTransactions and RecurringEstimateTransactionsLineItems.
2021-12-07	21.0.8011	QuickBooks Online		Added	Added the SendInvoice stored procedure to send Linked Payment Invoices via Email.
2021-10-27	21.0.7970	QuickBooks Online		Added	Added support for Parallel pagination. This should greatly improve performance when retrieving many (tens of thousands+) of rows from a table.
2021-10-11	21.0.7954	QuickBooks Online		Added	Added the CreateTransactionListWithSplitsReport stored procedure to create customized schema files and access the Transaction list with splits report from the Quickbooks online report service.
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-07-23	21.0.7874	General		Changed	Updated the Literal Function Names for relative date/datetime functions. Previously, relative date/datetime functions resolved to a different value when used in the projection as opposed to the predicate. For example: SELECT LAST_MONTH() AS lm, Col FROM Table WHERE Col > LAST_MONTH(). Formerly, the two LAST_MONTH() methods would resolve to different datetimes. Now, they will match. As a replacement for the previous behavior, the relative date/datetime functions in the criteria may have an 'L' appended to them. For example: WHERE col > L_LAST_MONTH(). This will continue to resolve to the same values that were previously calculated in the criteria. Note that the "L_" prefix will only work in the predicate - it not available for the projection.
2021-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.
2021-01-25	20.0.7695	QuickBooks Online		Added	Added Batch update support for all the tables.
2021-01-18	20.0.7688	QuickBooks Online		Added	In the Invoice table, the AllowIPNPayment column has been removed and AllowOnlineCreditCardPayment has been added.

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

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

Executing Stored Procedures

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

Batch Processing

For information about how to modify several rows of QuickBooks Online data at once using parameterized INSERT, UPDATE, and DELETE statements, see Batch Processing.

Connecting with the cdata.quickbooksonline 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.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")

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, GivenName FROM Customers")
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, GivenName FROM Customers WHERE GivenName = ?"
params = ["Cook, Brian"]
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 Customers (Id, GivenName) VALUES (?, ?)"
params = ["Trujilo, Ana", "Hook, Captain"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

Update

The following example modifies an existing record in the table:

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

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

Calling Stored Procedures Using Execute()

When you call stored procedures by issuing EXECUTE commands, the stored procedure arguments are parameterized. For example:

cmd = "EXECUTE GetOAuthAccessToken AuthMode = ?"
params = ["APP"]
conn.execute(cmd, params)

Calling Stored Procedures Using Callproc()

When you call stored procedured by issuing the callproc() method, the stored procedure arguments are a procedure name and a list of parameters. For example:

cur = conn.cursor()
params = ["APP"]
cur.callproc("GetOAuthAccessToken", params)

This Python connector also supports writing to the data source via batch processing, using the cursor object's executemany() method. This requires both a SQL statement string and a data frame of values that act as a series of parameters for executing the SQL statement.

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 new records to the table:

cur = conn.cursor()
cmd = "INSERT INTO Customers (Id, GivenName) VALUES (?, ?)"
params = [["Trujilo, Ana", "Hook, Captain"], ["Trujilo, Ana", "Hook, Captain"]]
cur.executemany(cmd, params)
print("Records affected: ", cur.rowcount)

Update

The following example modifies existing records in the table:

cur = conn.cursor()
cmd = "UPDATE Customers SET GivenName = ? WHERE Id = ?"
params = [["Hook, Captain", "1"], ["Hook, Captain", "1"]]
cur.executemany(cmd, params)
print("Records affected: ", cur.rowcount)

Delete

The following example removes existing records from the table:

cur = conn.cursor()
cmd = "DELETE FROM Customers WHERE Id = ?"
params = [["1"], ["1"]]
cur.executemany(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 QuickBooks Online Integration Quickstarts

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

The CData Python Connector for QuickBooks Online 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 QuickBooks Online 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.

from sqlalchemy import create_engine
engine = create_engine("quickbooksonline:///?InitiateOAuth=GETANDREFRESH;")

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

from sqlalchemy import create_engine
engine = create_engine("quickbooksonline_2:///?InitiateOAuth=GETANDREFRESH;")

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

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)
Customers_table = Table("Customers", meta)
insp.reflect_table(Customers_table, ["Id","GivenName"])

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("quickbooksonline:///?InitiateOAuth=GETANDREFRESH;")
factory = sessionmaker(bind=engine)
session = factory()
for instance in session.query(Customers).filter_by(GivenName="Cook, Brian"):
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("GivenName: ", instance.GivenName)
	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:

Customers_table = Customers.metadata.tables["Customers"]
for instance in session.execute(Customers_table.select().where(Customers_table.c.GivenName == "Cook, Brian")):
	print("Id: ", instance.Id)
	print("FullName: ", instance.Name)
	print("City: ", instance.BillingCity)
	print("---------")

Implicit Joining

If mapped classes of related QuickBooks Online 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(Customers).order_by(Customers.AnnualRevenue)
for instance in rs:
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("GivenName: ", instance.GivenName)
	print("---------")

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

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

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

rs = session.execute(Customers_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(Customers.Id).label("CustomCount"), Customers.Id).group_by(Customers.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(Customers_table.select().with_only_columns([func.count(Customers_table.c.Id).label("CustomCount"), Customers_table.c.Id])group_by(Customers_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(Customers.AnnualRevenue).label("CustomSum"), Customers.Id).group_by(Customers.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(Customers_table.select().with_only_columns([func.sum(Customers_table.c.AnnualRevenue).label("CustomSum"), Customers_table.c.Id]).group_by(Customers_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(Customers.AnnualRevenue).label("CustomAvg"), Customers.Id).group_by(Customers.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(Customers_table.select().with_only_columns([func.avg(Customers_table.c.AnnualRevenue).label("CustomAvg"), Customers_table.c.Id]).group_by(Customers_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(Customers.AnnualRevenue).label("CustomMax"), func.min(Customers.AnnualRevenue).label("CustomMin"), Customers.Id).group_by(Customers.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(Customers_table.select().with_only_columns([func.max(Customers_table.c.AnnualRevenue).label("CustomMax"), func.min(Customers_table.c.AnnualRevenue).label("CustomMin"), Customers_table.c.Id]).group_by(Customers_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:

Customers_table = Customers.metadata.tables["Customers"]

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(Customers_table.insert(), {"Id": "Trujilo, Ana", "GivenName": "Hook, Captain"})

Update

The following example modifies an existing record in the table:

session.execute(Customers_table.update().where(Customers_table.c.Id == "1").values(Id="Trujilo, Ana", GivenName="Hook, Captain"))

Delete

The following example removes an existing record from the table:

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

When combined with the connector, Pandas can be used to generate data frames that contain your QuickBooks Online 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("quickbooksonline:///?InitiateOAuth=GETANDREFRESH;")

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,
	   GivenName,
     $exNumericCol;
	FROM Customers;""", 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": ["Trujilo, Ana"], "GivenName": ["Hook, Captain"]})
df.to_sql("Customers", con=engine, if_exists="append", index=False)

Matplotlib contains a number of tools that can graphically model QuickBooks Online 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 QuickBooks Online 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 QuickBooks Online, you can use the connector's connect function to create a connection using a valid QuickBooks Online connection string. If you prefer not to use a direct connection, you can use a SQLAlchemy engine.

import petl as etl
import cdata.quickbooksonline as mod
cnxn = mod.connect("InitiateOAuth=GETANDREFRESH;")

Extract, Transform, and Load the QuickBooks Online Data

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

sql = "SELECT	Id, GivenName FROM Customers "
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 QuickBooks Online tables using Petl's appenddb function.

table1 = [['Id','GivenName'],['Trujilo, Ana','Hook, Captain']]
etl.appenddb(table1,cnxn,'Customers')

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.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tables"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Views

import cdata.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")
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.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tablecolumns WHERE TableName = 'Customers'"
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.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")
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.quickbooksonline as mod
conn = mod.connect("InitiateOAuth=GETANDREFRESH;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'GetOAuthAccessToken'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

This section details a selection of advanced features of the QuickBooks Online 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 QuickBooks Online 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 QuickBooks Online 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 Customers 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.

Use Case

Sometimes, when inserting records, it's necessary to supply details about child records that have a dependency on a parent.

For example, when dealing with a CRM system, Invoices often cannot be entered without at least one line item. Since invoice line items can have several fields, this presents a unique challenge when offering the data as relational tables. When reading the data, it is easy enough to model an Invoice and an InvoiceLineItem table with a foreign key connecting the two. However, during inserts, the CRM system requires both the Invoice and the InvoiceLineItems to be created in a single submission.

To solve this sort of problem, our tools offer child collection columns on the parent. These columns can be used to submit insert statements that include details of both the parent and the child records.

For example, let's say that the Invoice table contains a single column called InvoiceLineItems. During the insert, we can pass the details of the records that must be inserted to the InvoiceLineItems table into Invoice record's InvoiceLineItems column.

The following subsection describes how this might be done.

Methods for Inserting Parent/Child Records

The connector facilitates two methods for inserting parent/child records: temporary table insertion and XML aggregate insertion.

Temporary (#TEMP) tables

The simplest way to enter data would be to use a #TEMP table, or temporary table, which the connector will store in memory.

Reference the #TEMP table with the following syntax:

TableName#TEMP

#TEMP tables are stored in memory for the duration of a connection.

Therefore, in order to use them, you cannot close the connection between submitting inserts to them, and they cannot be used in environments where a different connection may be used for each query.

Within that single connection, the table remains in memory until the bulk insert is successful, at which point the temporary table will be wiped from memory.

For example:

INSERT INTO InvoiceLineItems#TEMP (ReferenceNumber, Item, Quantity, Amount) VALUES ('INV001', 'Basketball', 10, 9.99)
INSERT INTO InvoiceLineItems#TEMP (ReferenceNumber, Item, Quantity, Amount) VALUES ('INV001', 'Football', 5, 12.99)

Once the InvoiceLineItems table is populated, the #TEMP table may be referenced during an insert into the Invoice table:

INSERT INTO Invoices (ReferenceNumber, Customer, InvoiceLines) VALUES ('INV001', 'John Doe', 'InvoiceLineItems#TEMP')

Under the hood, the connector will read in values from the #TEMP table.

Notice that the ReferenceNumber was used to identify what Invoice the lines are tied to. This is because the #TEMP table may be populated and used with a bulk insert, where there are separate lines for each invoice. This enables the #TEMP tables to be used with a bulk insert. For example:

INSERT INTO Invoices#TEMP (ReferenceNumber, Customer, InvoiceLines) VALUES ('INV001', 'John Doe', 'InvoiceLineItems#TEMP')
INSERT INTO Invoices#TEMP (ReferenceNumber, Customer, InvoiceLines) VALUES ('INV002', 'Jane Doe', 'InvoiceLineItems#TEMP')
INSERT INTO Invoices SELECT ReferenceNumber, Customer, InvoiceLines FROM Invoices#TEMP

In this case, we are inserting two different Invoices. The ReferenceNumber is how we determine which Lines go with which Invoice.

Note: The tables and columns presented here are an example of how the connector works in general. The specific table and column names may be different in the connector.

Direct XML Insertion

Direct XML can be used as an alternative to #TEMP tables. Since #TEMP tables are not used to construct them, it does not matter if you use the same connection or close the connection after insert.

For example:

[
  {
    "Item", "Basketball",
    "Quantity": 10
    "Amount": 9.99
  },
  {
    "Item", "Football",
    "Quantity": 5
    "Amount": 12.99
  }
]

OR

<Row>
  <Item>Basketball</Item>
  <Quantity>10</Quantity>
  <Amount>9.99</Amount>
</Row>
<Row>
  <Item>Football</Item>
  <Quantity>5</Quantity>
  <Amount>12.99</Amount>
</Row>

Note that the ReferenceNumber is not present in these examples because the XML, by its nature, is passed against the parent record in full per insert. Since the complete XML must be constructed and submitted for each row, there is no need to provide something to tie the child back to the parent.

Now insert the values:

INSERT INTO Invoices (ReferenceNumber, Customer, InvoiceLines) VALUES ('INV001', 'John Doe', '{...}')

OR

INSERT INTO Invoices (ReferenceNumber, Customer, InvoiceLines) VALUES ('INV001', 'John Doe', '<Row>...</Row>')

Example for QuickBooks Online

For a working example of how temp tables can be used for bulk insert in QuickBooks Online, please see the following:

// Insert into CreditMemoLineItems child table
INSERT INTO CreditMemoLineItems#TEMP (DocNumber, Line_DetailType, Line_SalesItemLineDetail_ItemRef, Line_Amount, Line_SalesItemLineDetail_Qty) VALUES ('1234001', 'SalesItemLineDetail', '2', 0.01, 1);

INSERT INTO CreditMemoLineItems#TEMP (DocNumber, Line_DetailType, Line_SalesItemLineDetail_ItemRef, Line_Amount, Line_SalesItemLineDetail_Qty) VALUES ('1234001', 'SalesItemLineDetail', '2', 0.01, 2);

INSERT INTO CreditMemoLineItems#TEMP (DocNumber, Line_DetailType, Line_SalesItemLineDetail_ItemRef, Line_Amount, Line_SalesItemLineDetail_Qty) VALUES ('1235001', 'SalesItemLineDetail', '2', 0.01, 1);

INSERT INTO CreditMemoLineItems#TEMP (DocNumber, Line_DetailType, Line_SalesItemLineDetail_ItemRef, Line_Amount, Line_SalesItemLineDetail_Qty) VALUES ('1235001', 'SalesItemLineDetail', '2', 0.01, 2)


// Insert into CreditMemos parent table
INSERT INTO CreditMemos#TEMP (DocNumber, CustomerRef, LineAggregate) values ('1234001', '5', 'CreditMemoLineItems#TEMP');

INSERT INTO CreditMemos#TEMP (DocNumber, CustomerRef, LineAggregate) values ('1235001', '6', 'CreditMemoLineItems#TEMP');


// Execute the bulk insert
INSERT INTO CreditMemos (DocNumber, CustomerRef, LineAggregate) SELECT DocNumber, CustomerRef, LineAggregate FROM CreditMemos#TEMP;

Customizing the SSL Configuration

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

To specify another certificate, see the SSLServerCert connection property.

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.

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.

If replication is enabled, the data is generated once and then copied to local and cloud data stores. With incremental updates, the connector achieves a performance advantage over dropping the cached tables and retrieving the entire table again on every refresh. With iterative updates, the connector only performs the query from the last time that the date was refreshed. If replication is not enabled, updates to the cache require downloading the entire data set.

Configuring Automatic Caching

To automatically update the cache and return results from the local cache, set the following connection string properties:

• AutoCache: This property automatically updates the cache when the value is set to true.
• CacheTolerance: This property ensures that the data retrieved from the database is the most current version. The default value is 600 seconds (10 minutes). The connector checks with the data source for newer records after the tolerance interval has expired. Otherwise, it returns the data directly from the cache.

Caching the Customers Table

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

SELECT Id, GivenName FROM Customers WHERE GivenName = 'Cook, Brian'

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 Customers WHERE GivenName = 'Cook, Brian'

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 Customers WHERE GivenName = 'Cook, Brian'
  

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 Customers#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 Customers WHERE GivenName='Cook, Brian' ORDER BY GivenName 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 QuickBooks Online 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 QuickBooks Online Query Evaluation component examines SQL queries and returns information indicating what parts of the query the connector is not capable of executing natively.

The QuickBooks Online 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 QuickBooks Online. 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 QuickBooks Online 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 QuickBooks Online 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.

GETDELETED Statements

GETDELETED statements return the Ids of deleted records. See GETDELETED Statements for a syntax reference and examples.

CACHE Statements

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

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

EXECUTE Statements

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

Names and Quoting

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

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

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

• SQL Server:
  

  SELECT DATENAME(yy,GETDATE())

• connector:
  

  SELECT DATENAME('yy',GETDATE())

String Functions

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

Date Functions

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

Math Functions

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

ASCII(character_expression)

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

• character_expression: The character expression.

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

BASE64_ENCODE(input_binary)

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

• input_binary: The binary value to encode.

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

BASE64_DECODE(input_string)

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

• input_string: The Base64-encoded string.

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

CHAR(integer_expression)

Converts the integer ASCII code to the corresponding character.

• integer_expression: The integer from 0 through 255.

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

CHARINDEX(expressionToFind ,expressionToSearch [,start_location ])

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

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

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

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

CHAR_LENGTH(character_expression),

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

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

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

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

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

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

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

CONTAINS(expressionToSearch, expressionToFind)

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

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

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

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

ENDSWITH(character_expression, character_suffix)

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

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

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

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

FILESIZE(uri)

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

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

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

FORMAT(value [, parseFormat], format )

Returns the value formatted with the specified format.

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

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

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

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

HASHBYTES(algorithm, value)

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

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

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

INDEXOF(expressionToSearch, expressionToFind [,start_location ])

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

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

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

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

ISALPHABETIC(character_expression)

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

• character_expression: The string expression to evaluate.

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

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

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

ISALPHANUMERIC(character_expression)

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

• character_expression: The string expression to evaluate.

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

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

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

ISNUMERIC(character_expression)

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

• character_expression: The string expression to evaluate.

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

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

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

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

JSON_EXTRACT(json, jsonpath)

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

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

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

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

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

LEFT ( character_expression , integer_expression )

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

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

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

LEN(string_expression)

Returns the number of characters of the specified string expression.

• string_expression: The string expression.

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

LOCATE(substring,string)

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

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

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

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

LOWER ( character_expression )

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

• character_expression: The character expression.

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

LTRIM(character_expression)

Returns the character expression with leading blanks removed.

• character_expression: The character expression.

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

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

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

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

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

NCHAR(integer_expression)

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

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

OCTET_LENGTH(character_expression),

Returns the number of bytes present in the expression.

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

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

PATINDEX(pattern, expression)

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

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

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

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

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

POSITION(expressionToFind IN expressionToSearch)

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

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

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

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

QUOTENAME(character_string [, quote_character])

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

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

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

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

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

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

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

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

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

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

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

REPLACE(string_expression, string_pattern, string_replacement)

Replaces all occurrences of a string with another string.

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

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

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

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

REPLICATE ( string_expression ,integer_expression )

Repeats the string value the specified number of times.

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

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

REVERSE ( string_expression )

Returns the reverse order of the string expression.

• string_expression: The string.

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

RIGHT ( character_expression , integer_expression )

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

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

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

RTRIM(character_expression)

Returns the character expression after it removes trailing blanks.

• character_expression: The character expression.

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

SOUNDEX(character_expression)

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

• character_expression: The alphanumeric expression of character data.

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

SPACE(repeatcount)

Returns the string that consists of repeated spaces.

• repeatcount: The number of spaces.

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

SPLIT(string, delimiter, offset)

Returns a section of the string between to delimiters.

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

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

STARTSWITH(character_expression, character_prefix)

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

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

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

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

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

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

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

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

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

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

STUFF(character_expression , integer_start , integer_length , replaceWith_expression)

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

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

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

SUBSTRING(string_value FROM start FOR length)

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

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

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

                      SELECT SUBSTRING('1234567890' FROM 3);
                      -- Result: '34567890'
                    

You can also drop the FROM and FOR clauses:

                    SELECT SUBSTRING('1234567890', 3, 2)
                    --Result: '34'
                    SELECT SUBSTRING('1234567890', 3)
                    --Result: '34567890'
                    

TEXT_ENCODE(input_string, charset)

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

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

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

TEXT_DECODE(input_binary, charset)

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

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

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

TOSTRING(string_value1)

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

• string_value1: The string to be converted.

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

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

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

TRIM(trimspec trimchar FROM string_value)

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

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

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

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

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

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

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

UNICODE(ncharacter_expression)

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

• ncharacter_expression: The Unicode character expression.

UPPER ( character_expression )

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

• character_expression: The character expression.

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

XML_EXTRACT(xml, xpath [, separator])

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

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

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

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

ABS ( numeric_expression )

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

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

                      SELECT ABS(15);
                      -- Result: 15

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

ACOS ( float_expression )

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

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

                      SELECT ACOS(0.5);
                      -- Result: 1.0471975511966
                    

ASIN ( float_expression )

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

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

                      SELECT ASIN(0.5);
                      -- Result: 0.523598775598299
                    

ATAN ( float_expression )

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

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

                      SELECT ATAN(10);
                      -- Result: 1.47112767430373
                    

ATN2 ( float_expression1 , float_expression2 )

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

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

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

CEILING ( numeric_expression ) or CEIL( numeric_expression )

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

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

                      SELECT CEILING(1.3);
                      -- Result: 2

                      SELECT CEILING(1.5);
                      -- Result: 2

                      SELECT CEILING(1.7);
                      -- Result: 2
                    

COS ( float_expression )

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

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

                      SELECT COS(1);
                      -- Result: 0.54030230586814
                    

COT ( float_expression )

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

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

                      SELECT COT(1);
                      -- Result: 0.642092615934331
                    

DEGREES ( numeric_expression )

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

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

                      SELECT DEGREES(3.1415926);
                      -- Result: 179.999996929531
                    

EXP ( float_expression )

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

• float_expression: The float expression.

                      SELECT EXP(2);
                      -- Result: 7.38905609893065
                    

EXPR ( expression )

Evaluates the expression.

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

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

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

FLOOR ( numeric_expression )

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

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

                      SELECT FLOOR(1.3);
                      -- Result: 1

                      SELECT FLOOR(1.5);
                      -- Result: 1

                      SELECT FLOOR(1.7);
                      -- Result: 1
                    

GREATEST(int1,int2,....)

Returns the greatest of the supplied integers.

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

HEX(value)

Returns a the equivalent hex for the input value.

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

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

JSON_AVG(json, jsonpath)

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

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

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

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

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

JSON_COUNT(json, jsonpath)

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

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

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

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

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

JSON_MAX(json, jsonpath)

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

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

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

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

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

JSON_MIN(json, jsonpath)

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

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

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

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

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

JSON_SUM(json, jsonpath)

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

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

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

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

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

LEAST(int1,int2,....)

Returns the least of the supplied integers.

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

LOG ( float_expression [, base ] )

Returns the natural logarithm of the specified float expression.

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

                      SELECT LOG(7.3890560);
                      -- Result: 1.99999998661119
                    

LOG10 ( float_expression )

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

• float_expression: The expression of type float.

                      SELECT LOG10(10000);
                      -- Result: 4
                    

MOD(dividend,divisor)

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

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

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

NEGATE(real_number)

Returns the opposite to the real number input.

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

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

PI ( )

Returns the constant value of pi.

                  SELECT PI()
                  -- Result: 3.14159265358979 
                

POWER ( float_expression , y )

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

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

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

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

RADIANS ( float_expression )

Returns the angle in radians of the angle in degrees.

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

                      SELECT RADIANS(180);
                      -- Result: 3.14159265358979
                    

RAND ( [ integer_seed ] )

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

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

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

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

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

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

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

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

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

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

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

SIGN ( numeric_expression )

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

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

                      SELECT SIGN(0);
                      -- Result: 0

                      SELECT SIGN(10);
                      -- Result: 1

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

SIN ( float_expression )

Returns the trigonometric sine of the angle in radians.

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

                     SELECT SIN(1);
                     -- Result: 0.841470984807897
                    

SQRT ( float_expression )

Returns the square root of the specified float value.

• float_expression: The expression of type float.

                      SELECT SQRT(100);
                      -- Result: 10
                    

SQUARE ( float_expression )

Returns the square of the specified float value.

• float_expression: The expression of type float.

                      SELECT SQUARE(10);
                      -- Result: 100

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

TAN ( float_expression )

Returns the tangent of the input expression.

• float_expression: The expression of type float.

                      SELECT TAN(1);
                      -- Result: 1.5574077246549
                    

TRUNC(decimal_number,precision)

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

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

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

_ROW_NUMBER_()

Returns a row index as an additional column.

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

CURRENT_DATE()

Returns the current date value.

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

CURRENT_TIMESTAMP()

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

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

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

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

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

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

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

DATEDIFF ( datepart , startdate , enddate )

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

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

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

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

DATE_FORMAT(date,format)

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

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

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

DATEFROMPARTS(integer_year, integer_month, integer_day)

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

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

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

DATENAME(datepart , date)

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

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

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

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

DATEPART(datepart, date [,integer_datefirst])

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

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

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

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

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

Returns the datetime value for the specified date parts.

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

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

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

Returns the datetime value for the specified date parts.

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

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

DATE_TRUNC(date, datepart)

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

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

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

DATE_TRUNC2(datepart, date, [weekday])

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

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

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

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

DAY(date)

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

• date: The datetime string that specifies the date.

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

DAYNAME(date)

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

• date: The datetime string that specifies the date.

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

DAYOFMONTH(date)

Returns the day of the month of the given date part.

• date: The datetime string that specifies the date.

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

DAYOFWEEK(date)

Returns the day of the week of the given date part.

• date: The datetime string that specifies the date.

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

DAYOFYEAR(date)

Returns the day of the year of the given date part.

• date: The datetime string that specifies the date.

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

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

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

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

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

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

EXTRACT(date_part FROM date_column_name)

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

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

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

FDWEEK(date)

Returns the first day of the week of the given date part.

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

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

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

FDMONTH(date)

Returns the first day of the month of the given date part.

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

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

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

FDQUARTER(date)

Returns the first day of the quarter of the given date part.

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

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

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

FILEMODIFIEDTIME(uri)

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

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

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

FROM_DAYS(datevalue)

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

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

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

FROM_UNIXTIME(time, issecond)

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

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

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

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

GETDATE()

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

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

GETUTCDATE()

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

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

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

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

HOUR(date)

Returns the hour component from the provided datetime.

• date: The datetime string that specifies the date.

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

ISDATE(date, [date_format])

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

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

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

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

LAST_WEEK()

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

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

LAST_MONTH()

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

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

LAST_YEAR()

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

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

LDWEEK(date)

Returns the last day of the provided week.

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

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

LDMONTH(date)

Returns the last day of the provided month.

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

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

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

LDQUARTER(date)

Returns the last day of the provided quarter.

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

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

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

MAKEDATE(year, days)

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

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

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

MINUTE(date)

Returns the minute component from the provided datetime.

• date: The datetime string that specifies the date.

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

MONTH(date)

Returns the month component from the provided datetime.

• date: The datetime string that specifies the date.

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

QUARTER(date)

Returns the quarter associated with the provided datetime.

• date: The datetime string that specifies the date.

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

SECOND(date)

Returns the second component from the provided datetime.

• date: The datetime string that specifies the date.

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

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

Returns the datetime value for the specified date and time.

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

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

STRTODATE(string,format)

Parses the provided string value and returns the corresponding datetime.

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

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

SYSDATETIME()

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

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

SYSUTCDATETIME()

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

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

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

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

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

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

TO_DAYS(date)

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

• date: The datetime string that specifies the date.

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

WEEK(date)

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

• date: The datetime string that specifies the date.

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

YEAR(date)

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

• date: The datetime string.

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

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

L_TODAY()

The current day.

  SELECT * FROM MyTable WHERE MyDateField = L_TODAY()

L_YESTERDAY()

The previous day.

  SELECT * FROM MyTable WHERE MyDateField = L_YESTERDAY()

L_TOMORROW()

The following day.

  SELECT * FROM MyTable WHERE MyDateField = L_TOMORROW()

L_LAST_WEEK()

Every day in the preceding week.

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_WEEK()

L_THIS_WEEK()

Every day in the current week.

  SELECT * FROM MyTable WHERE MyDateField = L_THIS_WEEK()

L_NEXT_WEEK()

Every day in the following week.

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_WEEK()

Also available:

• L_LAST/L_THIS/L_NEXT MONTH
• L_LAST/L_THIS/L_NEXT QUARTER
• L_LAST/L_THIS/L_NEXT YEAR

L_LAST_N_DAYS(n)

The previous n days, excluding the current day.

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_N_DAYS(3)

L_NEXT_N_DAYS(n)

The following n days, including the current day.

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_N_DAYS(3)

Also available:

• L_LAST/L_NEXT_90_DAYS

L_LAST_N_WEEKS(n)

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

  SELECT * FROM MyTable WHERE MyDateField = L_LAST_N_WEEKS(3)

L_NEXT_N_WEEKS(n)

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

  SELECT * FROM MyTable WHERE MyDateField = L_NEXT_N_WEEKS(3)

Also available:

• L_LAST/L_NEXT_N_MONTHS(n)
• L_LAST/L_NEXT_N_QUARTERS(n)
• L_LAST/L_NEXT_N_YEARS(n)

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 Customers

2. Rename a column:
   

   SELECT [GivenName] AS MY_GivenName FROM Customers

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

   SELECT CAST(AnnualRevenue AS VARCHAR) AS Str_AnnualRevenue FROM Customers

4. Search data:
   

   SELECT * FROM Customers WHERE GivenName = 'Cook, Brian'

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

   SELECT COUNT(*) AS MyCount FROM Customers 

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

   SELECT COUNT(DISTINCT GivenName) FROM Customers 

7. Return the unique items matching the query criteria:
   

   SELECT DISTINCT GivenName FROM Customers 

8. Sort a result set in ascending order:
   

   SELECT Id, GivenName FROM Customers  ORDER BY GivenName ASC

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

   SELECT Id, GivenName FROM Customers 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 Customers WHERE GivenName = @param

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

Pseudo Columns

Some input-only fields are available in SELECT statements. These fields, called pseudo columns, do not appear as regular columns in the results, yet may be specified as part of the WHERE clause. You can use pseudo columns to access additional features from QuickBooks Online.

    SELECT * FROM Customers WHERE IncludeJobs = 'TRUE'
    

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 Customers WHERE GivenName = 'Cook, Brian'

COUNT(DISTINCT)

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

SELECT COUNT(DISTINCT Id) AS DistinctValues FROM Customers WHERE GivenName = 'Cook, Brian'

AVG

Returns the average of the column values.

SELECT GivenName, AVG(AnnualRevenue) FROM Customers WHERE GivenName = 'Cook, Brian'  GROUP BY GivenName

MIN

Returns the minimum column value.

SELECT MIN(AnnualRevenue), GivenName FROM Customers WHERE GivenName = 'Cook, Brian' GROUP BY GivenName

MAX

Returns the maximum column value.

SELECT GivenName, MAX(AnnualRevenue) FROM Customers WHERE GivenName = 'Cook, Brian' GROUP BY GivenName

SUM

Returns the total sum of the column values.

SELECT SUM(AnnualRevenue) FROM Customers WHERE GivenName = 'Cook, Brian'

The CData Python Connector for QuickBooks Online 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 i.DocNumber, c.CompanyName FROM Invoices i INNER JOIN Customers c ON i.CustomerRef=c.Id

Left Join

A left join selects all rows in the FROM table and only matching rows in the JOIN table:

SELECT i.DocNumber, c.CompanyName FROM Invoices i LEFT JOIN Customers c ON i.CustomerRef=c.Id

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 Customers

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, GivenName, RANK() OVER (ORDER BY GivenName) AS Rank FROM Customers

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

SELECT Id, GivenName, RANK() OVER (PARTITION BY Id ORDER BY GivenName) AS Rank FROM Customers

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, GivenName, DENSE_RANK() OVER (PARTITION BY Id ORDER BY GivenName) AS Rank FROM Customers

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

SELECT Id, GivenName, DENSE_RANK() OVER (PARTITION BY Id ORDER BY GivenName) AS Rank FROM Customers

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 Customers (GivenName) VALUES ('Hook, Captain')

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 Customers SET GivenName='Hook, Captain' 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 Customers WHERE Id = @myId

You can issue the GETDELETED query to retrieve all records deleted from the live data for the time range specified. This query accepts a datetime value as a filter. You can also use the statement without a filter.

When used on LineItem tables or other 'child entities', GETDELETED instead returns the parent records that have been modified rather than information about deleted child records. This is a limitation of the QuickBooks Online api.

GETDELETED FROM <table_name>
GETDELETED FROM <table_name> WHERE <search_condition>


<search_condition> ::= 
  {
    <expression> { = | < | <= | > | >= } [ <expression> ] 
  } [ { AND | OR } ... ]

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>
  

Example Query:

GETDELETED FROM Customers WHERE [MetaData_LastUpdatedTime]>'2018-06-08T06:53:38-07:00'

Note: By putting a CACHE command in front of the query, you can update the cache to remove all values that have been deleted from the data source. This is shown in the query below:

CACHE GETDELETED FROM [TableName]

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 Customers

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

CACHE CachedCustomers SELECT * FROM Customers

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 CachedCustomers SELECT * FROM Customers 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 GivenName even though the cache table CachedCustomers has all the columns in Customers.

CACHE CachedCustomers SCHEMA ONLY SELECT * FROM Customers
CACHE CachedCustomers SELECT Id, GivenName FROM Customers

To execute stored procedures, you can use EXECUTE or EXEC statements.

EXEC and EXECUTE assign stored procedure inputs, referenced by name, to values or parameter names.

Stored Procedure Syntax

To execute a stored procedure as an SQL statement, use the following syntax:

 
{ EXECUTE | EXEC } <stored_proc_name> 
{
  [ @ ] <input_name> = <expression>
} [ , ... ]

<expression> ::=
  | @ <parameter> 
  | ?
  | <literal>

Example Statements

Reference stored procedure inputs by name:

EXECUTE my_proc @second = 2, @first = 1, @third = 3;

Execute a parameterized stored procedure statement:

EXECUTE my_proc second = @p1, first = @p2, third = @p3; 

PIVOT and UNPIVOT can be used to change a table-valued expression into another table.

PIVOT

PIVOT rotates a table-value expression by turning unique values from one column into multiple columns in the output. PIVOT can run aggregations where required on any column value.

PIVOT Synax

 
"SELECT 'AverageCost' AS Cost_Sorted_By_Production_Days, [0], [1], [2], [3], [4]
FROM
(
SELECT DaysToManufacture, StandardCost
FROM Production.Product
) AS SourceTable
PIVOT
(
AVG(StandardCost)
FOR DaysToManufacture IN ([0], [1], [2], [3], [4])
) AS PivotTable;"

UNPIVOT

UNPIVOT carries out nearly the opposite to PIVOT by rotating columns of a table-valued expressions into column values.

UNPIVOT Sytax

 
"SELECT VendorID, Employee, Orders
FROM
(SELECT VendorID, Emp1, Emp2, Emp3, Emp4, Emp5
FROM pvt) p
UNPIVOT
(Orders FOR Employee IN
(Emp1, Emp2, Emp3, Emp4, Emp5)
)AS unpvt;"

For further information on PIVOT and UNPIVOT, see FROM clause plus JOIN, APPLY, PIVOT (Transact-SQL)

Use INSERT INTO SELECT queries to select a list of records from one table and insert those same records into another table as a group. Inserting batches of records in this way may result in improved query performance compared to using many individual INSERT INTO queries.

The table whose records are selected for insertion into another table can be either a real table or a user-defined temporary table.

Inserting Records from Real Tables

To insert a group of records from one real, non-temporary, source table into another destination table, you can use an INSERT INTO SELECT query. This type of query is formatted similarly to a standard INSERT INTO query, except the VALUES clause is substituted with a SELECT query targeting the source table. All records matched by the embedded SELECT query are inserted into the destination table.

If the source table and destination tables have different column names, you must map columns from the source table to the corresponding columns in the destination table you want to insert them into. Perform this mapping by specifying the destination table columns in the same order as the source table columns you want to match them with. For example:

INSERT INTO DestinationTable (A,B,C,D) SELECT Q,R,S,T FROM SourceTable

In this example, the first source column (Q) is inserted into the first destination column (A), the second source column (R) is inserted into the second destination column (B), and so on.

If the source table and destination table both have the same column list with the same names, you can use a streamlined query.

INSERT INTO DestinationTableWithSameColumns SELECT * FROM SourceTable

In this example, there is no need to specify a list of columns for either the source or destination table, because their metadata already matches.

Inserting Records from Temporary Tables

You can manually define and populate temporary tables to hold a list of records for later bulk insertion.

Populate the Temporary Table

To create a temporary table, you must give it a name ending in "#TEMP" and execute an INSERT INTO query using that name, as if that table already existed in the database. After executing the first INSERT INTO, the temporary table exists and can receive subsequent INSERTs. For example:

INSERT INTO Customers#TEMP (GivenName, MyCustomField__c) VALUES ('New Customers', '9000');
INSERT INTO Customers#TEMP (GivenName, MyCustomField__c) VALUES ('New Customers 2', '9001');
INSERT INTO Customers#TEMP (GivenName, MyCustomField__c) VALUES ('New Customers 3', '9002');

This creates a temporary table called Customers#TEMP with two columns and three rows of data. Since type cannot be determined on the temporary table itself, all values are considered strings and later converted to the proper type when they are inserted together into the real (non-temporary) table of interest.

Insert Temporary Table Contents into Real Tables

Once your temporary table is populated, execute an INSERT INTO SELECT query targeting the real (non-temporary) table you want to insert the temporary table's records into. This is formatted similarly to a standard INSERT INTO query, except the VALUES clause is substituted with a SELECT query targeting the matching columns in the temporary table. For example:

INSERT INTO Customers (GivenName, MyCustomField__c) SELECT GivenName, MyCustomField__c FROM Customers#TEMP

In this example, the full contents of Customers#TEMP are inserted into the Customers.

Results

The LastResultInfo#TEMP temporary table contains details about the most recently executed query that uses the contents of a temporary table in an embedded SELECT clause, as is the case for INSERT INTO SELECT queries that use a temporary table as the source of records. This table is cleared and repopulated each time such a query is executed. LastResultInfo#TEMP includes information such as whether the query in question succeeded, and how many rows were affected by the query.

Temporary Table Lifespan

Temporary tables only last as long as the connection remains open. When the connection to QuickBooks Online is closed, all temporary tables are cleared, including the LastResultInfo#TEMP table.

To perform multiple deletes in a single request to QuickBooks Online, first use the INSERT INTO syntax to create an in-memory temporary table of data to be deleted. Once you have all of the data you want to delete added to temporary table, use DELETE FROM syntax to delete data from the live table in QuickBooks Online. This functionality is also available via the standard Batch Processing API available in JDBC.

Populate the Temporary Table

The temporary table you are populating is dynamic and is created at run time the first time you insert to it. Temporary tables are denoted by a # appearing in their name. When using a temporary table to delete, the temporary table must be named in the format [TableName]#TEMP, where TableName is the name of the table you are inserting to. For example:

INSERT INTO Customers#TEMP (Id) VALUES ('AX1000001');
INSERT INTO Customers#TEMP (Id) VALUES ('AX1000002');
INSERT INTO Customers#TEMP (Id) VALUES ('AX1000003');

This creates a temporary table called Customers#TEMP with one column and three rows of data. Since type cannot be determined on the temporary table itself, all values are stored in memory as strings. They are later converted to the proper type when they are submitted to the Customers table.

Delete from the Actual Table

Once your temporary table is populated, it is now time to insert to the actual table in QuickBooks Online. You can do this by performing a DELETE from the actual table and selecting the input data from the temporary table. For example:

DELETE FROM Customers WHERE EXISTS SELECT Id FROM Customers#TEMP

In this example, the full contents of the Customers#TEMP table are passed into the Customers table. This results in fewer requests being submitted to QuickBooks Online since multiple deletes may be submitted with each request, which is much better for performance if you have many records to delete.

Results

The results of the query are stored in the LastResultInfo#TEMP temporary table. This table is cleared and repopulated the next time data is modified by passing in a temporary table. Please be aware that the LastResultInfo#TEMP table has no predefined schema. You need to check its metadata at run time before reading data.

Temporary Table Life Span

Temporary tables only last as long as the connection remains opened. When the connection to QuickBooks Online is closed, all temporary tables are cleared, including the LastResultInfo#TEMP table.

The CData Python Connector for QuickBooks Online models data in the QuickBooks Online API as tables, views, and stored procedures. Each table, view, and stored procedure is defined in a schema file, which is a simple, text-based configuration file.

The connector uses the QuickBooks Online API to process supported filters. Filters that are not supported by the API are processed client-side within the connector.

Tables

The Tables section, which describes standard SQL tables, and the Views section, which lists read-only SQL tables, contain samples of what you might have in your QuickBooks Online account. Common tables include those that are listed below.

Table	Description
Accounts	Holds the chart of accounts in QuickBooks Online, enabling the creation, modification, deletion, and retrieval of financial account records that are used for categorizing transactions and reporting.
BalanceSheetSummaryReport	Exposes the Balance Sheet summary report from QuickBooks Online, aggregating assets, liabilities, and equity to give a snapshot of company financial health over a selected time period.
BillLineItems	Contains detailed line-item data for vendor bills, including products or services purchased, amounts, tax details, and associated accounts for expense tracking and reporting.
BillPayments	Maintains records of vendor bill payments, including payment methods, amounts, dates, and vendor details, to manage cash outflows and reconcile accounts payable.
Bills	Represents vendor bills in QuickBooks Online, enabling you to create, modify, delete, and retrieve obligations that are owed to suppliers for goods or services received.
CreditCardPayments	Displays a view of credit card payment transactions, summarizing payments made to credit card accounts for easier reconciliation and expense management.
CreditMemoLineItems	Captures line-level details of customer credit memos, including products or services credited, amounts, and tax information for accurate revenue adjustments.
CreditMemos	Maintains records of customer credit memos that are issued to adjust invoices, apply customer credits, or refund amounts for returned goods or overpayments.
CustomerBalanceDetail	Presents the Customer Balance Detail report from QuickBooks Online, showing outstanding invoices, payments, and credits per customer with running balances.
Customers	Contains all customer profiles in QuickBooks Online, enabling you to create, update, delete, and retrieve customer contact information, billing preferences, and tax settings.
EstimateLineItems	Contains line-item details for customer estimates or quotes, including products, services, quantities, prices, and tax information for potential sales.
Estimates	Stores header-level information of customer estimates or quotes, such as customer details, dates, and total amounts, supporting the sales pipeline.
InvoiceLineItems	Captures line-level details of customer invoices, including products or services sold, quantities, prices, discounts, and taxes, forming the granular data behind each invoice.
Invoices	Stores header-level information for customer invoices, including customer details, invoice dates, terms, due dates, and balances, supporting accounts-receivable tracking and reporting.
Items	Maintains the catalog of products and services that are offered by the business, including inventory and non-inventory items, used for sales, purchases, and expense tracking across QuickBooks Online.
JournalEntries	Stores journal entries that record double-entry accounting adjustments, including debits and credits applied to accounts, used for financial corrections and accruals.
PaymentLineItems	Captures the line-level allocations of customer payments, showing how each payment applies to invoices, credit memos, or other receivables.
TaxRates	Maintains sales-tax rate definitions that are applied to transactions, including jurisdiction, rate percentage, and effective dates.
Vendors	Stores vendor records including contact details, payment terms, and tax information, forming the master list of suppliers for QuickBooks Online.
VendorCredits	Represents vendor credits at the header level, used to apply credits to bills or reimburse the company for returns or overpayments.

Stored Procedures

Stored Procedures are actions that are invoked via SQL queries. They perform tasks that are beyond standard CRUD operations, including posting transactions, sending invoices, recording payments, and managing attachments in QuickBooks Online.

The connector models the data in QuickBooks Online as a list of tables in a relational database that can be queried using standard SQL statements.

CData Python Connector for QuickBooks Online Tables

Name	Description
Accounts	Holds the chart of accounts in QuickBooks Online, enabling the creation, modification, deletion, and retrieval of financial account records that are used for categorizing transactions and reporting.
AttachableRefs	Provides references linking transactions or entities to attached files or documents, helping you trace how uploaded attachments relate to bills, invoices, or other QuickBooks objects.
Attachables	Stores the actual files or metadata of attachments that are uploaded to QuickBooks Online, such as receipts, contracts, or images that support financial transactions or customer/vendor records.
BillLineItems	Contains detailed line-item data for vendor bills, including products or services purchased, amounts, tax details, and associated accounts for expense tracking and reporting.
BillLinkedTransactions	Tracks relationships between vendor bills and linked transactions, such as purchase orders or payments, allowing you to see how bills relate to other financial activities.
BillPaymentLineItems	Captures line-level details of bill payments, showing how each payment applies to one or multiple bills and reflecting discounts or credits used.
BillPayments	Maintains records of vendor bill payments, including payment methods, amounts, dates, and vendor details, to manage cash outflows and reconcile accounts payable.
Bills	Represents vendor bills in QuickBooks Online, enabling you to create, modify, delete, and retrieve obligations that are owed to suppliers for goods or services received.
BudgetDetails	Provides detailed budget line items, including amounts per account, class, or department, supporting budget-to-actual analysis within QuickBooks Online.
Budgets	Contains the header-level information of company budgets, including fiscal year, budget type, and tracking segments that are used for financial planning and analysis.
Class	Stores QuickBooks Classes that are used to categorize transactions across multiple business segments or projects, supporting more granular reporting and profit/loss tracking.
CompanyCurrency	Defines each active currency configured for a QuickBooks Online company with multicurrency enabled, including currency codes, exchange rates, and activation status as seen in the Currency Center.
CompanyInfo	Retrieves core company information such as legal name, address, industry type, fiscal year start, and contact details, which underpin company-wide settings in QuickBooks Online.
CreditMemoLineItems	Captures line-level details of customer credit memos, including products or services credited, amounts, and tax information for accurate revenue adjustments.
CreditMemos	Maintains records of customer credit memos that are issued to adjust invoices, apply customer credits, or refund amounts for returned goods or overpayments.
Customers	Contains all customer profiles in QuickBooks Online, enabling you to create, update, delete, and retrieve customer contact information, billing preferences, and tax settings.
Departments	Holds department or location records that are used to track income, expenses, and profitability by business unit or physical location.
DepositLineItems	Contains individual line items of bank deposits, detailing the source payments, amounts, and linked transactions that are consolidated into each deposit.
Deposits	Maintains bank-deposit records that show lump-sum deposits, associated line items, and account allocations for accurate bank reconciliation.
Employees	Stores employee records for payroll and HR functions, including contact details, hire dates, and status that are used in time tracking and expense reporting.
EstimateLineItems	Contains line-item details for customer estimates or quotes, including products, services, quantities, prices, and tax information for potential sales.
EstimateLinkedTransactions	Tracks how customer estimates link to other transactions such as invoices or sales orders, helping follow a deal from quote to billing.
Estimates	Stores header-level information of customer estimates or quotes, such as customer details, dates, and total amounts, supporting the sales pipeline.
ExchangeRates	Provides daily or periodic exchange rate data used by QuickBooks Online to convert multicurrency transactions into the home currency for reporting and compliance.
InventoryAdjustmentLineItems	Contains detailed line-item data for vendor bills, including products or services purchased, amounts, tax details, and associated accounts for expense tracking and reporting.
InventoryAdjustments	Represents inventory adjustments in QuickBooks Online, enabling you to create, modify, delete, and retrieve quantity adjustments for inventory items.
InvoiceLineItems	Captures line-level details of customer invoices, including products or services sold, quantities, prices, discounts, and taxes, forming the granular data behind each invoice.
InvoiceLinkedTransactions	Tracks relationships between invoices and related transactions, such as payments or sales receipts, to help trace how invoices are settled and linked within the sales process.
Invoices	Stores header-level information for customer invoices, including customer details, invoice dates, terms, due dates, and balances, supporting accounts-receivable tracking and reporting.
Items	Maintains the catalog of products and services that are offered by the business, including inventory and non-inventory items, used for sales, purchases, and expense tracking across QuickBooks Online.
JournalCode	Contains journal codes that are used for classification or statutory reporting in certain regions, enabling businesses to meet country-specific accounting requirements.
JournalEntries	Stores journal entries that record double-entry accounting adjustments, including debits and credits applied to accounts, used for financial corrections and accruals.
JournalEntryLineItems	Contains the line-level debit and credit details of each journal entry, showing how accounts are affected within a balanced accounting transaction.
PaymentLineItems	Captures the line-level allocations of customer payments, showing how each payment applies to invoices, credit memos, or other receivables.
PaymentMethods	Stores available payment-method definitions such as cash, check, credit card, or bank transfer, used when recording customer payments or vendor bill settlements.
Payments	Represents payments that are received from customers, including amount, date, payment method, and linked invoices, forming the basis for accounts-receivable settlement.
Preferences	Contains company-wide preference settings that define QuickBooks Online behavior, such as sales-form defaults, accounting methods, tax preferences, and user-access configurations.
PurchaseLineItems	Captures the line-level details of purchase transactions, including vendor items, quantities, unit costs, and expense accounts for accurate expense and cost tracking.
PurchaseOrderLineItems	Contains detailed line items for purchase orders, specifying products or services requested, quantities, expected costs, and vendor references.
PurchaseOrderLinkedTransactions	Tracks relationships between purchase orders and linked transactions, such as bills or item receipts, allowing visibility into the purchasing and fulfillment lifecycle.
PurchaseOrders	Stores header-level purchase order information, including vendor, order date, expected delivery, and total value, supporting procurement and vendor management.
Purchases	Represents general purchase transactions, including credit-card charges, checks, or cash purchases, capturing spending outside of standard vendor bills.
RecurringCreditMemoTransactions	Contains recurring transaction templates for customer credit memos, allowing automated issuance of credits to customers on a predefined schedule.
RecurringCreditMemoTransactionsLineItems	Captures line-level details of recurring credit memos, including products or services credited, amounts, and taxes applied automatically.
RecurringDepositTransactions	Stores recurring templates for deposit transactions, enabling businesses to automate repetitive deposits into bank accounts.
RecurringDepositTransactionsLineItems	Contains line-level details of recurring deposits, such as payment sources and amounts, supporting automation of regular income deposits.
RecurringEstimateTransactions	Maintains recurring estimate templates, automating the generation of customer quotes on a set schedule for recurring sales opportunities.
RecurringEstimateTransactionsLineItems	Captures the line-level details of recurring estimates, such as products, services, and pricing, ensuring consistent quote creation over time.
RecurringInvoiceTransactions	Stores recurring invoice templates that automate billing for subscriptions, retainers, or repeat sales, improving cash-flow management.
RecurringInvoiceTransactionsLineItems	Contains the line-level detail of recurring invoices, specifying products, services, amounts, and taxes that are applied each billing cycle.
RecurringJournalEntryTransactions	Holds recurring journal entry templates, enabling automated posting of routine accounting adjustments like depreciation or accruals.
RecurringJournalEntryTransactionsLineItems	Captures the debit and credit line items for recurring journal entries, ensuring accurate and consistent automated accounting adjustments.
RecurringPurchaseTransactions	Represents recurring purchase templates for expenses, allowing businesses to schedule automatic entry of regular vendor purchases.
RecurringPurchaseTransactionsLineItems	Contains the detailed line items of recurring purchase templates, including items, costs, and accounts for automated expense tracking.
RecurringRefundReceiptTransactions	Stores recurring templates for customer refund receipts, enabling businesses to automate returning funds to customers on a scheduled basis.
RecurringRefundReceiptTransactionsLineItems	Contains the line-level details of recurring refund receipts, including refunded products, services, amounts, and taxes for consistent automated processing.
RecurringSalesReceiptTransactions	Holds recurring templates for sales receipts, automating the recording of repeat customer sales that are paid at the point of sale.
RecurringSalesReceiptTransactionsLineItems	Captures line-level details of recurring sales receipts, specifying items sold, quantities, and amounts for each automated sales entry.
RecurringTransferTransactions	Maintains recurring templates for fund transfers between accounts, automating routine internal transfers within QuickBooks Online.
RecurringVendorCreditTransactions	Stores recurring templates for vendor credits, allowing automated application of credits or refunds from vendors on a scheduled basis.
RecurringVendorCreditTransactionsLineItems	Contains line-level details of recurring vendor credits, specifying items, amounts, and accounts for automated vendor-credit processing.
RefundReceiptLineItems	Captures the line-level details of customer refund receipts, including refunded items, quantities, and amounts to accurately track returns and reimbursements.
RefundReceipts	Represents customer refund receipts at the header level, including customer information, refund method, and total amount refunded.
SalesReceiptLineItems	Contains line-level details of sales receipts for immediate sales transactions, including items sold, quantities, discounts, and taxes.
SalesReceipts	Represents sales receipts at the header level, recording point-of-sale transactions where payment is received immediately.
TaxAgency	Stores tax-agency records that are used in QuickBooks Online to define the government authorities to which sales tax is remitted.
TaxCodes	Contains sales tax codes and rules that determine how taxes are calculated on transactions, supporting multi-jurisdiction compliance.
TaxRates	Maintains sales-tax rate definitions that are applied to transactions, including jurisdiction, rate percentage, and effective dates.
Terms	Stores payment terms such as Net 30 or Due on Receipt, used to define invoice due dates and early payment discounts.
TimeActivities	Contains time entry records for employees or vendors, capturing billable and non-billable hours linked to customers, projects, or payroll.
Transfers	Represents transfers of funds between bank, credit card, or other accounts, recording movement of money within the business.
VendorCreditLineItems	Captures line-level details of vendor credits, including items or expenses credited, amounts, and accounts to properly offset vendor balances.
VendorCredits	Represents vendor credits at the header level, used to apply credits to bills or reimburse the company for returns or overpayments.
Vendors	Stores vendor records including contact details, payment terms, and tax information, forming the master list of suppliers for QuickBooks Online.

Holds the chart of accounts in QuickBooks Online, enabling the creation, modification, deletion, and retrieval of financial account records that are used for categorizing transactions and reporting.

Table Specific Information

Select

All filterable columns support the following operators:

• =
• !=
• >=
• <=
• >
• <
• IN
• LIKE
• CONTAINS

The driver processes other filters client-side within the driver.

Columns

Name	Type	ReadOnly	References	Filterable	Sortable	Description
Id [KEY]	String	True		True	False	The unique identifier (Id) that is assigned to the account within QuickBooks Online. This value is required when you reference or update the account through the API.
SyncToken	String	True		False	False	The version control token for the account record. This token increments each time the account is modified, ensuring that only the most current version of the account can be updated and preventing conflicting changes from multiple applications.
MetaData_CreateTime	Datetime	True		True	True	The date and time when the account record was originally created in QuickBooks Online, reflecting the system's creation timestamp.
MetaData_LastUpdatedTime	Datetime	True		True	True	The date and time when the account record was most recently updated, allowing you to track modifications over time.
Name	String	False		True	True	The user-defined name of the account as it appears in the chart of accounts. This name must be unique and is required when you create a new account.
SubAccount	Boolean	False		True	True	Indicates whether the account is a subaccount of another account (true) or a top-level account (false or null). This field affects how balances roll up in reporting.
ParentRef	String	False	Accounts.Id	True	True	The unique Id of the parent account when this account is designated as a subaccount, used to build hierarchical account structures.
ParentRef_Name	String	True	Accounts.Name	False	False	The name of the parent account when this account is a subaccount, helping users recognize the parent-child relationship.
FullyQualifiedName	String	True		True	True	The complete hierarchical path of the account starting from the topmost parent down to this account, with each level separated by colons (for example, Parent:Account1:SubAccount1:SubAccount2).
Description	String	False		True	True	A detailed explanation of the account's purpose or usage, including notes about the types of transactions or journal entries that should be posted to it.
Active	Boolean	False		True	False	Indicates whether the account is currently active (true) or inactive (false). Inactive accounts cannot be posted to and are hidden from searches, although historical references remain.
Classification	String	False		True	False	The high-level classification of the account (such as Asset, Liability, Equity, Income, or Expense) that is used for reporting and grouping purposes. The allowed values are Asset, Equity, Expense, Liability, Revenue.
AccountType	String	False		True	False	The account type or subclassification within the classification that determines how the account is used and displayed on financial reports. The allowed values are Bank, Other Current Asset, Fixed Asset, Other Asset, Accounts Receivable, Equity, Expense, Other Expense, Cost of Goods Sold, Accounts Payable, Credit Card, Long Term Liability, Other Current Liability, Income, Other Income.
AccountSubType	String	False		True	False	The specific subtype of the account that provides an additional layer of categorization under the account type. The allowed values are CashOnHand, Checking, MoneyMarket, RentsHeldInTrust, Savings, TrustAccounts, AllowanceForBadDebts, DevelopmentCosts, EmployeeCashAdvances, OtherCurrentAssets, Inventory, Investment_MortgageRealEstateLoans, Investment_Other, Investment_TaxExemptSecurities, Investment_USGovernmentObligations, LoansToOfficers, LoansToOthers, LoansToStockholders, PrepaidExpenses, Retainage, UndepositedFunds, AccumulatedDepletion, AccumulatedDepreciation, DepletableAssets, FixedAssetComputers, FixedAssetCopiers, FixedAssetFurniture, FixedAssetPhone, FixedAssetPhotoVideo, FixedAssetSoftware, FixedAssetOtherToolsEquipment, FurnitureAndFixtures, Land, LeaseholdImprovements, OtherFixedAssets, AccumulatedAmortization, Buildings, IntangibleAssets, MachineryAndEquipment, Vehicles, LeaseBuyout, OtherLongTermAssets, SecurityDeposits, AccumulatedAmortizationOfOtherAssets, Goodwill, Licenses, OrganizationalCosts, AccountsReceivable, OpeningBalanceEquity, PartnersEquity, RetainedEarnings, AccumulatedAdjustment, OwnersEquity, PaidInCapitalOrSurplus, PartnerContributions, PartnerDistributions, PreferredStock, CommonStock, TreasuryStock, EstimatedTaxes, Healthcare, PersonalIncome, PersonalExpense, AdvertisingPromotional, BadDebts, BankCharges, CharitableContributions, CommissionsAndFees, Entertainment, EntertainmentMeals, EquipmentRental, FinanceCosts, GlobalTaxExpense, Insurance, InterestPaid, LegalProfessionalFees, OfficeExpenses, OfficeGeneralAdministrativeExpenses, OtherBusinessExpenses, OtherMiscellaneousServiceCost, PromotionalMeals, RentOrLeaseOfBuildings, RepairMaintenance, ShippingFreightDelivery, SuppliesMaterials, Travel, TravelMeals, Utilities, Auto, CostOfLabor, DuesSubscriptions, PayrollExpenses, TaxesPaid, UnappliedCashBillPaymentExpense, Depreciation, ExchangeGainOrLoss, OtherMiscellaneousExpense, PenaltiesSettlements, Amortization, GasAndFuel, HomeOffice, HomeOwnerRentalInsurance, OtherHomeOfficeExpenses, MortgageInterest, RentAndLease, RepairsAndMaintenance, ParkingAndTolls, Vehicle, VehicleInsurance, VehicleLease, VehicleLoanInterest, VehicleLoan, VehicleRegistration, VehicleRepairs, OtherVehicleExpenses, Utilities, WashAndRoadServices, EquipmentRentalCos, OtherCostsOfServiceCos, ShippingFreightDeliveryCos, SuppliesMaterialsCogs, CostOfLaborCos, AccountsPayable, CreditCard, NotesPayable, OtherLongTermLiabilities, ShareholderNotesPayable, DirectDepositPayable, LineOfCredit, LoanPayable, GlobalTaxPayable, GlobalTaxSuspense, OtherCurrentLiabilities, PayrollClearing, PayrollTaxPayable, PrepaidExpensesPayable, RentsInTrustLiability, TrustAccountsLiabilities, FederalIncomeTaxPayable, InsurancePayable, SalesTaxPayable, StateLocalIncomeTaxPayable, NonProfitIncome, OtherPrimaryIncome, SalesOfProductIncome, ServiceFeeIncome, DiscountsRefundsGiven, UnappliedCashPaymentIncome, DividendIncome, InterestEarned, OtherInvestmentIncome, OtherMiscellaneousIncome, TaxExemptInterest, PayrollWageExpenses, PayrollTaxExpenses, CashAndCashEquivalents, OtherEarMarkedBankAccounts, AssetsAvailableForSale, BalWithGovtAuthorities, CalledUpShareCapitalNotPaid, ExpenditureAuthorisationsAndLettersOfCredit, GlobalTaxDeferred, GlobalTaxRefund, InternalTransfers, OtherConsumables, ProvisionsCurrentAssets, ShortTermInvestmentsInRelatedParties, ShortTermLoansAndAdvancesToRelatedParties, TradeAndOtherReceivables, AssetsInCourseOfConstruction, CapitalWip, CumulativeDepreciationOnIntangibleAssets, IntangibleAssetsUnderDevelopment, LandAsset, NonCurrentAssets, ParticipatingInterests, ProvisionsFixedAssets, AssetsHeldForSale, AvailableForSaleFinancialAssets, DeferredTax, Investments, LongTermInvestments, LongTermLoansAndAdvancesToRelatedParties, OtherIntangibleAssets, OtherLongTermInvestments, OtherLongTermLoansAndAdvances, PrepaymentsAndAccruedIncome, ProvisionsNonCurrentAssets, AccumulatedOtherComprehensiveIncome, CalledUpShareCapital, CapitalReserves, DividendDisbursed, EquityInEarningsOfSubsiduaries, InvestmentGrants, MoneyReceivedAgainstShareWarrants, OtherFreeReserves, ShareApplicationMoneyPendingAllotment, ShareCapital, Funds, AmortizationExpense, AppropriationsToDepreciation, BorrowingCost, CommissionsAndFees, DistributionCosts, ExternalServices, ExtraordinaryCharges, IncomeTaxExpense, LossOnDiscontinuedOperationsNetOfTax, ManagementCompensation, OtherCurrentOperatingCharges, OtherExternalServices, OtherRentalCosts, OtherSellingExpenses, ProjectStudiesSurveysAssessments, PurchasesRebates, ShippingAndDeliveryExpense, StaffCosts, Sundry, TravelExpensesGeneralAndAdminExpenses, TravelExpensesSellingExpense, DeferredTaxExpense, Depletion, ExceptionalItems, ExtraordinaryItems, IncomeTaxOtherExpense, MatCredit, PriorPeriodItems, TaxRoundoffGainOrLoss, CostOfSales, FreightAndDeliveryCost, OutstandingDuesMicroSmallEnterprise, OutstandingDuesOtherThanMicroSmallEnterprise, AccrualsAndDeferredIncome, AccruedLongLermLiabilities, AccruedVacationPayable, BankLoans, DebtsRelatedToParticipatingInterests, DeferredTaxLiabilities, GovernmentAndOtherPublicAuthorities, GroupAndAssociates, LiabilitiesRelatedToAssetsHeldForSale, LongTermBorrowings, LongTermDebit, LongTermEmployeeBenefitObligations, ObligationsUnderFinanceLeases, OtherLongTermProvisions, ProvisionForLiabilities, ProvisionsNonCurrentLiabilities, StaffAndRelatedLongTermLiabilityAccounts, AccruedLiabilities, CurrentLiabilities, CurrentPortionEmployeeBenefitsObligations, CurrentPortionOfObligationsUnderFinanceLeases, CurrentTaxLiability, DividendsPayable, DutiesAndTaxes, InterestPayables, ProvisionForWarrantyObligations, ProvisionsCurrentLiabilities, ShortTermBorrowings, SocialSecurityAgencies, StaffAndRelatedLiabilityAccounts, SundryDebtorsAndCreditors, TradeAndOtherPayables, CashReceiptIncome, OperatingGrants, OtherCurrentOperatingIncome, OwnWorkCapitalized, RevenueGeneral, SalesRetail, SalesWholesale, SavingsByTaxScheme, GainLossOnSaleOfFixedAssets, GainLossOnSaleOfInvestments, LossOnDisposalOfAssets, OtherOperatingIncome, UnrealisedLossOnSecuritiesNetOfTax.
AcctNum	String	False		False	False	A user-assigned account number that uniquely identifies the account within the chart of accounts, often aligned with internal accounting policies or reporting requirements.
CurrentBalance	Decimal	True		True	True	The current monetary balance of the account. This field is available only for balance sheet accounts where a running total is maintained.
CurrentBalanceWithSubAccounts	Decimal	True		True	True	The combined current balance of the account plus all of its subaccounts, reflecting the full roll-up total in reporting.
CurrencyRef	String	False		False	False	The unique identifier of the currency in which the account is denominated, used for multicurrency transactions and reporting.
CurrencyRef_Name	String	True		False	False	The descriptive name of the currency in which the account is denominated, such as US Dollar or Euro.
TaxCodeRef	String	False	TaxCodes.Id	False	False	The unique Id of the tax code that is associated with the account. This Id links to the TaxCodes view for more details about applicable taxes (available in International versions of QuickBooks Online).

Provides references linking transactions or entities to attached files or documents, helping you trace how uploaded attachments relate to bills, invoices, or other QuickBooks objects.

Table Specific Information

Select

All filterable columns support the following operators:

• =
• !=
• >=
• <=
• >
• <
• IN
• LIKE
• CONTAINS

The driver processes other filters client-side within the driver.

Columns

Name	Type	ReadOnly	References	Filterable	Sortable	Description
EntityRefId [KEY]	String	True		True	False	The unique identifier (Id) of the entity (such as an invoice, bill, or customer record) to which the attachment is linked in QuickBooks Online.
AttachableId [KEY]	String	True	Attachables.ID	True	False	The unique Id that is assigned to the attachment itself, used to reference or update the attachable record.
SyncToken	String	True		False	False	The version control token for the attachable record. This token must be included when the record is updated or deleted to ensure that you are working with the most recent version.
MetaData_CreateTime	Datetime	True		True	True	The date and time when the attachment record was created in QuickBooks Online.
MetaData_LastUpdatedTime	Datetime	True		True	True	The date and time when the attachment record was last updated, enabling change tracking.
FileName	String	False		True	True	The name of the attached file as stored in QuickBooks Online, including its original filename if provided.
Size	Integer	False		True	True	The file size of the attachment in bytes, which can help with upload limits and storage considerations.
ContentType	String	False		True	True	The content type of the attached file (such as image/png, application/pdf) that indicates its format.
Category	String	False		True	True	The user-defined category of the attachment (for example, receipt, contract, or image) to help classify supporting documents.
Latitude	String	False		True	True	The latitude coordinate where the attachment was uploaded or noted, if location data is available.
Longitude	String	False		True	True	The longitude coordinate where the attachment was uploaded or noted, if location data is available.
Note	String	False		True	True	A free-text note stored either alongside the attachment or as a standalone comment, providing additional context or instructions.
PlaceName	String	False		True	True	The descriptive place name or location string that is associated with the upload, offering a human-readable location for the attachment.
Tag	String	False		True	True	A tag or label that is applied to the attachment to make searching and grouping easier.
AttachableRef_EntityRef	String	False		True	False	The reference value of the entity (such as an invoice Id) to which the attachment is linked, establishing the relationship between the attachment and a QuickBooks record.
AttachableRef_EntityRef_type	String	False		True	False	The type of entity that is referenced (such as Invoice, Bill, or Customer). For insert and update operations, this value is ignored when the AttachableRef_EntityRef column is null.
AttachableRef_EntityRef_name	String	False		False	False	The display name of the entity that is referenced. For insert and update operations, this value is ignored when the AttachableRef_EntityRef column is null.
AttachableRef_IncludeOnSend	Boolean	False		True	False	Indicates whether the attachment should be included when QuickBooks Online sends an email to a customer along with a transaction.
AttachableRef_LineInfo	String	False		True	False	If the entity is a transaction, this field specifies the transaction detail line (such as a specific invoice line) to which the attachment relates.
FileAccessUri	String	False		False	False	The complete Uniform Resource Identifier (URI) that can be used to access the attachment file within QuickBooks Online.
TempDownloadUri	String	False		False	False	The temporary URI that can be used by clients to directly download the attachment file without additional authentication.
AttachableRef_NoRefOnly	Boolean	False		False	False	Indicates whether to return only attachments that are not linked to any entity. This field can be combined with the AttachableRef.Inactive filter to return hidden or orphaned attachments.
AttachableRef_Inactive	Boolean	False		False	False	Indicates whether to include references to hidden entities when filtering. When this field is set to true, hidden references are included, and it works in combination with the AttachableRef.EntityRef.Type, AttachableRef.EntityRef.Value, and AttachableRef.NoRefOnly filters.
AttachableRef_CustomFieldAggregate	String	False		False	False	An XML aggregate that contains any custom field data that is associated with the attachment, enabling retrieval of extended metadata.

Stores the actual files or metadata of attachments that are uploaded to QuickBooks Online, such as receipts, contracts, or images that support financial transactions or customer/vendor records.

Table Specific Information

Select

All filterable columns support the following operators:

• =
• !=
• >=
• <=
• >
• <
• IN
• LIKE
• CONTAINS

The driver processes other filters client-side within the driver.

Columns

Name	Type	ReadOnly	References	Filterable	Sortable	Description
Id [KEY]	String	True		True	False	The unique identifier (Id) that is assigned to the attachable record. This Id is used to reference the specific attachment in QuickBooks Online transactions and API operations.
SyncToken	String	True		False	False	The version number that is assigned to the attachable entity. This value must be provided when you perform update or delete operations to ensure data consistency and prevent concurrency conflicts.
MetaData_CreateTime	Datetime	True		True	True	The date and time when the attachable record was originally created in QuickBooks Online. This timestamp helps track the origin of the attachment in audit or integration scenarios.
MetaData_LastUpdatedTime	Datetime	True		True	True	The date and time when the attachable record was last modified in QuickBooks Online. This timestamp is useful for synchronization, auditing, and identifying the most recent version of the attachment.
FileName	String	False		True	False	The name of the attached file, including its original filename as provided by the user or source system.
Size	Integer	False		True	True	The size of the attached file in bytes. This information allows applications and users to verify file size before download or processing.
ContentType	String	False		True	False	The content type of the attached file (for example, image/jpeg or application/pdf). This value informs QuickBooks Online and client applications how to handle the attachment.
Category	String	False		True	True	The category that is assigned to the attachment, indicating its functional type or purpose (for example, receipt, invoice backup, or supporting document).
Latitude	String	False		True	True	The latitude coordinate that indicates where the attachment was uploaded or associated, if location information is available. Useful for geotagging or location-based reporting.
Longitude	String	False		True	True	The longitude coordinate indicating where the attachment was uploaded or associated, if location information is available. Useful for geotagging or location-based reporting.
Note	String	False		True	False	A free-form note that is provided by the user. This note can describe the context of the attachment or stand alone as a note record that is linked to the company file.
PlaceName	String	False		True	False	The name of the place where the attachment was uploaded or associated, if provided. This name can correspond to a business location or event name.
Tag	String	False		True	False	A tag or label that is applied to the attachment to facilitate organization, filtering, or grouping of related files within QuickBooks Online.
AttachableRefAggregate	String	False		False	False	The aggregate reference that specifies the QuickBooks transaction or entity (for example, Invoice, Bill, or Customer) to which this attachable file is linked. This reference establishes the attachment's relationship within the company file.
FileAccessUri	String	False		False	False	The full path Uniform Resource Identifier (URI) that allows secure access to the attachment file in QuickBooks Online. Applications use this URI to retrieve the attachment programmatically.
TempDownloadUri	String	False		False	False	The temporary download URI that allows clients to directly download the attachment file within a limited time window. Typically, this URI is used for one-time or short-lived download operations.

Contains detailed line-item data for vendor bills, including products or services purchased, amounts, tax details, and associated accounts for expense tracking and reporting.

Table Specific Information

Bills may be inserted, updated, or queried via the Bills or BillLineItems tables. Bills may be deleted by using the Bills table.

Select

All filterable columns support the following operators:

• =
• !=
• >=
• <=
• >
• <
• IN
• LIKE
• CONTAINS

The driver processes other filters client-side within the driver.

Insert

To add a Bill, specify the Line_Amount, Line_DetailType, Line_AccountBasedExpenseLineDetail_AccountRef, VendorRef.For example, the following will insert a new Bill with two Line Items:

INSERT INTO BillLineItems (Line_Amount, Line_DetailType, Line_AccountBasedExpenseLineDetail_AccountRef, VendorRef) VALUES ('4.04', 'AccountBasedExpenseLineDetail', '7', '36')

INSERT INTO BillLineItems#TEMP (Line_Amount, Line_DetailType, Line_AccountBasedExpenseLineDetail_AccountRef, VendorRef) VALUES ('4.04', 'AccountBasedExpenseLineDetail', '7', '36')
      INSERT INTO Bills ( VendorRef, Id, DocNumber, TxnDate, PrivateNote, LineAggregate) VALUES ('36', '6704', '66', '1/1/2040', 'AccountBasedExpenseLineDetail', BillLineItems#TEMP)

Columns

Name	Type	ReadOnly	References	Filterable	Sortable	Description
LineId [KEY]	String	True		False	False	The unique identifier (Id) that is assigned to the individual line item within the bill. This links each line item to its parent bill and allows tracking of specific expenses or items.
BillId [KEY]	String	False	Bills.ID	True	False	The unique Id of the bill to which the line item belongs. This connects the line detail to its parent bill transaction.
SyncToken	String	True		False	False	The version number that is assigned to the bill object. QuickBooks Online increments this token each time the object is modified to prevent conflicting updates. You must supply the current SyncToken when you update or delete a bill to ensure data integrity.
MetaData_CreateTime	Datetime	True		True	True	The date and time when the bill record was originally created in QuickBooks Online. This timestamp is useful for auditing and synchronization processes.
MetaData_LastUpdatedTime	Datetime	True		True	True	The date and time when the bill record was last updated in QuickBooks Online. This timestamp helps track changes and identify the most recent version of the record.
DocNumber	String	False		True	True	The reference number that is associated with the bill transaction, such as a supplier invoice number or other identifying code.
TxnDate	Date	False		True	True	The date of the bill transaction. Typically, this value is the date that is entered by the user or the posting date that affects financial statements. If the date is omitted, QuickBooks Online uses the server's current date.
PrivateNote	String	False		False	False	A private, internal note attached to the bill transaction. By default, this note is not visible on printed or shared transaction records.
LinkedTxnAggregate	String	False		False	False	An XML aggregate that contains details of transactions that are linked to this bill, such as purchase orders or payments. This column allows you to see related documents connected to the bill.
Line_Id	String	False		False	False	The unique Id that is assigned to the line item itself, enabling differentiation of multiple lines within the same bill.
Line_Amount	Decimal	False		False	False	The total monetary amount of the line item, including charges and discounts but excluding taxes. This amount reflects the net amount before any tax is applied.
Line_Description	String	False		False	False	A descriptive text for the line item, such as the purpose of the expense or details of goods or services received.
Line_DetailType	String	False		False	False	The type of detail that is represented by the line item (for example, Account-based expense detail or Item-based expense detail). This column determines how QuickBooks Online processes and reports the line item.
Line_LineNum	String	False		False	False	The sequential number of the line item within the bill. This column helps preserve the order of multiple line entries.
Line_LinkedTxnAggregate	String	False		False	False	An XML aggregate of transactions linked to this specific line item, such as related purchase orders or vendor credits.
Line_AccountBasedExpenseLineDetail_ClassRef	String	False	Class.Id	False	False	The Id of the class entity that is assigned to this expense line. Classes allow tracking of expenses by category or segment in the company file.
Line_AccountBasedExpenseLineDetail_ClassRef_Name	String	True	Class.FullyQualifiedName	False	False	The name of the class entity that is assigned to this expense line. This name is the human-readable counterpart to the ClassRef Id.
Line_AccountBasedExpenseLineDetail_CustomerRef	String	False	Customers.Id	False	False	The Id of the customer that is associated with this expense line. This Id supports job costing and billable expense tracking.
Line_AccountBasedExpenseLineDetail_CustomerRef_Name	String	True	Customers.DisplayName	False	False	The name of the customer that is associated with this expense line. This name is the human-readable counterpart to the CustomerRef Id.
Line_AccountBasedExpenseLineDetail_AccountRef	String	False	Accounts.Id	False	False	The Id of the expense account to which this line item is posted in the chart of accounts.
Line_AccountBasedExpenseLineDetail_AccountRef_Name	String	True	Accounts.Name	False	False	The name of the expense account to which this line item is posted. This name is the human-readable counterpart to the AccountRef Id.
Line_AccountBasedExpenseLineDetail_TaxCodeRef	String	False	TaxCodes.Id	False	False	The sales tax code that is applied to this expense line, indicating how QuickBooks Online should calculate tax for this line item.
Line_AccountBasedExpenseLineDetail_TaxAmount	Decimal	False		False	False	The amount of sales tax that is applied to this expense line. This value shows the tax portion only, separate from the line amount.
Line_AccountBasedExpenseLineDetail_TaxInclusiveAmt	Decimal	False		False	False	The total amount of the line item, including sales tax. This amount represents the gross cost of the expense line.
Line_AccountBasedExpenseLineDetail_BillableStatus	String	False		False	False	The billable status of the expense line (for example, Billable, NotBillable). This status indicates whether the cost can be passed on to a customer. The allowed values are Billable, NotBillable, HasBeenBilled.
Line_AccountBasedExpenseLineDetail_MarkupInfo_Value	Decimal	True		False	False	The absolute markup amount added to this expense line when it is billed to a customer.
Line_AccountBasedExpenseLineDetail_MarkupInfo_Percent	Double	False		False	False	The markup rate that is applied to this expense line expressed as a percentage (for example, enter 10.0 for a 10-percent markup).
Line_AccountBasedExpenseLineDetail_MarkupInfo_PriceLevelRef	String	False		False	False	The Id of the price level entity that is used to determine markup on this expense line.
Line_ItemBasedExpenseLineDetail_ItemRef	String	False	Items.Id	False	False	The Id of the item that is associated with this expense line. This Id links the expense to a specific inventory, non-inventory, or service item in the company file.
Line_ItemBasedExpenseLineDetail_ItemRef_Name	String	True	Items.Name	False	False	The name of the item that is associated with this expense line. This is the human-readable counterpart to the ItemRef Id and helps identify the goods or services purchased.
Line_ItemBasedExpenseLineDetail_ClassRef	String	False	Class.Id	False	False	The Id of the class entity that is assigned to this item-based expense line. Classes allow tracking of expenses by category or segment in the company file.
Line_ItemBasedExpenseLineDetail_ClassRef_Name	String	True	Class.FullyQualifiedName	False	False	The name of the class entity that is assigned to this item-based expense line. This name is the human-readable counterpart to the ClassRef Id.
Line_ItemBasedExpenseLineDetail_UnitPrice	Decimal	False		False	False	The unit price of the item on this expense line as recorded in QuickBooks Online. This unit price represents the cost per single unit of the item.
Line_ItemBasedExpenseLineDetail_Qty	Double	False		False	False	The quantity of items that are recorded for this line. This number multiplied by the unit price forms the base amount before taxes and markups.
Line_ItemBasedExpenseLineDetail_CustomerRef	String	False	Customers.Id	False	False	The Id of the customer that is associated with this item-based expense line. This Id supports job costing and billable expense tracking.
Line_ItemBasedExpenseLineDetail_CustomerRef_Name	String	True	Customers.DisplayName	False	False	The name of the customer that is associated with this item-based expense line. This name is the human-readable counterpart to the CustomerRef Id.
Line_ItemBasedExpenseLineDetail_TaxCodeRef	String	False	TaxCodes.Id	False	False	The sales tax code that is applied to this item-based expense line. This code determines how QuickBooks Online calculates tax for the line.
Line_ItemBasedExpenseLineDetail_BillableStatus	String	False		False	False	The billable status of the item-based expense line (for example, Billable, NotBillable). This status indicates whether the cost can be passed on to a customer. The allowed values are Billable, NotBillable, HasBeenBill.
Line_ItemBasedExpenseLineDetail_MarkupInfo_Value	Double	True		False	False	The absolute markup amount that is added to this item-based expense line when it is billed to a customer.
Line_ItemBasedExpenseLineDetail_MarkupInfo_Percent	Double	False		False	False	The markup rate that is applied to this item-based expense line expressed as a percentage (for example, enter 10.0 for a 10 percent markup).
Line_ItemBasedExpenseLineDetail_MarkupInfo_PriceLevelRef	String	False		False	False	The Id of the price-level entity that is used to determine markup on this item-based expense line.
Line_ItemBasedExpenseLineDetail_MarkupInfo_PriceLevelRef_Name	String	True		False	False	The name of the price level that is associated with this markup. This name is the human-readable counterpart to the PriceLevelRef Id.
Line_ItemBasedExpenseLineDetail_TaxInclusiveAmt	Decimal	False		False	False	The total amount of the item-based expense line, including sales tax. This total represents the gross cost of the line.
Line_ItemBasedExpenseLineDetail_MarkUpInfo_MarkUpIncomeAccountRef	String	False		False	False	The Id of the income account in which markup revenue for this item-based expense line is recorded. This Id is found in the Id field of the referenced account object.
Line_ItemBasedExpenseLineDetail_PriceLevelRef	String	False		False	False	The Id of the price level that is referenced by this item-based expense line as found in the Id field of the referenced price-level object.
VendorRef	String	False	Vendors.Id	True	True	The Id of the vendor that is associated with the bill. This Id links the bill to the supplier providing the goods or services.
VendorRef_Name	String	True	Vendors.DisplayName	False	False	The name of the vendor that is associated with the bill. This name is the human-readable counterpart to the VendorRef Id.
APAccountRef	String	False	Accounts.Id	True	True	The Id of the accounts payable account that is used to record this bill. This Id links the bill to the appropriate liability account in the chart of accounts.
APAccountRef_Name	String	True	Accounts.Name	False	False	The name of the accounts-payable account that is used to record this bill. This account name is the human-readable counterpart to the APAccountRef Id.
TotalAmt	Decimal	False		True	True	The total monetary amount of the bill, calculated as the sum of all line items including taxes, discounts, and markups.
SalesTermRef	String	False	Terms.Id	True	True	The Id of the payment terms that are applied to this bill (for example, Net 30 or Due on Receipt). This Id determines how QuickBooks Online calculates due dates and discounts.
SalesTermRef_Name	String	True	Terms.Name	False	False	The name of the payment terms that are applied to this bill. This name is the human-readable counterpart to the SalesTermRef Id.
DueDate	Date	False		True	True	The date by which the bill must be paid according to its payment terms. This date excludes early-payment discounts or late-payment penalties.
Balance	Decimal	True		True	False	The unpaid balance of the bill at the time of retrieval. When the bill is fully paid, this value becomes zero.
DepartmentRef	String	False	Departments.Id	False	False	The Id of the department that is associated with this bill. Departments can be used to track location or division for reporting.
DepartmentRef_Name	String	True	Departments.Name	False	False	The name of the department that is associated with this bill. This name is the human-readable counterpart to the DepartmentRef Id.
TxnTaxDetail_TxnTaxCodeRef	String	False	TaxCodes.Id	False	False	The tax code that is applied at the transaction level for this bill. This tax code determines the overall tax treatment for the bill.
TxnTaxDetail_TotalTax	String	False		False	False	The total amount of tax that is calculated for the bill at the transaction level. This total excludes any tax line items that are manually inserted into the transaction.
TxnTaxDetail_TaxLineAggregate	String	False		False	False	An XML aggregate that contains the details of each tax line item that is included in this bill.
CurrencyRef	String	False		False	False	The Id of the currency that is used for this bill transaction. This Id is relevant if the multicurrency feature is enabled in the company file.
CurrencyRef_Name	String	True		False	False	The name of the currency that is used for this bill transaction. This name is the human-readable counterpart to the CurrencyRef Id.
ExchangeRate	Decimal	False		False	False	The exchange rate that is applied to convert one unit of the bill's currency into the home currency. This column is available only if the multicurrency feature is enabled and only in the UK, AU, and CA editions.
GlobalTaxCalculation	String	False		False	False	The method that is used to apply taxes to this bill (for example, TaxInclusive, TaxExcluded). This column is available only in the UK, AU, and CA editions. The allowed values are TaxExcluded, TaxInclusive, NotApplicable.

Tracks relationships between vendor bills and linked transactions, such as purchase orders or payments, allowing you to see how bills relate to other financial activities.

Columns

Name	Type	ReadOnly	References	Filterable	Sortable	Description
LinkedTxnId [KEY]	String	True		False	False	The identifier (Id) of the linked transaction line item within the bill. The Id uniquely links this transaction line to its parent bill.
BillId [KEY]	String	False	Bills.Id	True	False	The Id of the bill that is associated with the linked transaction line item. This Id connects the linked transaction to the correct bill.
SyncToken	String	True		False	False	The version number that is assigned to the bill-linked transaction object. The sync token locks the object for one application at a time, and QuickBooks Online increments it after each modification. An update or delete using an older sync token fails, ensuring that only the latest version of the object is maintained.
MetaData_CreateTime	Datetime	True		True	True	The date and time when the linked transaction record was originally created in QuickBooks Online. The CreateTime value provides a reference point for auditing and synchronization.
MetaData_LastUpdatedTime	Datetime	True		True	True	The date and time when the linked transaction record was last updated in QuickBooks Online. The LastUpdatedTime value helps track changes and identify the most recent version of the record.
DocNumber	String	False		True	True	The reference number that is associated with the transaction. This reference number allows users to match QuickBooks transactions to external documents such as vendor invoices.
TxnDate	Date	False		True	True	The date that is entered by the user for when this transaction occurred. This date determines the posting date used in reports and financial statements.
PrivateNote	String	False		False	False	A private, internal note for the transaction. The private note does not appear on printed or shared transaction records.
LinkedTxn_TxnId	String	False		False	False	The Id of the transaction that is linked to this bill. This Id provides the connection between related QuickBooks transactions such as bills, credits, or payments.
LinkedTxn_TxnType	String	False		False	False	The type of the transaction that is linked to this bill (for example, BillPayment or VendorCredit). The transaction type identifies how the linked transaction relates to the bill.
LinkedTxn_TxnLineId	String	False		False	False	The Id of the line item within the linked transaction. ThisId uniquely identifies which line from the linked transaction is connected to the bill.
LineAggregate	String	False		False	False	An XML aggregate that contains the details of all line items that are associated with the linked transaction. This column enables applications to retrieve related lines in a structured format.
VendorRef	String	False	Vendors.Id	True	True	The Id of the vendor that is associated with this linked transaction. This Id links the transaction to the supplier providing the goods or services.
VendorRef_Name	String	True	Vendors.DisplayName	False	False	The name of the vendor that is associated with this linked transaction. This name is the human-readable counterpart to the VendorRef Id.
APAccountRef	String	False	Accounts.Id	True	True	The Id of the accounts-payable account that is used for this linked transaction. This Id connects the transaction to the correct liability account in the chart of accounts.
APAccountRef_Name	String	True	Accounts.Name	False	False	The name of the accounts-payable account that is used for this linked transaction. This name is the human-readable counterpart to the APAccountRef Id.
SalesTermRef	String	False	Terms.Id	True	True	The Id of the sales-terms entity that is applied to this bill. This Id identifies the payment terms such as Net 30 or Due on Receipt.
SalesTermRef_Name	String	True	Terms.Name	False	False	The name of the sales-terms entity that is applied to this bill. This name is the human-readable counterpart to the SalesTermRef Id.
TxnTaxDetail_TxnTaxCodeRef	String	False	TaxCodes.Id	False	False	The tax code that is applied to this transaction at the transaction level. The tax code determines how QuickBooks Online calculates tax for the bill.
TxnTaxDetail_TotalTax	String	False		False	False	The total amount of tax that is calculated for the transaction, excluding any tax lines that are manually inserted into the transaction line list. This total shows the full tax impact of the transaction.
TxnTaxDetail_TaxLineAggregate	String	False		False	False	An XML aggregate containing the details of each tax line item included in this transaction. The column enables applications to retrieve related tax lines in a structured format.
DueDate	Date	False		True	False	The date by which the bill must be paid according to its payment terms. The due date excludes early-payment discount incentives and late-payment penalties. If the date is not supplied, QuickBooks Online uses the server's current date.
TotalAmt	Decimal	True		True	True	The total monetary amount of the transaction. This total includes the sum of all charges, allowances, and taxes applied to the bill.
Balance	Decimal	False		False	False	The unpaid balance of the transaction at the time of retrieval. The balance shows the remaining amount due and becomes zero when fully paid.
DepartmentRef	String	False	Departments.Id	False	False	The Id of the department that is associated with this transaction. The department stores the location or division of the transaction as defined by using location tracking in QuickBooks Online.
DepartmentRef_Name	String	True	Departments.Name	False	False	The name of the department that is associated with this transaction. This name is the human-readable counterpart to the DepartmentRef Id.
CurrencyRef	String	False		False	False	The Id of the currency that is used in this transaction. This currency reference is relevant when the multicurrency feature is enabled in the company file.
CurrencyRef_Name	String	True		False	False	The name of the currency that is used in this transaction. This name is the human-readable counterpart to the CurrencyRef Id.
ExchangeRate	Decimal	False		False	False	The exchange rate that is applied to convert one unit of the bill's currency into the home currency. The exchange rate is valid only when the multicurrency feature is enabled. In QuickBooks Online, exchange rates are recorded as the number of home currency units that are required to equal one foreign currency unit. This field is available only in the UK, AU, and CA editions.
GlobalTaxCalculation	String	False		False	False	The method that is used used to apply taxes to this transaction (for example, TaxInclusive or TaxExcluded). This field is valid only in the UK, AU, and CA editions. The allowed values are TaxExcluded, TaxInclusive, NotApplicable.