Conversation
|
@bmtcril - added superset-extra-assets docs if you could take a look again |
| # analyses/ dbt_project.yml macros/ models/ README.md seeds/ snapshots/ tests/ | ||
|
|
||
| .. code-block:: yaml | ||
| * ``dbt_project.yml`` should have the same `profile name <https://github.com/openedx/sample-aspects-dbt/blob/main/dbt_project.yml#L8-L9>`_ as your local profiles file |
There was a problem hiding this comment.
It's safer to link to a specific hash of this file rather than the main blob, if you're calling out line numbers, in case this file changes
|
|
||
| .. code-block:: yaml | ||
| # directory which will store compiled SQL files | ||
| target-path: "target" |
There was a problem hiding this comment.
[curious] is "target" the literal value someone should use, or is it a placeholder they should fill with their own information?
There was a problem hiding this comment.
its the literal value, though i see how that could be confusing. i can add a link to the line above to show that it should be literally 'target'
There was a problem hiding this comment.
Yeah I think that would be helpful!
| Before adding your custom transforms, it's a good idea to test that your dbt package can connect to the Clickhouse database and run the base transforms from aspects-dbt. | ||
|
|
||
| #. Run ``dbt debug`` to test the connection to your database and the validity of your dbt project. | ||
| #. You might need to run ``dbt deps`` to install the dependencies for your package. |
There was a problem hiding this comment.
How would I know if this step is needed?
There was a problem hiding this comment.
good call - it will say 'run dbt deps to update blah blah' but ill make that clearer
| can be used to guard against data edge cases and regressions from future code changes. | ||
| Data tests | ||
| ------------ | ||
| Data tests can be defined in the `schema.yml <https://github.com/openedx/sample-aspects-dbt/blob/main/models/enrollment/schema.yml#L18-L20>`_ file for each model, and are used to validate properties of the data such as types, accepted values, uniqueness, and relationships between tables. |
There was a problem hiding this comment.
Here's another place where it's safer to point at a hash if you're going to call out specific lines
| * This command does several things to make import safer and easier, including checking for some required security fields, safely naming files so that charts with duplicate names don't overwrite each other, and checking that certain fields use Tutor settings instead of hard coded values. It also adds a special ``_file_name`` key that tells Aspects what name to use for the file when importing back to Superset. | ||
|
|
||
| tutor aspects import_superset_zip <path to>/<your dashboard>.zip --base_assets_path <path to>/<your extension>/templates/<your extension>/superset-assets/ | ||
| #. Before importing a dashboard back into Superset, you will need to manually add a `_roles <https://github.com/openedx/tutor-contrib-aspects-sample/blob/main/tutoraspects_sample/templates/aspects-sample/build/assets/dashboards/Sample_Aspects_Plugin.yaml#L2-L3>`_ key, which sets the permissions for who can view the dashboard. |
There was a problem hiding this comment.
Another pointing-at-main-blob-with-line-numbers
There was a problem hiding this comment.
I wonder if it would be cleaner for any of these mentions to just code-block in the 1-2 lines of yaml you're referencing?
There was a problem hiding this comment.
yeah i did think of that, but i was thinking it would be better to show where the code is in addition to what it is. i could probably do both
There was a problem hiding this comment.
Yeah, that makes a lot of sense. One thing you could do is just link to the file (sans line numbers ... I have encountered documentation that points at specific lines, the file has changed, and I'm deeply confused) and then pull out the relevant lines in a code block. It might be like,
add a (link)roles key(/link) that will look something like:
(code block)
| are only ones you have created yourself unless you truly intend to overwrite defaults. | ||
| When a Superset zip is exported it will contain any datasets and databases needed for all of the charts in that dashboard. This may include the default xapi and MySQL databases or Aspects datasets that you probably do not want to overwrite, and can include their passwords! | ||
|
|
||
| Use caution when importing datasets or databases in your project and make sure that they are only ones you have created yourself unless you truly intend to overwrite defaults. |
There was a problem hiding this comment.
Is this a destructive action or can you come back from this?
There was a problem hiding this comment.
you can fix it by re-importing the released aspects files, just a pain
There was a problem hiding this comment.
Is it worth mentioning that, or linking to recovery steps? Or will operators generally understand that at this point?
| Once you have your files imported to the plugin, make sure it is installed and enabled | ||
| in your Tutor environment, then you should just be able to do ``tutor config save`` and | ||
| ``tutor <local|dev|k8s> import-assets`` to update your Superset assets. | ||
| Once you have your files imported to the plugin, make sure it is installed and enabled in your Tutor environment, then run ``tutor config save`` and ``tutor <local|dev|k8s> import-assets`` to update your Superset assets. |
There was a problem hiding this comment.
[suggestion] link back to the installation/enablement part of the docs
Co-authored-by: Sarina Canelake <sarina@axim.org>
|
@sarina can you please take another look? the last couple commits were just me reorganizing and updating some titles |
3 participants
Updating documentation for new sample dbt extension package
Clarifying In Context metrics instructions & some article title updates
Part of #91
https://docsopenedxorg--338.org.readthedocs.build/projects/openedx-aspects/en/338/technical_documentation/how-tos/dbt_extensions.html