QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-04-19 08:04:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: 🚀 Docs V2 CI Script (#18560)

Browse Source 
* switch to v2

* promote docv2

* remove on triggers
This commit is contained in:
Hugh A. Miles II
2022-02-02 13:02:51 -08:00
committed by GitHub
parent 70969821de
commit 9c3205b573
509 changed files with 5133 additions and 93411 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/docs/miscellaneous/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Miscellaneous",
"position": 5
}

147
docs/docs/miscellaneous/chart-params.mdx Normal file
View File

@@ -0,0 +1,147 @@
---
title: Chart Parameters Reference
hide_title: true
sidebar_position: 4
version: 1
---
## Chart Parameters
Chart parameters are stored as a JSON encoded string the `slices.params` column and are often referenced throughout the code as form-data. Currently the form-data is neither versioned nor typed as thus is somewhat free-formed. Note in the future there may be merit in using something like [JSON Schema](https://json-schema.org/) to both annotate and validate the JSON object in addition to using a Mypy `TypedDict` (introduced in Python 3.8) for typing the form-data in the backend. This section serves as a potential primer for that work.
The following tables provide a non-exhausive list of the various fields which can be present in the JSON object grouped by the Explorer pane sections. These values were obtained by extracting the distinct fields from a legacy deployment consisting of tens of thousands of charts and thus some fields may be missing whilst others may be deprecated.
Note not all fields are correctly categorized. The fields vary based on visualization type and may appear in different sections depending on the type. Verified deprecated columns may indicate a missing migration and/or prior migrations which were unsuccessful and thus future work may be required to clean up the form-data.
### Datasource & Chart Type
| Field | Type | Notes |
| ----------------- | -------- | ----------------------------------- |
| `database_name` | _string_ | _Deprecated?_ |
| `datasource` | _string_ | `<datasouce_id>__<datasource_type>` |
| `datasource_id` | _string_ | _Deprecated?_ See `datasource` |
| `datasource_name` | _string_ | _Deprecated?_ |
| `datasource_type` | _string_ | _Deprecated?_ See `datasource` |
| `viz_type` | _string_ | The **Visualization Type** widget |
### Time
| Field | Type | Notes |
| ------------------- | -------- | ------------------------------------- |
| `druid_time_origin` | _string_ | The Druid **Origin** widget |
| `granularity` | _string_ | The Druid **Time Granularity** widget |
| `granularity_sqla` | _string_ | The SQLA **Time Column** widget |
| `time_grain_sqla` | _string_ | The SQLA **Time Grain** widget |
| `time_range` | _string_ | The **Time range** widget |
### GROUP BY
| Field | Type | Notes |
| ------------------------- | --------------- | ----------------- |
| `metrics` | _array(string)_ | See Query section |
| `order_asc` | - | See Query section |
| `row_limit` | - | See Query section |
| `timeseries_limit_metric` | - | See Query section |
### NOT GROUPED BY
| Field | Type | Notes |
| --------------- | --------------- | ----------------------- |
| `order_by_cols` | _array(string)_ | The **Ordering** widget |
| `row_limit` | - | See Query section |
### Y Axis 1
| Field | Type | Notes |
| --------------- | ---- | -------------------------------------------------- |
| `metric` | - | The **Left Axis Metric** widget. See Query section |
| `y_axis_format` | - | See Y Axis section |
### Y Axis 2
| Field | Type | Notes |
| ---------- | ---- | --------------------------------------------------- |
| `metric_2` | - | The **Right Axis Metric** widget. See Query section |
### Query
| Field | Type | Notes |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
| `adhoc_filters` | _array(object)_ | The **Filters** widget |
| `extra_filters` | _array(object)_ | Another pathway to the **Filters** widget.<br/>It is generally used to pass dashboard filter parameters to a chart.<br/>It can be used for appending additional filters to a chart that has been saved with its own filters on an ad-hoc basis if the chart is being used as a standalone widget.<br/><br/>For implementation examples see : [utils test.py](https://github.com/apache/superset/blob/66a4c94a1ed542e69fe6399bab4c01d4540486cf/tests/utils_tests.py#L181)<br/>For insight into how superset processes the contents of this parameter see: [exploreUtils/index.js](https://github.com/apache/superset/blob/93c7f5bb446ec6895d7702835f3157426955d5a9/superset-frontend/src/explore/exploreUtils/index.js#L159) |
| `columns` | _array(string)_ | The **Breakdowns** widget |
| `groupby` | _array(string)_ | The **Group by** or **Series** widget |
| `limit` | _number_ | The **Series Limit** widget |
| `metric`<br/>`metric_2`<br/>`metrics`<br/>`percent_mertics`<br/>`secondary_metric`<br/>`size`<br/>`x`<br/>`y` | _string_,_object_,_array(string)_,_array(object)_ | The metric(s) depending on the visualization type |
| `order_asc` | _boolean_ | The **Sort Descending** widget |
| `row_limit` | _number_ | The **Row limit** widget |
| `timeseries_limit_metric` | _object_ | The **Sort By** widget |
The `metric` (or equivalent) and `timeseries_limit_metric` fields are all composed of either metric names or the JSON representation of the `AdhocMetric` TypeScript type. The `adhoc_filters` is composed of the JSON represent of the `AdhocFilter` TypeScript type (which can comprise of columns or metrics depending on whether it is a WHERE or HAVING clause). The `all_columns`, `all_columns_x`, `columns`, `groupby`, and `order_by_cols` fields all represent column names.
### Chart Options
| Field | Type | Notes |
| -------------- | --------- | --------------------------- |
| `color_picker` | _object_ | The **Fixed Color** widget |
| `label_colors` | _object_ | The **Color Scheme** widget |
| `normalized` | _boolean_ | The **Normalized** widget |
### Y Axis
| Field | Type | Notes |
| ---------------- | -------- | ---------------------------- |
| `y_axis_2_label` | _N/A_ | _Deprecated?_ |
| `y_axis_format` | _string_ | The **Y Axis Format** widget |
| `y_axis_zero` | _N/A_ | _Deprecated?_ |
Note the `y_axis_format` is defined under various section for some charts.
### Other
| Field | Type | Notes |
| -------------- | -------- | ----- |
| `color_scheme` | _string_ | |
### Unclassified
| Field | Type | Notes |
| ----------------------------- | ----- | ----- |
| `add_to_dash` | _N/A_ | |
| `code` | _N/A_ | |
| `collapsed_fieldsets` | _N/A_ | |
| `comparison type` | _N/A_ | |
| `country_fieldtype` | _N/A_ | |
| `default_filters` | _N/A_ | |
| `entity` | _N/A_ | |
| `expanded_slices` | _N/A_ | |
| `filter_immune_slice_fields` | _N/A_ | |
| `filter_immune_slices` | _N/A_ | |
| `flt_col_0` | _N/A_ | |
| `flt_col_1` | _N/A_ | |
| `flt_eq_0` | _N/A_ | |
| `flt_eq_1` | _N/A_ | |
| `flt_op_0` | _N/A_ | |
| `flt_op_1` | _N/A_ | |
| `goto_dash` | _N/A_ | |
| `import_time` | _N/A_ | |
| `label` | _N/A_ | |
| `linear_color_scheme` | _N/A_ | |
| `new_dashboard_name` | _N/A_ | |
| `new_slice_name` | _N/A_ | |
| `num_period_compare` | _N/A_ | |
| `period_ratio_type` | _N/A_ | |
| `perm` | _N/A_ | |
| `rdo_save` | _N/A_ | |
| `refresh_frequency` | _N/A_ | |
| `remote_id` | _N/A_ | |
| `resample_fillmethod` | _N/A_ | |
| `resample_how` | _N/A_ | |
| `rose_area_proportion` | _N/A_ | |
| `save_to_dashboard_id` | _N/A_ | |
| `schema` | _N/A_ | |
| `series` | _N/A_ | |
| `show_bubbles` | _N/A_ | |
| `slice_name` | _N/A_ | |
| `timed_refresh_immune_slices` | _N/A_ | |
| `userid` | _N/A_ | |

61
docs/docs/miscellaneous/country-map-tools.mdx Normal file
View File

@@ -0,0 +1,61 @@
---
title: Country Map Tools
hide_title: true
sidebar_position: 1
version: 1
---
## The Country Map Visualization
The Country Map visualization allows you to plot lightweight choropleth maps of
your countries by province, states, or other subdivision types. It does not rely
on any third-party map services but would require you to provide the
[ISO-3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes of your country's
top-level subdivisions. Comparing to a province or state's full names, the ISO
code is less ambiguous and is unique to all regions in the world.
## Included Maps
The Country Maps visualization already ships with the maps for the following countries:
- Belgium
- Brazil
- Bulgaria
- Canada
- China
- Egypt
- France
- Germany
- India
- Iran
- Italy
- Japan
- Korea
- Liechtenstein
- Morocco
- Myanmar
- Netherlands
- Portugal
- Russia
- Singapore
- Spain
- Switzerland
- Syria
- Thailand
- Timorleste
- UK
- Ukraine
- Uruguay
- USA
- Zambia
## Adding a New Country
To add a new country to the list, you'd have to edit files in
[@superset-ui/legacy-plugin-chart-country-map](https://github.com/apache-superset/superset-ui/tree/master/plugins/legacy-plugin-chart-country-map).
1. Generate a new GeoJSON file for your country following the guide in [this Jupyter notebook](https://github.com/apache-superset/superset-ui/blob/master/plugins/legacy-plugin-chart-country-map/scripts/Country%20Map%20GeoJSON%20Generator.ipynb).
2. Edit the countries list in [legacy-plugin-chart-country-map/src/countries.js](https://github.com/apache-superset/superset-ui/blob/master/plugins/legacy-plugin-chart-country-map/src/countries.js).
3. Ping one of the Superset committers to get the `@superset-ui/legacy-plugin-chart-country-map` package published, or
publish it under another name yourself.
4. Update npm dependencies in `superset-frontend/package.json` to install the updated plugin package.

116
docs/docs/miscellaneous/importing-exporting-datasources.mdx Normal file
View File

@@ -0,0 +1,116 @@
---
title: Importing and Exporting Datasources
hide_title: true
sidebar_position: 2
version: 1
---
## Importing and Exporting Datasources
The superset cli allows you to import and export datasources from and to YAML. Datasources include
both databases and druid clusters. The data is expected to be organized in the following hierarchy:
```
├──databases
| ├──database_1
| | ├──table_1
| | | ├──columns
| | | | ├──column_1
| | | | ├──column_2
| | | | └──... (more columns)
| | | └──metrics
| | | ├──metric_1
| | | ├──metric_2
| | | └──... (more metrics)
| | └── ... (more tables)
| └── ... (more databases)
└──druid_clusters
├──cluster_1
| ├──datasource_1
| | ├──columns
| | | ├──column_1
| | | ├──column_2
| | | └──... (more columns)
| | └──metrics
| | ├──metric_1
| | ├──metric_2
| | └──... (more metrics)
| └── ... (more datasources)
└── ... (more clusters)
```
### Exporting Datasources to YAML
You can print your current datasources to stdout by running:
```
superset export_datasources
```
To save your datasources to a file run:
```
superset export_datasources -f <filename>
```
By default, default (null) values will be omitted. Use the -d flag to include them. If you want back
references to be included (e.g. a column to include the table id it belongs to) use the -b flag.
Alternatively, you can export datasources using the UI:
1. Open **Sources -> Databases** to export all tables associated to a single or multiple databases.
(**Tables** for one or more tables, **Druid Clusters** for clusters, **Druid Datasources** for
datasources)
2. Select the items you would like to export.
3. Click **Actions -> Export** to YAML
4. If you want to import an item that you exported through the UI, you will need to nest it inside
its parent element, e.g. a database needs to be nested under databases a table needs to be nested
inside a database element.
In order to obtain an **exhaustive list of all fields** you can import using the YAML import run:
```
superset export_datasource_schema
```
As a reminder, you can use the `-b` flag to include back references.
### Importing Datasources from YAML
In order to import datasources from a YAML file(s), run:
```
superset import_datasources -p <path or filename>
```
If you supply a path all files ending with **yaml** or **yml** will be parsed. You can apply
additional flags (e.g. to search the supplied path recursively):
```
superset import_datasources -p <path> -r
```
The sync flag **-s** takes parameters in order to sync the supplied elements with your file. Be
careful this can delete the contents of your meta database. Example:
```
superset import_datasources -p <path / filename> -s columns,metrics
```
This will sync all metrics and columns for all datasources found in the `<path /filename>` in the
Superset meta database. This means columns and metrics not specified in YAML will be deleted. If you
would add tables to columns,metrics those would be synchronised as well.
If you don’t supply the sync flag (**-s**) importing will only add and update (override) fields.
E.g. you can add a verbose_name to the column ds in the table random_time_series from the example
datasets by saving the following YAML to file and then running the **import_datasources** command.
```
databases:
- database_name: main
tables:
- table_name: random_time_series
columns:
- column_name: ds
verbose_name: datetime
```

334
docs/docs/miscellaneous/issue-codes.mdx Normal file
View File

@@ -0,0 +1,334 @@
---
title: Issue Codes
sidebar_position: 3
version: 1
---
# Issue Code Reference
This page lists issue codes that may be displayed in
Superset and provides additional context.
## Issue 1000
```
The datasource is too large to query.
```
It's likely your datasource has grown too large to run the current
query, and is timing out. You can resolve this by reducing the
size of your datasource or by modifying your query to only process a
subset of your data.
## Issue 1001
```
The database is under an unusual load.
```
Your query may have timed out because of unusually high load on the
database engine. You can make your query simpler, or wait until the
database is under less load and try again.
## Issue 1002
```
The database returned an unexpected error.
```
Your query failed because of an error that occurred on the database.
This may be due to a syntax error, a bug in your query, or some other
internal failure within the database. This is usually not an
issue within Superset, but instead a problem with the underlying
database that serves your query.
## Issue 1003
```
There is a syntax error in the SQL query. Perhaps there was a misspelling or a typo.
```
Your query failed because of a syntax error within the underlying query. Please
validate that all columns or tables referenced within the query exist and are spelled
correctly.
## Issue 1004
```
The column was deleted or renamed in the database.
```
Your query failed because it is referencing a column that no longer exists in
the underlying datasource. You should modify the query to reference the
replacement column, or remove this column from your query.
## Issue 1005
```
The table was deleted or renamed in the database.
```
Your query failed because it is referencing a table that no longer exists in
the underlying database. You should modify your query to reference the correct
table.
## Issue 1006
```
One or more parameters specified in the query are missing.
```
Your query was not submitted to the database because it's missing one or more
parameters. You should define all the parameters referenced in the query in a
valid JSON document. Check that the parameters are spelled correctly and that
the document has a valid syntax.
## Issue 1007
```
The hostname provided can't be resolved.
```
The hostname provided when adding a new database is invalid and cannot be
resolved. Please check that there are no typos in the hostname.
## Issue 1008
```
The port is closed.
```
The port provided when adding a new database is not open. Please check that
the port number is correct, and that the database is running and listening on
that port.
## Issue 1009
```
The host might be down, and cannot be reached on the provided port.
```
The host provided when adding a new database doesn't seem to be up.
Additionally, it cannot be reached on the provided port. Please check that
there are no firewall rules preventing access to the host.
## Issue 1010
```
Superset encountered an error while running a command.
```
Something unexpected happened, and Superset encountered an error while
running a command. Please reach out to your administrator.
## Issue 1011
```
Superset encountered an unexpected error.
```
Something unexpected happened in the Superset backend. Please reach out
to your administrator.
## Issue 1012
```
The username provided when connecting to a database is not valid.
```
The user provided a username that doesn't exist in the database. Please check
that the username is typed correctly and exists in the database.
## Issue 1013
```
The password provided when connecting to a database is not valid.
```
The user provided a password that is incorrect. Please check that the
password is typed correctly.
## Issue 1014
```
Either the username or the password used are incorrect.
```
Either the username provided does not exist or the password was written incorrectly. Please
check that the username and password were typed correctly.
## Issue 1015
```
Either the database is spelled incorrectly or does not exist.
```
Either the database was written incorrectly or it does not exist. Check that it was typed correctly.
## Issue 1016
```
The schema was deleted or renamed in the database.
```
The schema was either removed or renamed. Check that the schema is typed correctly and exists.
## Issue 1017
```
The user doesn't have the proper permissions to connect to the database
```
We were unable to connect to your database. Please confirm that your service account has the Viewer and Job User roles on the project.
## Issue 1018
```
One or more parameters needed to configure a database are missing.
```
Not all parameters required to test, create, or edit a database were present. Please double check which parameters are needed, and that they are present.
## Issue 1019
```
The submitted payload has the incorrect format.
```
Please check that the request payload has the correct format (eg, JSON).
## Issue 1020
```
The submitted payload has the incorrect schema.
```
Please check that the request payload has the expected schema.
## Issue 1021
```
Results backend needed for asynchronous queries is not configured.
```
Your instance of Superset doesn't have a results backend configured, which is needed for asynchronous queries. Please contact an administrator for further assistance.
## Issue 1022
```
Database does not allow data manipulation.
```
Only `SELECT` statements are allowed against this database. Please contact an administrator if you need to run DML (data manipulation language) on this database.
## Issue 1023
```
CTAS (create table as select) doesn't have a SELECT statement at the end.
```
The last statement in a query run as CTAS (create table as select) MUST be a SELECT statement. Please make sure the last statement in the query is a SELECT.
## Issue 1024
```
CVAS (create view as select) query has more than one statement.
```
When running a CVAS (create view as select) the query should have a single statement. Please make sure the query has a single statement, and no extra semi-colons other than the last one.
## Issue 1025
```
CVAS (create view as select) query is not a SELECT statement.
```
When running a CVAS (create view as select) the query should be a SELECT statement. Please make sure the query has a single statement and it's a SELECT statement.
## Issue 1026
```
Query is too complex and takes too long to run.
```
The submitted query might be too complex to run under the time limit defined by your Superset administrator. Please double check your query and verify if it can be optimized. Alternatively, contact your administrator to increase the timeout period.
## Issue 1027
```
The database is currently running too many queries.
```
The database might be under heavy load, running too many queries. Please try again later, or contact an administrator for further assistance.
## Issue 1028
```
One or more parameters specified in the query are malformatted.
```
The query contains one or more malformed template parameters. Please check your query and confirm that all template parameters are surround by double braces, for example, "{{ ds }}". Then, try running your query again.
## Issue 1029
```
The object does not exist in this database.
```
Either the schema, column, or table do not exist in the database.
## Issue 1030
```
The query potentially has a syntax error.
```
The query might have a syntax error. Please check and run again.
## Issue 1031
```
The results backend no longer has the data from the query.
```
The results from the query might have been deleted from the results backend after some period. Please re-run your query.
## Issue 1032
```
The query associated with the results was deleted.
```
The query associated with the stored results no longer exists. Please re-run your query.
## Issue 1033
```
The results stored in the backend were stored in a different format, and no longer can be deserialized.
```
The query results were stored in a format that is no longer supported. Please re-run your query.
## Issue 1034
```
The database port provided is invalid.
```
Please check that the provided database port is an integer between 0 and 65535 (inclusive).
## Issue 1035
```
Failed to start remote query on a worker.
```
The query was not started by an asynchronous worker. Please reach out to your administrator for further assistance.
## Issue 1036
```
The database was deleted.
```
The operation failed because the database referenced no longer exists. Please reach out to your administrator for further assistance.