Skip to content

Commit d7aff94

Browse files
jbatjbat
authored
Merge pull request #26 from rdytech/NEP-17997-add-duplicate-dashboard-doc
NEP-17997 add dup dashboard doc
2 parents 938fbc6 + 2e2700d commit d7aff94

File tree

6 files changed

+356
-96
lines changed

6 files changed

+356
-96
lines changed

‎README.md‎

Lines changed: 108 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -2,70 +2,132 @@
22

33
[![Build status](https://badge.buildkite.com/fc7ee4a03e119a5d859472865fc0bdc9a6e46d51b7f5b8cd62.svg)](https://buildkite.com/jobready/superset-client)
44

5-
The Repo is `superset-client` with the gem named `superset`
5+
The Repo is `superset-client` with the ruby gem named `superset`
66

77
All ruby classes are namespaced under `Superset::`
88

9-
## Installation
9+
# Installation
10+
11+
## Docker Setup
12+
13+
Build, bundle and open a ruby console
1014

11-
Add to your Gemfile
1215
```
13-
gem 'superset'
16+
docker-compose build
17+
docker-compose run --rm app bundle install
18+
docker-compose run --rm app bin/console
1419
```
1520

16-
And then execute:
21+
Run specs
22+
23+
```
24+
docker-compose run --rm app rspec
25+
# or
26+
docker-compose run --rm app bash # then run 'bundle exec rspec' from the container.
27+
```
1728

18-
$ bundle
29+
## Local setup or including in a Ruby/Rails app
1930

20-
Or install it yourself as:
31+
Add to your Gemfile `gem 'superset'`
32+
And then execute: `bundle install`
33+
Or install it yourself as `gem install superset`
2134

22-
$ gem install superset
35+
## Setup API Credentials
2336

37+
Follow this doc setup your users API creds [setting_up_personal_api_credentials](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
38+
39+
Short version is .. copy the `env.sample` to `.env` and add edit values where applicable. Opening a console with `bin/console` will then auto load the `.env` file.
2440

2541
## Usage
2642

27-
Experiment with the API calls directly by open a pry console using
28-
`bin/console`
43+
Experiment with the API calls directly by open a pry console using `bin/console`
2944

30-
Primary usage is for general api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
3145

32-
The Superset API users may then fall into 2 categories
33-
- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc. ref `Superset::Credential::ApiUser`
34-
which pulls credentials from
35-
`ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
3646

37-
- a user for guest token api call to use when embedding dashboards in a host application. ref `Superset::Credential::EmbeddedUser`
38-
which pulls credentials from
39-
`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
4047

41-
Configure your superset host in
42-
`ENV['SUPERSET_HOST']`
48+
### API calls
49+
50+
Quickstart examples
51+
52+
```ruby
53+
Superset::Database::List.call
54+
Superset::Database::GetSchemas.new(1).list # get schemas for database 1
55+
56+
Superset::Dashboard::List.call
57+
Superset::Dashboard::List.new(title_contains: 'Sales').list
4358

44-
Copy the `env.sample` to `.env` and add edit values where applicable.
45-
Opening a console with `bin/console` will then auto load the `.env` file.
59+
Superset::Dashboard::BulkDelete.new(dashboard_ids: [1,2,3]).perform # Dashboards only ( leaves all charts, datasets in place)
60+
Superset::Dashboard::BulkDeleteCascade.new(dashboard_ids: [1,2,3]).perform # Dashboards and related charts and datasets.
4661

47-
See here to setup your users API creds [setting_up_personal_api_credentials](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
62+
Superset::Sqllab::Execute.new(database_id: 1, schema: 'public', query: 'select count(*) from birth_names').perform
4863

64+
Superset::Dashboard::Export.new(dashboard_id: 1, destination_path: '/tmp').perform
4965

50-
## API calls
66+
Superset::RouteInfo.new(route: 'dashboard/_info').perform # Get info on an API endpoint .. handy for getting available filters
67+
Superset::RouteInfo.new(route: 'chart/_info').filters # OR just get the filters for an endpoint
5168

52-
Generally they follow the convention/path of the Superset API strucuture as per the swagger docs.
69+
superset_class_list # helper method to list all classes under Superset::
70+
71+
```
72+
73+
### Duplicating Dashboards
74+
75+
Primary motivation behind this library was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.
76+
See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
77+
78+
### API Examples with results
79+
80+
Generally classes follow the convention/path of the Superset API strucuture as per the swagger docs.
5381

5482
ref https://superset.apache.org/docs/api/
5583

56-
Limited support for filters is available on some list pages. Pagination is supported.
84+
Limited support for filters is available on some list pages, primarily through param `title_contains`.
85+
Pagination is supported via `page_num` param.
5786

5887
Primary methods across majority of api calls are
5988
- response : the full API response
6089
- result : just the result attribute array
6190
- list : displays a formatted output to console, handy for quick investigation of objects
62-
- call : is a alias to list on Get and List requests
91+
- call : is a class method to list on Get and List requests
92+
93+
```ruby
94+
# List all Databases
95+
Superset::Database::List.call
96+
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/?q=(page:0,page_size:100), {}
97+
+----+------------------------------------+------------+------------------+
98+
| Superset::Database::List |
99+
+----+------------------------------------+------------+------------------+
100+
| Id | Database name | Backend | Expose in sqllab |
101+
+----+------------------------------------+------------+------------------+
102+
| 1 | examples | postgresql | true |
103+
+----+------------------------------------+------------+------------------+
104+
105+
# List database schemas for Database 1
106+
Superset::Database::GetSchemas.new(1).list
107+
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/1/schemas/, {}
108+
=> ["information_schema", "public"]
109+
110+
# List dashboards
111+
Superset::Dashboard::List.call
112+
# PAGE_SIZE is set to 100, so get the second set of 100 dashboards with
113+
Superset::Dashboard::List.new(page_num: 1).list
114+
# OR filter by title
115+
Superset::Dashboard::List.new(title_contains: 'Sales').list
116+
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/dashboard/?q=(filters:!((col:dashboard_title,opr:ct,value:'Sales')),page:0,page_size:100), {}
63117

64-
```
65-
# some examples
66-
Superset::Dashboard::Get.call(1)
118+
+-----+------------------------------+-----------+--------------------------------------------------------------------+
119+
| Superset::Dashboard::List |
120+
+-----+------------------------------+-----------+--------------------------------------------------------------------+
121+
| Id | Dashboard title | Status | Url |
122+
+-----+------------------------------+-----------+--------------------------------------------------------------------+
123+
| 6 | Video Game Sales | published | https://your-superset-host/superset/dashboard/6/ |
124+
| 8 | Sales Dashboard | published | https://your-superset-host/superset/dashboard/8/ |
125+
+-----+------------------------------+-----------+--------------------------------------------------------------------+
126+
127+
128+
Superset::Dashboard::Get.call(1) # same as Superset::Dashboard::Get.new(1).list
67129
+----------------------------+
68-
| World Bank's Data |
130+
| World Banks Data |
69131
+----------------------------+
70132
| Charts |
71133
+----------------------------+
@@ -74,36 +136,30 @@ Superset::Dashboard::Get.call(1)
74136
| Life Expectancy VS Rural % |
75137
| Box plot |
76138
| Most Populated Countries |
77-
| World's Population |
78-
| World's Pop Growth |
139+
| Worlds Population |
140+
| Worlds Pop Growth |
79141
| Rural Breakdown |
80142
| Treemap |
81143
| Growth Rate |
82144
+----------------------------+
83145

84-
Superset::Dashboard::List.new(title_contains: 'test').list
85-
D, [2024-03-05T10:48:10.053139 #5095] DEBUG -- : Happi: GET https://your-ss-host/api/v1/dashboard/?q=(filters:!((col:dashboard_title,opr:ct,value:'test')),page:0,page_size:100), {}
86-
+----+-------------------------------------+-----------+-------------------------------------------------------+
87-
| Superset::Dashboard::List |
88-
+----+-------------------------------------+-----------+-------------------------------------------------------+
89-
| Id | Dashboard title | Status | Url |
90-
+----+-------------------------------------+-----------+-------------------------------------------------------+
91-
| 22 | Embedded Test 1 | published | https://your-ss-host/superset/dashboard/22/ |
92-
| 36 | Test Embedded 2 | published | https://your-ss-host/superset/dashboard/36/ |
93-
| 7 | Unicode Test | published | https://your-ss-host/superset/dashboard/unicode-test/ |
94-
+----+-------------------------------------+-----------+-------------------------------------------------------+
95146

147+
```
148+
## Optional Credential setup for Embedded User
96149

97-
# Default page num is 100
98-
Superset::Dashboard::List.new().list
150+
Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
99151

100-
# second set of 100 dashboards
101-
Superset::Dashboard::List.new(page_num: 1).list
152+
The Superset API users fall into 2 categories
153+
- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.
154+
ref `Superset::Credential::ApiUser`
155+
which pulls credentials from `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
102156

103-
```
157+
- a user for guest token api call to use when embedding dashboards in a host application.
158+
ref `Superset::Credential::EmbeddedUser`
159+
which pulls credentials from `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
104160

105161

106-
### Fetch a Guest Token
162+
### Fetch a Guest Token for Embedded user
107163

108164
Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in
109165
`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
@@ -113,52 +169,16 @@ Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
113169
=> "eyJ0eXAiOi............VV4mrMfsvg"
114170
```
115171

116-
## Development
117-
118-
After checking out the repo, run tests with
119-
`bundle exec rspec`
120-
121-
You can also run for an interactive pry prompt that will allow you to experiment.
122-
`bin/console`
123-
124-
Docker setup is also an option.
125-
126-
### Docker Setup
127-
128-
Use [Docker](https://docs.docker.com/docker-for-mac/install/) to run in containers.
129-
130-
Once Docker is installed on your system, you can use the following commands from the root of the application folder, e.g `/var/www/elcapitan`:
131-
132-
###### Build images:
133-
134-
`docker-compose build`
135-
136-
###### Bundle install and run specs:
137-
138-
`docker-compose run --rm app`
139-
140-
###### Bundle install:
141-
142-
`docker-compose run --rm app bundle install`
143-
144-
###### Run specs:
145-
146-
```
147-
docker-compose run --rm app rspec
148-
# or
149-
docker-compose run --rm app /bin/bash # then run rspec from inside the container.
150-
```
151-
152172
## Releasing a new version
153173

154-
On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.
174+
On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.
155175
Build the new version and upload to gemfury.
156176

157177
`gem build superset.gemspec`
158178

159179
### Publishing to RubyGems
160180

161-
WIP .. general idea is for this gem to be made public
181+
WIP .. direction is for this gem to be made public
162182

163183
### ReadyTech private Gemfury repo
164184

‎bin/console‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,23 @@ unless ENV['SUPERSET_HOST'] && ENV['SUPERSET_API_USERNAME'] && ENV['SUPERSET_API
4949
exit
5050
end
5151

52+
def list_classes(namespace)
53+
namespace.constants.each_with_object([]) do |constant, classes|
54+
const_value = namespace.const_get(constant)
55+
if const_value.is_a?(Class)
56+
classes << const_value
57+
elsif const_value.is_a?(Module)
58+
classes.concat(list_classes(const_value))
59+
end
60+
end
61+
end
62+
63+
# general help to list all superset classes
64+
def superset_class_list
65+
puts " ---- Listing Superset Classes ----- "
66+
list_classes(Superset)
67+
end
68+
5269
puts "\n >>> Welcome to the Superset Ruby API Client <<< \n\n"
5370
puts "Your accessible Superset Database connections are: Superset::Database::List.call"
5471

0 commit comments

Comments
 (0)