metabase-python

An unofficial Python library for the Metabase API.

Installation

pip install metabase-python

Usage

Connection

Start by creating an instance of Metabase with your credentials.

frommetabaseimportMetabasemetabase=Metabase(
host="<host>",
user="<username/email>",
password="<password>",
)

Interacting with Endpoints

You can then interact with any of the supported endpoints through the classes included in this package. Methods that instantiate an object from the Metabase API require the using parameter which expects an instance of Metabase such as the one we just instantiated above. All changes are reflected in Metabase instantly.

frommetabaseimportUser# get all objectsusers=User.list(using=metabase)
# get an object by IDuser=User.get(1, using=metabase)
# attributes are automatically loaded and available in the instanceifuser.is_active:
print("User is active!")
# update any available attributeuser.update(is_superuser=True)
# delete an objectuser.delete()
# create an objectnew_user=User.create(
using=metabase,
first_name="<first_name>",
last_name="<last_name>",
email="<email>",
password="<password>"
)

The methods .list(), .get(), .create(), .update(), .delete() are available on all endpoints that support them in Metabase API.

Some endpoints also support additional methods:

frommetabaseimportUseruser=User.get(1, using=metabase)
user.reactivate() # Reactivate useruser.send_invite() # Resend the user invite email for a given user.

Here's a slightly more advanced example:

frommetabaseimportUser, PermissionGroup, PermissionMembership# create a new PermissionGroupmy_group=PermissionGroup.create(name="My Group", using=metabase)
foruserinUser.list():
# add all users to my_groupPermissionMembership.create(
group_id=my_group.id,
user_id=user.id,
using=metabase,
)

Querying & MBQL

You can also execute queries and get results back as a Pandas DataFrame. You can provide the exact MBQL, or use the Query object to compile MBQL (i.e. Metabase Query Language) from Python classes included in this package.

frommetabaseimportDataset, Query, Count, GroupBy, TemporalOptiondataset=Dataset.create(
database=1,
type="query",
query={
"source-table": 1,
"aggregation": [["count"]],
"breakout": ["field", 7, {"temporal-unit": "year"},],
},
using=metabase,
)
# compile the MBQL above using the Query objectdataset=Dataset.create(
database=1,
type="query",
query=Query(
table_id=2,
aggregations=[Count()],
group_by=[GroupBy(id=7, option=TemporalOption.YEAR)]
).compile(),
using=metabase
)
df=dataset.to_pandas()

As shown above, the Query object allows you to easily compile MBQL from Python objects. Here is a more complete example:

frommetabaseimportQuery, Sum, Average, Metric, Greater, GroupBy, BinOption, TemporalOptionquery=Query(
table_id=5,
aggregations=[
Sum(id=5), # Provide the ID for the Metabase fieldAverage(id=5, name="Average of Price"), # Optionally, you can provide a nameMetric.get(5) # You can also provide your Metabase Metrics
],
filters=[
Greater(id=1, value=5.5) # Filter for values of FieldID 1 greater than 5.5
],
group_by=[
GroupBy(id=4), # Group by FieldID 4GroupBy(id=5, option=BinOption.AUTO), # You can use Metabase's binning feature for numeric fieldsGroupBy(id=5, option=TemporalOption.YEAR) # Or it's temporal option for date fields
]
)
print(query.compile())
{
'source-table': 5,
'aggregation': [
['sum', ['field', 5, None]],
['aggregation-options', ['avg', ['field', 5, None]], {'name': 'Average of Price', 'display-name': 'Average of Price'}],
["metric", 5]
],
'breakout': [
['field', 4, None],
['field', 5, {'binning': {'strategy': 'default'}}],
['field', 5, {'temporal-unit': 'year'}]
],
'filter': ['>', ['field', 1, None], 5.5]
}

This can also be used to more easily create Metric objects.

frommetabaseimportMetric, Query, Count, EndsWith, CaseOptionmetric=Metric.create(
name="Gmail Users",
description="Number of users with a @gmail.com email address.",
table_id=2,
definition=Query(
table_id=1,
aggregations=[Count()],
filters=[EndsWith(id=4, value="@gmail.com", option=CaseOption.CASE_INSENSITIVE)]
).compile(),
using=metabase
)

Endpoints

For a full list of endpoints and methods, see Metabase API.

Endpoints	Support	Notes
Activity	❌
Alert	❌
Automagic dashboards	❌
Card	✅
Collection	❌
Dashboard	❌
Database	✅
Dataset	✅
Email	❌
Embed	❌
Field	✅
Geojson	❌
Ldap	❌
Login history	❌
Metric	✅
Native query snippet	❌
Notify	❌
Permissions	✅
Premium features	❌
Preview embed	❌
Public	❌
Pulse	❌
Revision	❌
Search	❌
Segment	✅
Session	❌
Setting	❌
Setup	❌
Slack	❌
Table	✅
Task	❌
Tiles	❌
Transform	❌
User	✅
Util	❌

Contributing

Contributions are welcome!

License

This library is distributed under the MIT license.