Workspaces API
A workspace groups related feature sets, jobs, drafts, and reviews together.
Workspaces replace the legacy Projects concept, which means any workflow that previously used client.projects now uses client.workspaces.
To initialize the client, see Starting the client.
List workspaces
# Iterate over all workspaces
for workspace in client.workspaces.list():
print(workspace.uid, workspace.name)
# Access by index
first = client.workspaces.list()[0]
# Filter by name
ws = client.workspaces.list(name="default")[0]
# Filter with an AIP-160 expression
ws = client.workspaces.list(query='display_name = "production"')[0]
Count workspaces
total = client.workspaces.count()
Create a workspace
workspace = client.workspaces.create(
name="my-workspace",
description="Workspace for the fraud detection project",
)
The user who creates the workspace is automatically granted the owner role.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Display name for the workspace. |
description | str | No | Description. Defaults to "". |
Returns a Workspace object.
Get a workspace
# Pass the workspace uid — the identifier part of "workspaces/<uid>"
workspace = client.workspaces.get("ws-abc123")
Workspace properties
| Property | Type | Description |
|---|---|---|
uid | str | Unique identifier. |
name | str | Display name. |
description | str | Description. |
created_time | datetime | When the workspace was created. |
last_modified_time | datetime | When the workspace was last updated. |
access_level | str | "WORKSPACE_ACCESS_LEVEL_PUBLIC" or "WORKSPACE_ACCESS_LEVEL_PRIVATE". |
permission_scope | WorkspacePermissionScope | Whether feature sets inside the workspace are visible to others (see Access control). |
feature_sets | FeatureSets | Feature sets in this workspace. |
drafts | FeatureSetDrafts | Draft feature sets in this workspace. |
reviews | Reviews | Feature set reviews in this workspace. |
jobs | Jobs | Jobs in this workspace. |
print(workspace.uid)
print(workspace.name)
print(workspace.description)
print(workspace.created_time)
print(workspace.last_modified_time)
Update a workspace
Only the fields you pass are updated.
workspace.update(name="fraud-detection-v2")
workspace.update(description="Renamed workspace for fraud detection")
workspace.update(name="fraud-detection-v2", description="Renamed workspace")
# Clear the description
workspace.update(description=None)
Delete a workspace
workspace.delete()
This deletes all feature sets, features, jobs, and other resources in the workspace.
Access control
Access levels
from h2o_featurestore import WorkspaceAccessLevel
# Visible to all users on the platform
workspace.set_access_level(WorkspaceAccessLevel.PUBLIC)
# Restricted to users with explicit access
workspace.set_access_level(WorkspaceAccessLevel.PRIVATE)
# Plain strings are also accepted
workspace.set_access_level("PUBLIC")
workspace.set_access_level("PRIVATE")
# Check the current level
print(workspace.access_level)
# "WORKSPACE_ACCESS_LEVEL_PUBLIC" or "WORKSPACE_ACCESS_LEVEL_PRIVATE"
| Value | Description |
|---|---|
WorkspaceAccessLevel.PUBLIC | Visible to all users on the platform. |
WorkspaceAccessLevel.PRIVATE | Restricted to users with explicit access. |
Permission scope
When a workspace is PUBLIC, the permission scope controls whether the feature sets inside it are also visible.
from h2o_featurestore import WorkspaceAccessLevel, WorkspacePermissionScope
# Public workspace — feature sets are visible to everyone
workspace.set_access_level(
WorkspaceAccessLevel.PUBLIC,
permission_scope=WorkspacePermissionScope.FEATURE_SET,
)
# Public workspace — only the workspace is visible, not the feature sets inside it
workspace.set_access_level(
WorkspaceAccessLevel.PUBLIC,
permission_scope=WorkspacePermissionScope.WORKSPACE_ONLY,
)
# Check the current scope
print(workspace.permission_scope)
# WorkspacePermissionScope.FEATURE_SET or WorkspacePermissionScope.WORKSPACE_ONLY
| Value | Description |
|---|---|
WorkspacePermissionScope.FEATURE_SET | Feature sets are visible to anyone who can see the workspace. |
WorkspacePermissionScope.WORKSPACE_ONLY | The workspace is visible, but feature sets inside it require separate access. |
List feature sets across workspaces
# All feature sets across every accessible workspace
for feature_set in client.workspaces.list_feature_sets():
print(feature_set.name)
# Limit to specific workspaces
for feature_set in client.workspaces.list_feature_sets(
workspace_names=["workspaces/ws-abc123", "workspaces/ws-def456"]
):
print(feature_set.name)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
workspace_names | list[str] | No | Workspace resource names to search (e.g. "workspaces/<uid>"). Searches all accessible workspaces if omitted. |
Returns a generator of FeatureSet objects.
Search features within a workspace
Searches feature names and descriptions across all feature sets in the workspace.
# Free-text search
for feature in workspace.search_features(query="customer"):
print(feature.name, feature.description)
# Sort results
for feature in workspace.search_features(
query="fraud",
sort_field="FEATURE_SORT_FIELD_NAME",
sort_direction="SORT_ASC",
):
print(feature.name)
# Only show features from feature sets you own
for feature in workspace.search_features(owned_only=True):
print(feature.name)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | str | No | Free-text search on feature name and description. |
sort_field | str | No | "FEATURE_SORT_FIELD_NAME" or "FEATURE_SORT_FIELD_DESCRIPTION". |
sort_direction | str | No | "SORT_ASC" or "SORT_DESC". |
owned_only | bool | No | If True, only returns features from feature sets you own. |
Schema extraction
Schema extraction runs as a job inside a workspace, so call it on the workspace you intend to register the feature set in: workspace.extract_schema_from_source(...).
The same method also exists on the client (client.extract_schema_from_source(...), see Schema API), but it scopes the job to your default workspace. That means the job does not appear in the target workspace's job list, Spark size presets resolve against the default workspace instead of the target one, and the call fails if you are not allowed to create feature sets in the default workspace — so prefer the workspace-scoped form.
Spark size presets are resolved per workspace. If you pass a spark_size that is
only available in the target workspace, the client-level call does not quietly
fall back to a default — it fails because the preset cannot be found in your
default workspace.
from h2o_featurestore import CSVFile
source = CSVFile("s3://my-bucket/data.csv")
# Waits for the job to complete and returns a Schema
schema = workspace.extract_schema_from_source(source)
# Returns a Job immediately; call wait_for_result() when you need the Schema
job = workspace.extract_schema_from_source_async(source)
schema = job.wait_for_result()
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
source | data source | Yes | The data source to extract the schema from. See Supported data sources. |
credentials | credentials object | No | Credentials for the data source. If omitted, they are read from environment variables. See Credentials configuration. |
profile_id | str | No | Id of an ingest profile to use. |
spark_size | str | No | Spark size preset name. When left blank, the workspace default is used. |
For derived schemas from existing feature sets:
from h2o_featurestore import SparkPipeline
schema = workspace.extract_derived_schema(
feature_sets=[fs_a, fs_b],
transformation=SparkPipeline(...),
)
# Async version
job = workspace.extract_derived_schema_async(
feature_sets=[fs_a, fs_b],
transformation=SparkPipeline(...),
)
schema = job.wait_for_result()
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
feature_sets | list | Yes | Parent feature sets to derive from. Each one must already have been ingested. |
transformation | transformation | Yes | The transformation to apply, for example SparkPipeline. See Supported derived transformation. |
spark_size | str | No | Spark size preset name. When left blank, the workspace default is used. |
The parent feature sets may live in other workspaces, as long as you have editor permission on each of them. The workspace you call the method on runs the job and owns the resulting feature set. See Joining feature sets from different workspaces for a worked example.
Working with feature sets
Access feature sets through the workspace to keep all operations scoped to it.
# List feature sets in a workspace
for fs in workspace.feature_sets.list():
print(fs.name)
# Register a feature set in a workspace
feature_set = workspace.feature_sets.register(schema=schema, feature_set_name="customer_features")
Migrating from Projects
| Projects API | Workspaces API |
|---|---|
client.projects.list() | client.workspaces.list() |
client.projects.create(project_name=..., description=...) | client.workspaces.create(name=..., description=...) |
client.projects.get_by_name("name") | client.workspaces.list(name="name")[0] ¹ |
project.delete() | workspace.delete() |
client.projects.list_feature_sets(["proj_a"]) | client.workspaces.list_feature_sets(["workspaces/uid-a"]) |
AccessModifier.PUBLIC / PRIVATE | WorkspaceAccessLevel.PUBLIC / PRIVATE |
project.list_owners() / project.list_editors() | Not exposed via the Python client — managed through the workspace UI. See Permissions. |
¹ list(name="name")[0] raises IndexError when no workspace matches, unlike get_by_name() which raised a descriptive error. Check that list(...) returns at least one result before indexing.
- Submit and view feedback for this page
- Send feedback about H2O Feature Store to cloud-feedback@h2o.ai