Web pivot tables by SQL DB Data Source Setup

Cube config for SQL database should have "SourceType": "sqldb" and an additional "SourceDb" section:

{
  "Id": "orders",
  "Name": "Orders from MySQL sample DB",
  "SourceType": "SqlDb",
  "SourceDb": {
    "Connector": "mysql",
    "ConnectionString": "Server=db4free.net;Database=nreco_sampledb;Uid=nreco;Pwd=HRt5UbVD;",
    "SelectSql": "SELECT o.* FROM orders o LEFT JOIN customers c ON (c.customerNumber=o.customerNumber)"
  },
  "InferSchema": true,  /* dimensions and measures are determined automatically by SELECT query resultset */
  "Dimensions": [],
  "Measures": [],
  "Parameters": []
}

"SelectSql" determines tabular data that can be used in a pivot table report.
If you don't need to perform any row-level calculations in SQL it is recommended to use SELECT * FROM ... or SELECT mainTablePrefix.* FROM ... instead of explicit list of columns - in this case microservice replaces * with columns list needed for concrete report.

Also it is much more effective to resolve lookups after grouping stage; "Star-schema support" section explains how to configure conditional post-group JOINs.

List of supported connectors:

Data Source=hostName;Database=db;User=user;Password=password;

Server=hostName;Database=db;Uid=user;Pwd=password;ConvertZeroDateTime=True;

Host=hostName;Port=port;Database=db;User ID=user;Password=password;

Compress=True;Compressor=lz4;SocketTimeout=15000;Host=hostName;Port=portNumber;Database=default;User=default;Password=

Driver=ClickHouse.Client;Compression=True;Host=hostName;Port=8123;Protocol=http;Database=default;Username=default;Password=

Data Source=@CurrentDirectory/App_Data/northwind.db;

Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostName)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=serviceName)));
User Id=user;Password=password;

account=test;user=test;password=userpwd;warehouse=wh;db=snowflake_sample_data;host=test.snowflakecomputing.com;

Driver={any odbc driver's name};OdbcKey=someValue;

NOTE: "InferSchema" is useful for one-time or for development purposes; for production use it is better to specify list of dimensions and measures explicitely to avoid some overhead and get full control over cube member options.

Dimensions

In case of SQL data source dimension name should refer to the column of the specified SQL SELECT:

  "Dimensions": [
     {
       "Name": "status",  /* or 'o.status' */
       "LabelText": "Status"
     }
  ]

It is possible to specify SQL expression to calculate dimension values on database level:

     {
       "Name": "orderDate_year",
       "LabelText": "Order Year",   
       "Params": [ "YEAR(orderDate)" ]
     }

You can use report parameters in this custom SQL (starting from v.1.8.5).

Measures

Measure parameter (if needed by the aggregator type) should refer to the column returned by "SelectSql" query:

  "Measures": [
     {
       "Type": "Count",  /* other types: "Sum", "Average", "Min", "Max", "FirstValue" */
     },
     {
       "Type": "Sum",
       "Params": [ "orderNumber" ]  /* refers to a column from SQL query. This can be an SQL expression */
     }  
  ]

Like dimensions each measure should have an unique name; if property "Name" is not specified measure name is generated automatically by its type and list of parameters. For the sample config from above suggested names will be "Count and "SumOforderNumber".

It is possible to use non-standard SQL aggregate function with "FirstValue" measure type:

  "Measures": [
     {
       "Name": "usersCountUnique
       "Type": "FirstValue",
       "Params": [ "COUNT(DISTINCT user_id)" ]  /* custom SQL */
     }  
  ]

You can use report parameters in this custom SQL (starting from v.1.8.5).

Parameters

In SQL data sources report parameters could be used in SELECT query as ADO.NET command parameters, for example:

  "Parameters": [
    {
      "Name": "country",
      "DataType": "string",
      "Multivalue": true
    }
  ]

    "SelectSql": "SELECT o.* FROM orders o LEFT JOIN customers c ON (c.customerNumber=o.customerNumber) WHERE 1=1 @country[ AND c.country IN ({0}) ]"

Token @country[ AND c.country IN ({0}) ] refers to the parameter with name "country". It works in the following way: if report parameter is empty, nothing is added to WHERE; otherwise "AND c.country IN ('Austria')" condition is added.

NOTE: Multivalue parameters should be used only with "IN" operator.

If database has star schema with main facts table and dimension tables it is possible to resolve lookup values without JOINs in the main query ("SelectSql"). Instead of that JOINs could be applied after data grouping only if they are needed for the concrete pivot table report; this is possible with "JoinsAfterGroup" config entry.

Lets assume that 'facts' table has 'company_id' column that refers to 'companies' dimension table with 'id' and 'title' columns. The following config illustrates how to configure conditional JOIN to resolve 'Company Title' dimension:

  "SourceDb": {
    "Connector": "...",
    "ConnectionString": "...",
    "SelectSql": "SELECT * FROM facts",
    "JoinsAfterGroup": [
      {
        "JoinSql": "LEFT JOIN companies c ON (c.id=t.company_id)",  /* "SelectSql" has an alias 't' */
        "ApplyOnFields": [ "c.title" ]  /* join is applied only for specfied dimension names */
      }    
    ]
  },
  "Dimensions": [
    {
      "Name": "c.title",  /* refers to join specified in "JoinsAfterGroup" */
      "LabelText": "Company Title",
      "Params": ["company_id"]  /* FK column in facts table for group-by */
    }
  ],

You can use report parameter tokens (@ParamName) in "JoinSql" template in the same manner as in "SelectSql".

It is possible to customize default database connector setup by defining custom connector type in appsettings.json config (in "PivotDataService" section):

"DbConnectors" : [
  {
    "BaseConnector": "odbc",
    "Connector": "odbc-access",
    "IdentifierFormat": "[{0}]",
    "ConnectionStringTpl": "Driver={{Microsoft Access Driver (*.mdb)}}; DBQ={0}",
    "SelectWithLimitTpl": "SELECT TOP {1} * FROM ( {0} ) as t",
    "SqlFuncTpl": {
      "Year": "YEAR({0})",
      "Month": "MONTH({0})"
      "DayOfMonth": "DAY({0})"
    }
  }
]

In this case custom connector is based on "odbc" and it defines database-specific options for Access ODBC driver.

How-to for ODBC-based connectors:

• Use Google BigQuery with ODBC driver