From 282f90792a1b589ccb285d224caf5d2d92c85e69 Mon Sep 17 00:00:00 2001 From: Pieterjan Spoelders Date: Tue, 17 Dec 2024 08:28:13 -0500 Subject: [PATCH] Start of FAQ + dev guide --- README.md | 42 +++++++++++++++-- doc/developer_guide/developer_guide.md | 64 ++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 doc/developer_guide/developer_guide.md diff --git a/README.md b/README.md index 2eacd46..0208e45 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ The main new feature is native query support. For a brief overview see the [cust ![alt text](https://github.com/EXASOL/powerbi-exasol/blob/master/screenshots/Example_Dashboard_Billion_Rows.PNG ) -## Using DSNs and Kerberos authentication +## Using DSNs, enabling ODBC logging and Kerberos authentication Please see the [user guide](doc/user_guide/user_guide.md) @@ -51,7 +51,7 @@ Please see the [user guide](doc/user_guide/user_guide.md) Custom queries using `Value.NativeQuery` are supported starting from connector version 1.1.0. An example (using the Advanced Editor): -``` +```mashup let Source = Exasol.Database("", "Yes"), CustomQuery = Value.NativeQuery( Source, "SELECT * FROM SCHEMANAME.TABLENAME") @@ -59,6 +59,8 @@ in CustomQuery ``` +General advice: Microsoft doesn’t recommend using SQL queries as the source of tables with Value.NativeQuery/[EnableFolding=true]. Turning these queries into views and referencing the views in your semantic model is probably the better move if possible. + ## How To use the Exasol Power BI Connector with the On-premises data gateway The Exasol connector was tested successfully with the On-premises data gateway version 3000.8.452 (August 2019) and also supports Direct Query. @@ -67,8 +69,42 @@ The Exasol connector was tested successfully with the On-premises data gateway v Also make sure you install the latest Exasol ODBC driver and Visual C++ Redistributable on the machine/VM where you install the data gateway, just as you would when you intend to use the connector for Power BI Desktop, for more information see section [Prerequisites](#prerequisites). +## Articles on Power BI + Exasol + +[Working with Exasol geospatial data in Power BI](https://exasol.my.site.com/s/article/Working-with-Exasol-geospatial-data-in-Power-BI?language=en_US) + +## FAQ / Frequent issues + +### "OLE DB or ODBC error: [Expression.Error] We couldn’t fold the expression to the data source. Please try a simpler expression" + +Please see: https://blog.crossjoin.co.uk/2022/05/08/understanding-the-we-couldnt-fold-the-expression-to-the-data-source-error-in-power-bi/ + +### Issues with TIMESTAMP WITH LOCAL TIME ZONE data type + +This is PowerBI specific: +Types PowerBI can't make sense of or map implicitly get ‘delivered’ as ‘Type.Binary’ in PowerBI. + +The easiest workaround in this case would be to create a view in the Exasol DB itself that contains all the columns you need and to convert this problematic ‘TIMESTAMP WITH LOCAL TIME ZONE' column to a calculated ‘TIMESTAMP' column that’s also part of the view. + +A 'TIMESTAMP’ column gets correctly read out by PowerBI. + +The SQL command to create this view and do the conversion would look like this: +```sql +CREATE VIEW YOURSCHEMA.WORKAROUNDVIEW as select … , CONVERT( TIMESTAMP , TSLTZ) AS DTCONVERTED from YOURSCHEMA.YOURTABLE; +``` +Where TSLTZ is the original ‘TIMESTAMP WITH LOCAL TIME ZONE' column and DTCONVERTED is the calculated & converted 'TIMESTAMP' column . + +You can then query this view in PowerBI without any further conversion steps needed for the new timestamp column. + +### "OLE DB or ODBC error: [Expression.Error] Local evaluation of Table.Join or Table.NestedJoin with key equality comparers is not supported" + +Usually this issue is caused by a faulty DAX expression or an unexpected value being returned by a DAX expression. + +An example: + +This issue can, for example, occur when using RLS in PowerBI. If the DAX expression for a certain role does not return a list of valid values, but instead returns a value like 'false' it might break the visuals and underlying query when filtering. ## Additional information * [Changelog](doc/changes/changelog.md) - +* [Developer guide](doc/developer_guide/developer_guide.md) diff --git a/doc/developer_guide/developer_guide.md b/doc/developer_guide/developer_guide.md new file mode 100644 index 0000000..4b93203 --- /dev/null +++ b/doc/developer_guide/developer_guide.md @@ -0,0 +1,64 @@ +# Developer guide + +## SDKs + +### PowerQuery SDK for Visual Studio 2019 + +DEPRECATED ( https://github.com/microsoft/DataConnectors) + +Please use PowerQuery SDK for Visual Studio Code instead + +### PowerQuery SDK for Visual Studio Code + +Install extension via VS code + +Repo of SDK + issues section: +https://github.com/microsoft/vscode-powerquery-sdk + +### Develop a connector using the PowerQuery SDK for Visual Studio Code + +https://learn.microsoft.com/en-us/power-query/install-sdk + +#### Building + +Select Terminal > "Run build task ..." > And then pick one of 2 options +- "Build connector project using MakePQX (newer) +- "MSBuild" (legacy) + +A .mez file will be created if all goes well. + +#### Testing + +TBC + +#### Testing changes in PowerBI locally + +You can install your newly created .mez file in: + +C:\Users\>\Documents\Power BI Desktop\Custom Connectors + +You'll also need to enable some settings in PowerBI Desktop locally: +https://learn.microsoft.com/en-us/power-bi/connect-data/desktop-connector-extensibility#custom-connectors + +If you go to Get Data > and look for Exasol you'll see 'Exasol (Custom)' if the extension's loaded correctly. + + +If you wish to run a custom version of the connector on the PowerBI service you'll also need to put the connector in place for the On-Prem Data Gateway. + +## Submission for certification + +The Connector Certification portal will be decommissioned by the end of this calendar year (https://connectorcertification.azurewebsites.net/). Effective December 16, 2024, all connector certification submissions should be made via email to dataconnectors@microsoft.com. + +## Microsoft Support + +### Official Support + +https://admin.powerplatform.microsoft.com/support + +### PowerQuery SDK board + +https://github.com/microsoft/vscode-powerquery-sdk + + + +