From c1a1932fbd68760d36176412ba8823e25f0fa288 Mon Sep 17 00:00:00 2001 From: Renaud Hartert Date: Thu, 6 Mar 2025 10:27:15 +0100 Subject: [PATCH] Update APIs --- .codegen/_openapi_sha | 2 +- NEXT_CHANGELOG.md | 55 + databricks/sdk/service/apps.py | 14 + databricks/sdk/service/billing.py | 57 +- databricks/sdk/service/catalog.py | 47 + databricks/sdk/service/cleanrooms.py | 9 +- databricks/sdk/service/compute.py | 184 ++- databricks/sdk/service/dashboards.py | 498 +++---- databricks/sdk/service/jobs.py | 193 ++- databricks/sdk/service/marketplace.py | 1 + databricks/sdk/service/ml.py | 326 +++-- databricks/sdk/service/oauth2.py | 83 +- databricks/sdk/service/serving.py | 46 +- databricks/sdk/service/settings.py | 16 +- databricks/sdk/service/sharing.py | 1146 +++++++++++++++-- databricks/sdk/service/vectorsearch.py | 15 +- databricks/sdk/service/workspace.py | 29 +- docs/account/billing/billable_usage.rst | 10 +- docs/account/billing/budget_policy.rst | 45 +- docs/account/billing/budgets.rst | 208 +-- docs/account/billing/log_delivery.rst | 114 +- docs/account/billing/usage_dashboards.rst | 12 +- .../account/catalog/metastore_assignments.rst | 36 +- docs/account/catalog/metastores.rst | 30 +- docs/account/catalog/storage_credentials.rst | 36 +- docs/account/iam/access_control.rst | 18 +- docs/account/iam/groups.rst | 50 +- docs/account/iam/service_principals.rst | 68 +- docs/account/iam/users.rst | 92 +- docs/account/iam/workspace_assignment.rst | 36 +- .../account/oauth2/custom_app_integration.rst | 36 +- docs/account/oauth2/federation_policy.rst | 40 +- docs/account/oauth2/o_auth_published_apps.rst | 6 +- .../oauth2/published_app_integration.rst | 36 +- .../service_principal_federation_policy.rst | 38 +- .../oauth2/service_principal_secrets.rst | 32 +- docs/account/provisioning/credentials.rst | 46 +- docs/account/provisioning/encryption_keys.rst | 60 +- docs/account/provisioning/networks.rst | 52 +- docs/account/provisioning/private_access.rst | 92 +- docs/account/provisioning/storage.rst | 39 +- docs/account/provisioning/vpc_endpoints.rst | 56 +- docs/account/provisioning/workspaces.rst | 124 +- .../settings/csp_enablement_account.rst | 16 +- .../settings/disable_legacy_features.rst | 22 +- .../settings/enable_ip_access_lists.rst | 20 +- .../settings/esm_enablement_account.rst | 14 +- docs/account/settings/ip_access_lists.rst | 74 +- .../account/settings/network_connectivity.rst | 52 +- docs/account/settings/personal_compute.rst | 22 +- docs/account/settings/settings.rst | 6 +- docs/dbdataclasses/catalog.rst | 10 + docs/dbdataclasses/compute.rst | 6 +- docs/dbdataclasses/dashboards.rst | 85 +- docs/dbdataclasses/jobs.rst | 11 + docs/dbdataclasses/marketplace.rst | 3 + docs/dbdataclasses/ml.rst | 47 +- docs/dbdataclasses/oauth2.rst | 4 + docs/dbdataclasses/sharing.rst | 199 ++- docs/dbdataclasses/workspace.rst | 12 +- docs/workspace/apps/apps.rst | 84 +- .../workspace/catalog/artifact_allowlists.rst | 12 +- docs/workspace/catalog/catalogs.rst | 42 +- docs/workspace/catalog/connections.rst | 137 +- docs/workspace/catalog/credentials.rst | 62 +- docs/workspace/catalog/external_locations.rst | 86 +- docs/workspace/catalog/functions.rst | 38 +- docs/workspace/catalog/grants.rst | 112 +- docs/workspace/catalog/metastores.rst | 103 +- docs/workspace/catalog/model_versions.rst | 48 +- docs/workspace/catalog/online_tables.rst | 20 +- docs/workspace/catalog/quality_monitors.rst | 100 +- docs/workspace/catalog/registered_models.rst | 78 +- docs/workspace/catalog/resource_quotas.rst | 15 +- docs/workspace/catalog/schemas.rst | 48 +- .../workspace/catalog/storage_credentials.rst | 66 +- docs/workspace/catalog/system_schemas.rst | 22 +- docs/workspace/catalog/table_constraints.rst | 22 +- docs/workspace/catalog/tables.rst | 79 +- .../catalog/temporary_table_credentials.rst | 6 +- docs/workspace/catalog/volumes.rst | 154 ++- docs/workspace/catalog/workspace_bindings.rst | 36 +- .../cleanrooms/clean_room_assets.rst | 34 +- .../cleanrooms/clean_room_task_runs.rst | 8 +- docs/workspace/cleanrooms/clean_rooms.rst | 42 +- docs/workspace/compute/cluster_policies.rst | 114 +- docs/workspace/compute/clusters.rst | 424 +++--- docs/workspace/compute/command_execution.rst | 56 +- .../workspace/compute/global_init_scripts.rst | 78 +- docs/workspace/compute/instance_pools.rst | 80 +- docs/workspace/compute/instance_profiles.rst | 64 +- docs/workspace/compute/libraries.rst | 32 +- .../policy_compliance_for_clusters.rst | 28 +- docs/workspace/compute/policy_families.rst | 16 +- docs/workspace/dashboards/genie.rst | 95 +- docs/workspace/dashboards/lakeview.rst | 96 +- .../dashboards/lakeview_embedded.rst | 8 +- docs/workspace/dashboards/query_execution.rst | 14 +- docs/workspace/files/dbfs.rst | 70 +- docs/workspace/files/files.rst | 76 +- docs/workspace/iam/access_control.rst | 4 +- .../iam/account_access_control_proxy.rst | 18 +- docs/workspace/iam/current_user.rst | 4 +- docs/workspace/iam/groups.rst | 81 +- docs/workspace/iam/permission_migration.rst | 4 +- docs/workspace/iam/permissions.rst | 88 +- docs/workspace/iam/service_principals.rst | 78 +- docs/workspace/iam/users.rst | 114 +- docs/workspace/jobs/jobs.rst | 670 +++++----- .../jobs/policy_compliance_for_jobs.rst | 22 +- .../marketplace/consumer_fulfillments.rst | 12 +- .../marketplace/consumer_installations.rst | 32 +- .../marketplace/consumer_listings.rst | 24 +- .../consumer_personalization_requests.rst | 18 +- .../marketplace/consumer_providers.rst | 18 +- .../marketplace/provider_exchange_filters.rst | 26 +- .../marketplace/provider_exchanges.rst | 58 +- docs/workspace/marketplace/provider_files.rst | 26 +- .../marketplace/provider_listings.rst | 32 +- .../provider_personalization_requests.rst | 12 +- ...provider_provider_analytics_dashboards.rst | 18 +- .../marketplace/provider_providers.rst | 32 +- docs/workspace/ml/experiments.rst | 400 +++--- docs/workspace/ml/model_registry.rst | 416 +++--- docs/workspace/pipelines/pipelines.rst | 203 +-- docs/workspace/serving/serving_endpoints.rst | 102 +- .../serving/serving_endpoints_data_plane.rst | 4 +- ...aibi_dashboard_embedding_access_policy.rst | 20 +- ...i_dashboard_embedding_approved_domains.rst | 20 +- .../settings/automatic_cluster_update.rst | 14 +- .../settings/compliance_security_profile.rst | 16 +- .../settings/credentials_manager.rst | 6 +- docs/workspace/settings/default_namespace.rst | 24 +- .../settings/disable_legacy_access.rst | 22 +- .../settings/disable_legacy_dbfs.rst | 20 +- .../settings/enhanced_security_monitoring.rst | 16 +- docs/workspace/settings/ip_access_lists.rst | 110 +- .../settings/notification_destinations.rst | 32 +- .../settings/restrict_workspace_admins.rst | 20 +- docs/workspace/settings/settings.rst | 10 +- docs/workspace/settings/token_management.rst | 58 +- docs/workspace/settings/tokens.rst | 24 +- docs/workspace/settings/workspace_conf.rst | 14 +- docs/workspace/sharing/providers.rst | 71 +- .../sharing/recipient_activation.rst | 16 +- docs/workspace/sharing/recipients.rst | 64 +- docs/workspace/sharing/shares.rst | 121 +- docs/workspace/sql/alerts.rst | 134 +- docs/workspace/sql/alerts_legacy.rst | 56 +- docs/workspace/sql/dashboard_widgets.rst | 14 +- docs/workspace/sql/dashboards.rst | 50 +- docs/workspace/sql/data_sources.rst | 14 +- docs/workspace/sql/dbsql_permissions.rst | 42 +- docs/workspace/sql/queries.rst | 92 +- docs/workspace/sql/queries_legacy.rst | 90 +- docs/workspace/sql/query_history.rst | 15 +- docs/workspace/sql/query_visualizations.rst | 22 +- .../sql/query_visualizations_legacy.rst | 36 +- docs/workspace/sql/redash_config.rst | 2 +- docs/workspace/sql/statement_execution.rst | 105 +- docs/workspace/sql/warehouses.rst | 153 +-- .../vectorsearch/vector_search_endpoints.rst | 20 +- .../vectorsearch/vector_search_indexes.rst | 74 +- docs/workspace/workspace/git_credentials.rst | 50 +- docs/workspace/workspace/repos.rst | 86 +- docs/workspace/workspace/secrets.rst | 148 +-- docs/workspace/workspace/workspace.rst | 112 +- 167 files changed, 7094 insertions(+), 4876 deletions(-) diff --git a/.codegen/_openapi_sha b/.codegen/_openapi_sha index 562b72fcc..baefa0efc 100644 --- a/.codegen/_openapi_sha +++ b/.codegen/_openapi_sha @@ -1 +1 @@ -99f644e72261ef5ecf8d74db20f4b7a1e09723cc \ No newline at end of file +bdd8536d26484460f450b1d17722c01c5a6a50a9 \ No newline at end of file diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md index ab063fee0..e949cffbe 100644 --- a/NEXT_CHANGELOG.md +++ b/NEXT_CHANGELOG.md @@ -19,3 +19,58 @@ * Update On Behalf Of User Authentication in Multithreaded applications ([#907](https://github.com/databricks/databricks-sdk-py/pull/907)) ### API Changes +* Added `execute_message_attachment_query()`, `get_message_attachment_query_result()` and `get_space()` methods for [w.genie](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/dashboards/genie.html) workspace-level service. +* Added `list_provider_share_assets()` method for [w.providers](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/sharing/providers.html) workspace-level service. +* Added `budget_policy_id` and `effective_budget_policy_id` fields for `databricks.sdk.service.apps.App`. +* Added `policy` field for `databricks.sdk.service.billing.CreateBudgetPolicyRequest`. +* Added `databricks_gcp_service_account` field for `databricks.sdk.service.catalog.ValidateCredentialRequest`. +* Added `attachment_id` field for `databricks.sdk.service.dashboards.GenieAttachment`. +* Added `conversation_id` field for `databricks.sdk.service.dashboards.GenieConversation`. +* Added `message_id` field for `databricks.sdk.service.dashboards.GenieMessage`. +* Added `description`, `id`, `last_updated_timestamp`, `query`, `query_result_metadata` and `title` fields for `databricks.sdk.service.dashboards.GenieQueryAttachment`. +* Added `gen_ai_compute_task` field for `databricks.sdk.service.jobs.RunTask`. +* Added `gen_ai_compute_task` field for `databricks.sdk.service.jobs.SubmitTask`. +* Added `gen_ai_compute_task` field for `databricks.sdk.service.jobs.Task`. +* Added `run_name` field for `databricks.sdk.service.ml.CreateRun`. +* Added `run_name` field for `databricks.sdk.service.ml.RunInfo`. +* Added `run_name` field for `databricks.sdk.service.ml.UpdateRun`. +* Added `lifetime` field for `databricks.sdk.service.oauth2.CreateServicePrincipalSecretRequest`. +* Added `expire_time` field for `databricks.sdk.service.oauth2.CreateServicePrincipalSecretResponse`. +* Added `jwks_uri` field for `databricks.sdk.service.oauth2.OidcFederationPolicy`. +* Added `expire_time` field for `databricks.sdk.service.oauth2.SecretInfo`. +* Added `instance_profile_arn` field for `databricks.sdk.service.serving.AmazonBedrockConfig`. +* Added `budget_policy_id` field for `databricks.sdk.service.serving.CreateServingEndpoint`. +* Added `budget_policy_id` field for `databricks.sdk.service.serving.ServingEndpoint`. +* Added `budget_policy_id` field for `databricks.sdk.service.serving.ServingEndpointDetailed`. +* Added `add`, `principal` and `remove` fields for `databricks.sdk.service.sharing.PermissionsChange`. +* Added `columns_to_rerank` field for `databricks.sdk.service.vectorsearch.QueryVectorIndexRequest`. +* Added `oracle` and `teradata` enum values for `databricks.sdk.service.catalog.ConnectionType`. +* Added `function_arguments_invalid_type_exception` and `message_cancelled_while_executing_exception` enum values for `databricks.sdk.service.dashboards.MessageErrorType`. +* Added `waiting` enum value for `databricks.sdk.service.jobs.RunLifecycleStateV2State`. +* Added `active_only`, `all` and `deleted_only` enum values for `databricks.sdk.service.ml.ViewType`. +* Added `oauth_client_credentials` enum value for `databricks.sdk.service.sharing.AuthenticationType`. +* Added `raw` enum value for `databricks.sdk.service.workspace.ExportFormat`. +* [Breaking] Changed `get_by_name()` method for [w.experiments](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/ml/experiments.html) workspace-level service to return `databricks.sdk.service.ml.GetExperimentByNameResponse` dataclass. +* [Breaking] Changed `log_inputs()` method for [w.experiments](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/ml/experiments.html) workspace-level service with new required argument order. +* [Breaking] Changed `share_permissions()` method for [w.shares](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/sharing/shares.html) workspace-level service to return `databricks.sdk.service.sharing.GetSharePermissionsResponse` dataclass. +* [Breaking] Changed `share_permissions()` and `update_permissions()` methods for [w.shares](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/sharing/shares.html) workspace-level service return type to become non-empty. +* [Breaking] Changed `update_permissions()` method for [w.shares](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/sharing/shares.html) workspace-level service to return `databricks.sdk.service.sharing.UpdateSharePermissionsResponse` dataclass. +* [Breaking] Changed `policy_id` field for `databricks.sdk.service.billing.BudgetPolicy` to no longer be required. +* Changed `policy_id` field for `databricks.sdk.service.billing.BudgetPolicy` to no longer be required. +* [Breaking] Changed `partitions` field for `databricks.sdk.service.cleanrooms.CleanRoomAssetTableLocalDetails` to type `databricks.sdk.service.cleanrooms.PartitionList` dataclass. +* [Breaking] Changed `query` field for `databricks.sdk.service.dashboards.GenieAttachment` to type `databricks.sdk.service.dashboards.GenieQueryAttachment` dataclass. +* [Breaking] Changed `digest`, `name`, `source` and `source_type` fields for `databricks.sdk.service.ml.Dataset` to be required. +* Changed `digest`, `name`, `source` and `source_type` fields for `databricks.sdk.service.ml.Dataset` to be required. +* [Breaking] Changed `dataset` field for `databricks.sdk.service.ml.DatasetInput` to be required. +* Changed `dataset` field for `databricks.sdk.service.ml.DatasetInput` to be required. +* Changed `key` and `value` fields for `databricks.sdk.service.ml.InputTag` to be required. +* [Breaking] Changed `key` and `value` fields for `databricks.sdk.service.ml.InputTag` to be required. +* [Breaking] Changed `view_type` field for `databricks.sdk.service.ml.ListExperimentsRequest` to type `databricks.sdk.service.ml.ViewType` dataclass. +* [Breaking] Changed `run_id` field for `databricks.sdk.service.ml.LogInputs` to be required. +* [Breaking] Changed `view_type` field for `databricks.sdk.service.ml.SearchExperiments` to type `databricks.sdk.service.ml.ViewType` dataclass. +* [Breaking] Changed `run_view_type` field for `databricks.sdk.service.ml.SearchRuns` to type `databricks.sdk.service.ml.ViewType` dataclass. +* [Breaking] Removed `custom_tags` and `policy_name` fields for `databricks.sdk.service.billing.CreateBudgetPolicyRequest`. +* [Breaking] Removed `cached_query_schema`, `description`, `id`, `instruction_id`, `instruction_title`, `last_updated_timestamp`, `query`, `statement_id` and `title` fields for `databricks.sdk.service.dashboards.QueryAttachment`. +* [Breaking] Removed `max_results` and `page_token` fields for `databricks.sdk.service.sharing.UpdateSharePermissions`. +* [Breaking] Removed `active_only`, `all` and `deleted_only` enum values for `databricks.sdk.service.ml.SearchExperimentsViewType`. +* [Breaking] Removed `active_only`, `all` and `deleted_only` enum values for `databricks.sdk.service.ml.SearchRunsRunViewType`. diff --git a/databricks/sdk/service/apps.py b/databricks/sdk/service/apps.py index bc001faa8..598ec1370 100755 --- a/databricks/sdk/service/apps.py +++ b/databricks/sdk/service/apps.py @@ -31,6 +31,8 @@ class App: app_status: Optional[ApplicationStatus] = None + budget_policy_id: Optional[str] = None + compute_status: Optional[ComputeStatus] = None create_time: Optional[str] = None @@ -46,6 +48,8 @@ class App: description: Optional[str] = None """The description of the app.""" + effective_budget_policy_id: Optional[str] = None + id: Optional[str] = None """The unique identifier of the app.""" @@ -78,6 +82,8 @@ def as_dict(self) -> dict: body["active_deployment"] = self.active_deployment.as_dict() if self.app_status: body["app_status"] = self.app_status.as_dict() + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.compute_status: body["compute_status"] = self.compute_status.as_dict() if self.create_time is not None: @@ -88,6 +94,8 @@ def as_dict(self) -> dict: body["default_source_code_path"] = self.default_source_code_path if self.description is not None: body["description"] = self.description + if self.effective_budget_policy_id is not None: + body["effective_budget_policy_id"] = self.effective_budget_policy_id if self.id is not None: body["id"] = self.id if self.name is not None: @@ -117,6 +125,8 @@ def as_shallow_dict(self) -> dict: body["active_deployment"] = self.active_deployment if self.app_status: body["app_status"] = self.app_status + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.compute_status: body["compute_status"] = self.compute_status if self.create_time is not None: @@ -127,6 +137,8 @@ def as_shallow_dict(self) -> dict: body["default_source_code_path"] = self.default_source_code_path if self.description is not None: body["description"] = self.description + if self.effective_budget_policy_id is not None: + body["effective_budget_policy_id"] = self.effective_budget_policy_id if self.id is not None: body["id"] = self.id if self.name is not None: @@ -155,11 +167,13 @@ def from_dict(cls, d: Dict[str, Any]) -> App: return cls( active_deployment=_from_dict(d, "active_deployment", AppDeployment), app_status=_from_dict(d, "app_status", ApplicationStatus), + budget_policy_id=d.get("budget_policy_id", None), compute_status=_from_dict(d, "compute_status", ComputeStatus), create_time=d.get("create_time", None), creator=d.get("creator", None), default_source_code_path=d.get("default_source_code_path", None), description=d.get("description", None), + effective_budget_policy_id=d.get("effective_budget_policy_id", None), id=d.get("id", None), name=d.get("name", None), pending_deployment=_from_dict(d, "pending_deployment", AppDeployment), diff --git a/databricks/sdk/service/billing.py b/databricks/sdk/service/billing.py index a5ff4b68c..4e8e4bca6 100755 --- a/databricks/sdk/service/billing.py +++ b/databricks/sdk/service/billing.py @@ -364,12 +364,12 @@ def from_dict(cls, d: Dict[str, Any]) -> BudgetConfigurationFilterWorkspaceIdCla class BudgetPolicy: """Contains the BudgetPolicy details.""" - policy_id: str - """The Id of the policy. This field is generated by Databricks and globally unique.""" - custom_tags: Optional[List[compute.CustomPolicyTag]] = None """A list of tags defined by the customer. At most 20 entries are allowed per policy.""" + policy_id: Optional[str] = None + """The Id of the policy. This field is generated by Databricks and globally unique.""" + policy_name: Optional[str] = None """The name of the policy. - Must be unique among active policies. - Can contain only characters from the ISO 8859-1 (latin1) set.""" @@ -672,12 +672,10 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateBudgetConfigurationResponse: class CreateBudgetPolicyRequest: """A request to create a BudgetPolicy.""" - custom_tags: Optional[List[compute.CustomPolicyTag]] = None - """A list of tags defined by the customer. At most 40 entries are allowed per policy.""" - - policy_name: Optional[str] = None - """The name of the policy. - Must be unique among active policies. - Can contain only characters of - 0-9, a-z, A-Z, -, =, ., :, /, @, _, +, whitespace.""" + policy: Optional[BudgetPolicy] = None + """The policy to create. `policy_id` needs to be empty as it will be generated `policy_name` must + be provided, custom_tags may need to be provided depending on the cloud provider. All other + fields are optional.""" request_id: Optional[str] = None """A unique identifier for this request. Restricted to 36 ASCII characters. A random UUID is @@ -686,10 +684,8 @@ class CreateBudgetPolicyRequest: def as_dict(self) -> dict: """Serializes the CreateBudgetPolicyRequest into a dictionary suitable for use as a JSON request body.""" body = {} - if self.custom_tags: - body["custom_tags"] = [v.as_dict() for v in self.custom_tags] - if self.policy_name is not None: - body["policy_name"] = self.policy_name + if self.policy: + body["policy"] = self.policy.as_dict() if self.request_id is not None: body["request_id"] = self.request_id return body @@ -697,10 +693,8 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the CreateBudgetPolicyRequest into a shallow dictionary of its immediate attributes.""" body = {} - if self.custom_tags: - body["custom_tags"] = self.custom_tags - if self.policy_name is not None: - body["policy_name"] = self.policy_name + if self.policy: + body["policy"] = self.policy if self.request_id is not None: body["request_id"] = self.request_id return body @@ -708,11 +702,7 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, Any]) -> CreateBudgetPolicyRequest: """Deserializes the CreateBudgetPolicyRequest from a dictionary.""" - return cls( - custom_tags=_repeated_dict(d, "custom_tags", compute.CustomPolicyTag), - policy_name=d.get("policy_name", None), - request_id=d.get("request_id", None), - ) + return cls(policy=_from_dict(d, "policy", BudgetPolicy), request_id=d.get("request_id", None)) @dataclass @@ -1752,22 +1742,15 @@ class BudgetPolicyAPI: def __init__(self, api_client): self._api = api_client - def create( - self, - *, - custom_tags: Optional[List[compute.CustomPolicyTag]] = None, - policy_name: Optional[str] = None, - request_id: Optional[str] = None, - ) -> BudgetPolicy: + def create(self, *, policy: Optional[BudgetPolicy] = None, request_id: Optional[str] = None) -> BudgetPolicy: """Create a budget policy. Creates a new policy. - :param custom_tags: List[:class:`CustomPolicyTag`] (optional) - A list of tags defined by the customer. At most 40 entries are allowed per policy. - :param policy_name: str (optional) - The name of the policy. - Must be unique among active policies. - Can contain only characters of - 0-9, a-z, A-Z, -, =, ., :, /, @, _, +, whitespace. + :param policy: :class:`BudgetPolicy` (optional) + The policy to create. `policy_id` needs to be empty as it will be generated `policy_name` must be + provided, custom_tags may need to be provided depending on the cloud provider. All other fields are + optional. :param request_id: str (optional) A unique identifier for this request. Restricted to 36 ASCII characters. A random UUID is recommended. This request is only idempotent if a `request_id` is provided. @@ -1775,10 +1758,8 @@ def create( :returns: :class:`BudgetPolicy` """ body = {} - if custom_tags is not None: - body["custom_tags"] = [v.as_dict() for v in custom_tags] - if policy_name is not None: - body["policy_name"] = policy_name + if policy is not None: + body["policy"] = policy.as_dict() if request_id is not None: body["request_id"] = request_id headers = { diff --git a/databricks/sdk/service/catalog.py b/databricks/sdk/service/catalog.py index 0630b40b0..a790b1b6e 100755 --- a/databricks/sdk/service/catalog.py +++ b/databricks/sdk/service/catalog.py @@ -1456,11 +1456,13 @@ class ConnectionType(Enum): HIVE_METASTORE = "HIVE_METASTORE" HTTP = "HTTP" MYSQL = "MYSQL" + ORACLE = "ORACLE" POSTGRESQL = "POSTGRESQL" REDSHIFT = "REDSHIFT" SNOWFLAKE = "SNOWFLAKE" SQLDW = "SQLDW" SQLSERVER = "SQLSERVER" + TERADATA = "TERADATA" @dataclass @@ -8130,6 +8132,38 @@ class TableType(Enum): VIEW = "VIEW" +@dataclass +class TagKeyValue: + key: Optional[str] = None + """name of the tag""" + + value: Optional[str] = None + """value of the tag associated with the key, could be optional""" + + def as_dict(self) -> dict: + """Serializes the TagKeyValue into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.key is not None: + body["key"] = self.key + if self.value is not None: + body["value"] = self.value + return body + + def as_shallow_dict(self) -> dict: + """Serializes the TagKeyValue into a shallow dictionary of its immediate attributes.""" + body = {} + if self.key is not None: + body["key"] = self.key + if self.value is not None: + body["value"] = self.value + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> TagKeyValue: + """Deserializes the TagKeyValue from a dictionary.""" + return cls(key=d.get("key", None), value=d.get("value", None)) + + @dataclass class TemporaryCredentials: aws_temp_credentials: Optional[AwsCredentials] = None @@ -9446,6 +9480,9 @@ class ValidateCredentialRequest: credential_name: Optional[str] = None """Required. The name of an existing credential or long-lived cloud credential to validate.""" + databricks_gcp_service_account: Optional[DatabricksGcpServiceAccount] = None + """GCP long-lived credential. Databricks-created Google Cloud Storage service account.""" + external_location_name: Optional[str] = None """The name of an existing external location to validate. Only applicable for storage credentials (purpose is **STORAGE**.)""" @@ -9469,6 +9506,8 @@ def as_dict(self) -> dict: body["azure_managed_identity"] = self.azure_managed_identity.as_dict() if self.credential_name is not None: body["credential_name"] = self.credential_name + if self.databricks_gcp_service_account: + body["databricks_gcp_service_account"] = self.databricks_gcp_service_account.as_dict() if self.external_location_name is not None: body["external_location_name"] = self.external_location_name if self.purpose is not None: @@ -9488,6 +9527,8 @@ def as_shallow_dict(self) -> dict: body["azure_managed_identity"] = self.azure_managed_identity if self.credential_name is not None: body["credential_name"] = self.credential_name + if self.databricks_gcp_service_account: + body["databricks_gcp_service_account"] = self.databricks_gcp_service_account if self.external_location_name is not None: body["external_location_name"] = self.external_location_name if self.purpose is not None: @@ -9505,6 +9546,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ValidateCredentialRequest: aws_iam_role=_from_dict(d, "aws_iam_role", AwsIamRole), azure_managed_identity=_from_dict(d, "azure_managed_identity", AzureManagedIdentity), credential_name=d.get("credential_name", None), + databricks_gcp_service_account=_from_dict(d, "databricks_gcp_service_account", DatabricksGcpServiceAccount), external_location_name=d.get("external_location_name", None), purpose=_enum(d, "purpose", CredentialPurpose), read_only=d.get("read_only", None), @@ -11137,6 +11179,7 @@ def validate_credential( aws_iam_role: Optional[AwsIamRole] = None, azure_managed_identity: Optional[AzureManagedIdentity] = None, credential_name: Optional[str] = None, + databricks_gcp_service_account: Optional[DatabricksGcpServiceAccount] = None, external_location_name: Optional[str] = None, purpose: Optional[CredentialPurpose] = None, read_only: Optional[bool] = None, @@ -11164,6 +11207,8 @@ def validate_credential( The Azure managed identity configuration. :param credential_name: str (optional) Required. The name of an existing credential or long-lived cloud credential to validate. + :param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccount` (optional) + GCP long-lived credential. Databricks-created Google Cloud Storage service account. :param external_location_name: str (optional) The name of an existing external location to validate. Only applicable for storage credentials (purpose is **STORAGE**.) @@ -11184,6 +11229,8 @@ def validate_credential( body["azure_managed_identity"] = azure_managed_identity.as_dict() if credential_name is not None: body["credential_name"] = credential_name + if databricks_gcp_service_account is not None: + body["databricks_gcp_service_account"] = databricks_gcp_service_account.as_dict() if external_location_name is not None: body["external_location_name"] = external_location_name if purpose is not None: diff --git a/databricks/sdk/service/cleanrooms.py b/databricks/sdk/service/cleanrooms.py index b9b1f5dc1..e551d82be 100755 --- a/databricks/sdk/service/cleanrooms.py +++ b/databricks/sdk/service/cleanrooms.py @@ -400,7 +400,7 @@ class CleanRoomAssetTableLocalDetails: """The fully qualified name of the table in its owner's local metastore, in the format of *catalog*.*schema*.*table_name*""" - partitions: Optional[List[sharing.PartitionSpecificationPartition]] = None + partitions: Optional[List[sharing.Partition]] = None """Partition filtering specification for a shared table.""" def as_dict(self) -> dict: @@ -424,10 +424,7 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, Any]) -> CleanRoomAssetTableLocalDetails: """Deserializes the CleanRoomAssetTableLocalDetails from a dictionary.""" - return cls( - local_name=d.get("local_name", None), - partitions=_repeated_dict(d, "partitions", sharing.PartitionSpecificationPartition), - ) + return cls(local_name=d.get("local_name", None), partitions=_repeated_dict(d, "partitions", sharing.Partition)) @dataclass @@ -1270,7 +1267,7 @@ def list( :param notebook_name: str (optional) Notebook name :param page_size: int (optional) - The maximum number of task runs to return + The maximum number of task runs to return. Currently ignored - all runs will be returned. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. diff --git a/databricks/sdk/service/compute.py b/databricks/sdk/service/compute.py index 277fa876c..1a46811bf 100755 --- a/databricks/sdk/service/compute.py +++ b/databricks/sdk/service/compute.py @@ -739,9 +739,9 @@ class ClusterAttributes: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -793,7 +793,7 @@ class ClusterAttributes: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -803,8 +803,15 @@ class ClusterAttributes: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -851,7 +858,7 @@ class ClusterAttributes: be specified.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -1121,9 +1128,9 @@ class ClusterDetails: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -1195,7 +1202,7 @@ class ClusterDetails: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -1209,8 +1216,15 @@ class ClusterDetails: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" last_restarted_time: Optional[int] = None """the timestamp that the cluster was started/restarted""" @@ -1305,7 +1319,7 @@ class ClusterDetails: a `TERMINATING` or `TERMINATED` state.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -2281,9 +2295,9 @@ class ClusterSpec: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -2335,7 +2349,7 @@ class ClusterSpec: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -2345,8 +2359,15 @@ class ClusterSpec: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -2407,7 +2428,7 @@ class ClusterSpec: be specified.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -2771,9 +2792,9 @@ class CreateCluster: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -2825,7 +2846,7 @@ class CreateCluster: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -2835,8 +2856,15 @@ class CreateCluster: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -2893,7 +2921,7 @@ class CreateCluster: be specified.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -3561,9 +3589,9 @@ class DataPlaneEventDetailsEventType(Enum): class DataSecurityMode(Enum): """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -4059,9 +4087,9 @@ class EditCluster: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -4113,7 +4141,7 @@ class EditCluster: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -4123,8 +4151,15 @@ class EditCluster: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -4181,7 +4216,7 @@ class EditCluster: be specified.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -6863,8 +6898,15 @@ class Kind(Enum): Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" CLASSIC_PREVIEW = "CLASSIC_PREVIEW" @@ -9067,9 +9109,9 @@ class UpdateClusterResource: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * - `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. + * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for @@ -9121,7 +9163,7 @@ class UpdateClusterResource: """The optional ID of the instance pool to which the cluster belongs.""" is_single_node: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers`""" @@ -9131,8 +9173,15 @@ class UpdateClusterResource: Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = - CLASSIC_PREVIEW`.""" + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -9193,7 +9242,7 @@ class UpdateClusterResource: be specified.""" use_ml_runtime: Optional[bool] = None - """This field can only be used with `kind`. + """This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" @@ -10012,8 +10061,8 @@ def create( :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. @@ -10057,7 +10106,7 @@ def create( :param instance_pool_id: str (optional) The optional ID of the instance pool to which the cluster belongs. :param is_single_node: bool (optional) - This field can only be used with `kind`. + This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers` @@ -10066,7 +10115,15 @@ def create( Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = CLASSIC_PREVIEW`. + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute @@ -10114,7 +10171,7 @@ def create( private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified. :param use_ml_runtime: bool (optional) - This field can only be used with `kind`. + This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not. @@ -10390,8 +10447,8 @@ def edit( :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. @@ -10435,7 +10492,7 @@ def edit( :param instance_pool_id: str (optional) The optional ID of the instance pool to which the cluster belongs. :param is_single_node: bool (optional) - This field can only be used with `kind`. + This field can only be used when `kind = CLASSIC_PREVIEW`. When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers` @@ -10444,7 +10501,15 @@ def edit( Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = CLASSIC_PREVIEW`. + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute @@ -10492,7 +10557,7 @@ def edit( private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified. :param use_ml_runtime: bool (optional) - This field can only be used with `kind`. + This field can only be used when `kind = CLASSIC_PREVIEW`. `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not. @@ -11563,7 +11628,9 @@ def delete(self, script_id: str): """ - headers = {} + headers = { + "Accept": "application/json", + } self._api.do("DELETE", f"/api/2.0/global-init-scripts/{script_id}", headers=headers) @@ -11642,6 +11709,7 @@ def update( if script is not None: body["script"] = script headers = { + "Accept": "application/json", "Content-Type": "application/json", } diff --git a/databricks/sdk/service/dashboards.py b/databricks/sdk/service/dashboards.py index 8b976f54c..b1e915640 100755 --- a/databricks/sdk/service/dashboards.py +++ b/databricks/sdk/service/dashboards.py @@ -242,27 +242,6 @@ class DashboardView(Enum): DASHBOARD_VIEW_BASIC = "DASHBOARD_VIEW_BASIC" -class DataType(Enum): - - DATA_TYPE_ARRAY = "DATA_TYPE_ARRAY" - DATA_TYPE_BIG_INT = "DATA_TYPE_BIG_INT" - DATA_TYPE_BINARY = "DATA_TYPE_BINARY" - DATA_TYPE_BOOLEAN = "DATA_TYPE_BOOLEAN" - DATA_TYPE_DATE = "DATA_TYPE_DATE" - DATA_TYPE_DECIMAL = "DATA_TYPE_DECIMAL" - DATA_TYPE_DOUBLE = "DATA_TYPE_DOUBLE" - DATA_TYPE_FLOAT = "DATA_TYPE_FLOAT" - DATA_TYPE_INT = "DATA_TYPE_INT" - DATA_TYPE_INTERVAL = "DATA_TYPE_INTERVAL" - DATA_TYPE_MAP = "DATA_TYPE_MAP" - DATA_TYPE_SMALL_INT = "DATA_TYPE_SMALL_INT" - DATA_TYPE_STRING = "DATA_TYPE_STRING" - DATA_TYPE_STRUCT = "DATA_TYPE_STRUCT" - DATA_TYPE_TIMESTAMP = "DATA_TYPE_TIMESTAMP" - DATA_TYPE_TINY_INT = "DATA_TYPE_TINY_INT" - DATA_TYPE_VOID = "DATA_TYPE_VOID" - - @dataclass class DeleteScheduleResponse: def as_dict(self) -> dict: @@ -391,13 +370,20 @@ def from_dict(cls, d: Dict[str, Any]) -> ExecuteQueryResponse: class GenieAttachment: """Genie AI Response""" - query: Optional[QueryAttachment] = None + attachment_id: Optional[str] = None + """Attachment ID""" + + query: Optional[GenieQueryAttachment] = None + """Query Attachment if Genie responds with a SQL query""" text: Optional[TextAttachment] = None + """Text Attachment if Genie responds with text""" def as_dict(self) -> dict: """Serializes the GenieAttachment into a dictionary suitable for use as a JSON request body.""" body = {} + if self.attachment_id is not None: + body["attachment_id"] = self.attachment_id if self.query: body["query"] = self.query.as_dict() if self.text: @@ -407,6 +393,8 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the GenieAttachment into a shallow dictionary of its immediate attributes.""" body = {} + if self.attachment_id is not None: + body["attachment_id"] = self.attachment_id if self.query: body["query"] = self.query if self.text: @@ -416,13 +404,17 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, Any]) -> GenieAttachment: """Deserializes the GenieAttachment from a dictionary.""" - return cls(query=_from_dict(d, "query", QueryAttachment), text=_from_dict(d, "text", TextAttachment)) + return cls( + attachment_id=d.get("attachment_id", None), + query=_from_dict(d, "query", GenieQueryAttachment), + text=_from_dict(d, "text", TextAttachment), + ) @dataclass class GenieConversation: id: str - """Conversation ID""" + """Conversation ID. Legacy identifier, use conversation_id instead""" space_id: str """Genie space ID""" @@ -433,6 +425,9 @@ class GenieConversation: title: str """Conversation title""" + conversation_id: str + """Conversation ID""" + created_timestamp: Optional[int] = None """Timestamp when the message was created""" @@ -442,6 +437,8 @@ class GenieConversation: def as_dict(self) -> dict: """Serializes the GenieConversation into a dictionary suitable for use as a JSON request body.""" body = {} + if self.conversation_id is not None: + body["conversation_id"] = self.conversation_id if self.created_timestamp is not None: body["created_timestamp"] = self.created_timestamp if self.id is not None: @@ -459,6 +456,8 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the GenieConversation into a shallow dictionary of its immediate attributes.""" body = {} + if self.conversation_id is not None: + body["conversation_id"] = self.conversation_id if self.created_timestamp is not None: body["created_timestamp"] = self.created_timestamp if self.id is not None: @@ -477,6 +476,7 @@ def as_shallow_dict(self) -> dict: def from_dict(cls, d: Dict[str, Any]) -> GenieConversation: """Deserializes the GenieConversation from a dictionary.""" return cls( + conversation_id=d.get("conversation_id", None), created_timestamp=d.get("created_timestamp", None), id=d.get("id", None), last_updated_timestamp=d.get("last_updated_timestamp", None), @@ -558,7 +558,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieGetMessageQueryResultResponse: @dataclass class GenieMessage: id: str - """Message ID""" + """Message ID. Legacy identifier, use message_id instead""" space_id: str """Genie space ID""" @@ -569,35 +569,37 @@ class GenieMessage: content: str """User message content""" + message_id: str + """Message ID""" + attachments: Optional[List[GenieAttachment]] = None - """AI produced response to the message""" + """AI-generated response to the message""" created_timestamp: Optional[int] = None """Timestamp when the message was created""" error: Optional[MessageError] = None - """Error message if AI failed to respond to the message""" + """Error message if Genie failed to respond to the message""" last_updated_timestamp: Optional[int] = None """Timestamp when the message was last updated""" query_result: Optional[Result] = None - """The result of SQL query if the message has a query attachment""" + """The result of SQL query if the message includes a query attachment. Deprecated. Use + `query_result_metadata` in `GenieQueryAttachment` instead.""" status: Optional[MessageStatus] = None - """MesssageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data + """MessageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data sources. * `FILTERING_CONTEXT`: Running smart context step to determine relevant context. * - `ASKING_AI`: Waiting for the LLM to respond to the users question. * `PENDING_WAREHOUSE`: - Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing - AI provided SQL query. Get the SQL query result by calling - [getMessageQueryResult](:method:genie/getMessageQueryResult) API. **Important: The message - status will stay in the `EXECUTING_QUERY` until a client calls - [getMessageQueryResult](:method:genie/getMessageQueryResult)**. * `FAILED`: Generating a - response or the executing the query failed. Please see `error` field. * `COMPLETED`: Message - processing is completed. Results are in the `attachments` field. Get the SQL query result by - calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message - has been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user - needs to execute the query again. * `CANCELLED`: Message has been cancelled.""" + `ASKING_AI`: Waiting for the LLM to respond to the user's question. * `PENDING_WAREHOUSE`: + Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing a + generated SQL query. Get the SQL query result by calling + [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `FAILED`: The response + generation or query execution failed. See `error` field. * `COMPLETED`: Message processing is + completed. Results are in the `attachments` field. Get the SQL query result by calling + [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message has + been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user needs to + rerun the query. * `CANCELLED`: Message has been cancelled.""" user_id: Optional[int] = None """ID of the user who created the message""" @@ -619,6 +621,8 @@ def as_dict(self) -> dict: body["id"] = self.id if self.last_updated_timestamp is not None: body["last_updated_timestamp"] = self.last_updated_timestamp + if self.message_id is not None: + body["message_id"] = self.message_id if self.query_result: body["query_result"] = self.query_result.as_dict() if self.space_id is not None: @@ -646,6 +650,8 @@ def as_shallow_dict(self) -> dict: body["id"] = self.id if self.last_updated_timestamp is not None: body["last_updated_timestamp"] = self.last_updated_timestamp + if self.message_id is not None: + body["message_id"] = self.message_id if self.query_result: body["query_result"] = self.query_result if self.space_id is not None: @@ -667,6 +673,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieMessage: error=_from_dict(d, "error", MessageError), id=d.get("id", None), last_updated_timestamp=d.get("last_updated_timestamp", None), + message_id=d.get("message_id", None), query_result=_from_dict(d, "query_result", Result), space_id=d.get("space_id", None), status=_enum(d, "status", MessageStatus), @@ -674,6 +681,143 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieMessage: ) +@dataclass +class GenieQueryAttachment: + description: Optional[str] = None + """Description of the query""" + + id: Optional[str] = None + + last_updated_timestamp: Optional[int] = None + """Time when the user updated the query last""" + + query: Optional[str] = None + """AI generated SQL query""" + + query_result_metadata: Optional[GenieResultMetadata] = None + """Metadata associated with the query result.""" + + title: Optional[str] = None + """Name of the query""" + + def as_dict(self) -> dict: + """Serializes the GenieQueryAttachment into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.description is not None: + body["description"] = self.description + if self.id is not None: + body["id"] = self.id + if self.last_updated_timestamp is not None: + body["last_updated_timestamp"] = self.last_updated_timestamp + if self.query is not None: + body["query"] = self.query + if self.query_result_metadata: + body["query_result_metadata"] = self.query_result_metadata.as_dict() + if self.title is not None: + body["title"] = self.title + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GenieQueryAttachment into a shallow dictionary of its immediate attributes.""" + body = {} + if self.description is not None: + body["description"] = self.description + if self.id is not None: + body["id"] = self.id + if self.last_updated_timestamp is not None: + body["last_updated_timestamp"] = self.last_updated_timestamp + if self.query is not None: + body["query"] = self.query + if self.query_result_metadata: + body["query_result_metadata"] = self.query_result_metadata + if self.title is not None: + body["title"] = self.title + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GenieQueryAttachment: + """Deserializes the GenieQueryAttachment from a dictionary.""" + return cls( + description=d.get("description", None), + id=d.get("id", None), + last_updated_timestamp=d.get("last_updated_timestamp", None), + query=d.get("query", None), + query_result_metadata=_from_dict(d, "query_result_metadata", GenieResultMetadata), + title=d.get("title", None), + ) + + +@dataclass +class GenieResultMetadata: + is_truncated: Optional[bool] = None + """Indicates whether the result set is truncated.""" + + row_count: Optional[int] = None + """The number of rows in the result set.""" + + def as_dict(self) -> dict: + """Serializes the GenieResultMetadata into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.is_truncated is not None: + body["is_truncated"] = self.is_truncated + if self.row_count is not None: + body["row_count"] = self.row_count + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GenieResultMetadata into a shallow dictionary of its immediate attributes.""" + body = {} + if self.is_truncated is not None: + body["is_truncated"] = self.is_truncated + if self.row_count is not None: + body["row_count"] = self.row_count + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GenieResultMetadata: + """Deserializes the GenieResultMetadata from a dictionary.""" + return cls(is_truncated=d.get("is_truncated", None), row_count=d.get("row_count", None)) + + +@dataclass +class GenieSpace: + space_id: str + """Space ID""" + + title: str + """Title of the Genie Space""" + + description: Optional[str] = None + """Description of the Genie Space""" + + def as_dict(self) -> dict: + """Serializes the GenieSpace into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.description is not None: + body["description"] = self.description + if self.space_id is not None: + body["space_id"] = self.space_id + if self.title is not None: + body["title"] = self.title + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GenieSpace into a shallow dictionary of its immediate attributes.""" + body = {} + if self.description is not None: + body["description"] = self.description + if self.space_id is not None: + body["space_id"] = self.space_id + if self.title is not None: + body["title"] = self.title + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GenieSpace: + """Deserializes the GenieSpace from a dictionary.""" + return cls(description=d.get("description", None), space_id=d.get("space_id", None), title=d.get("title", None)) + + @dataclass class GenieStartConversationMessageRequest: content: str @@ -923,6 +1067,7 @@ class MessageErrorType(Enum): FUNCTIONS_NOT_AVAILABLE_EXCEPTION = "FUNCTIONS_NOT_AVAILABLE_EXCEPTION" FUNCTION_ARGUMENTS_INVALID_EXCEPTION = "FUNCTION_ARGUMENTS_INVALID_EXCEPTION" FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION = "FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION" + FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION = "FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION" FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION = "FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION" GENERIC_CHAT_COMPLETION_EXCEPTION = "GENERIC_CHAT_COMPLETION_EXCEPTION" GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION = "GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION" @@ -935,6 +1080,7 @@ class MessageErrorType(Enum): INVALID_FUNCTION_CALL_EXCEPTION = "INVALID_FUNCTION_CALL_EXCEPTION" INVALID_TABLE_IDENTIFIER_EXCEPTION = "INVALID_TABLE_IDENTIFIER_EXCEPTION" LOCAL_CONTEXT_EXCEEDED_EXCEPTION = "LOCAL_CONTEXT_EXCEEDED_EXCEPTION" + MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION = "MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION" MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION = "MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION" MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION = "MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION" NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE = "NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE" @@ -956,19 +1102,17 @@ class MessageErrorType(Enum): class MessageStatus(Enum): - """MesssageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data + """MessageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data sources. * `FILTERING_CONTEXT`: Running smart context step to determine relevant context. * - `ASKING_AI`: Waiting for the LLM to respond to the users question. * `PENDING_WAREHOUSE`: - Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing - AI provided SQL query. Get the SQL query result by calling - [getMessageQueryResult](:method:genie/getMessageQueryResult) API. **Important: The message - status will stay in the `EXECUTING_QUERY` until a client calls - [getMessageQueryResult](:method:genie/getMessageQueryResult)**. * `FAILED`: Generating a - response or the executing the query failed. Please see `error` field. * `COMPLETED`: Message - processing is completed. Results are in the `attachments` field. Get the SQL query result by - calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message - has been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user - needs to execute the query again. * `CANCELLED`: Message has been cancelled.""" + `ASKING_AI`: Waiting for the LLM to respond to the user's question. * `PENDING_WAREHOUSE`: + Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing a + generated SQL query. Get the SQL query result by calling + [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `FAILED`: The response + generation or query execution failed. See `error` field. * `COMPLETED`: Message processing is + completed. Results are in the `attachments` field. Get the SQL query result by calling + [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message has + been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user needs to + rerun the query. * `CANCELLED`: Message has been cancelled.""" ASKING_AI = "ASKING_AI" CANCELLED = "CANCELLED" @@ -1203,95 +1347,6 @@ def from_dict(cls, d: Dict[str, Any]) -> PublishedDashboard: ) -@dataclass -class QueryAttachment: - cached_query_schema: Optional[QuerySchema] = None - - description: Optional[str] = None - """Description of the query""" - - id: Optional[str] = None - - instruction_id: Optional[str] = None - """If the query was created on an instruction (trusted asset) we link to the id""" - - instruction_title: Optional[str] = None - """Always store the title next to the id in case the original instruction title changes or the - instruction is deleted.""" - - last_updated_timestamp: Optional[int] = None - """Time when the user updated the query last""" - - query: Optional[str] = None - """AI generated SQL query""" - - statement_id: Optional[str] = None - - title: Optional[str] = None - """Name of the query""" - - def as_dict(self) -> dict: - """Serializes the QueryAttachment into a dictionary suitable for use as a JSON request body.""" - body = {} - if self.cached_query_schema: - body["cached_query_schema"] = self.cached_query_schema.as_dict() - if self.description is not None: - body["description"] = self.description - if self.id is not None: - body["id"] = self.id - if self.instruction_id is not None: - body["instruction_id"] = self.instruction_id - if self.instruction_title is not None: - body["instruction_title"] = self.instruction_title - if self.last_updated_timestamp is not None: - body["last_updated_timestamp"] = self.last_updated_timestamp - if self.query is not None: - body["query"] = self.query - if self.statement_id is not None: - body["statement_id"] = self.statement_id - if self.title is not None: - body["title"] = self.title - return body - - def as_shallow_dict(self) -> dict: - """Serializes the QueryAttachment into a shallow dictionary of its immediate attributes.""" - body = {} - if self.cached_query_schema: - body["cached_query_schema"] = self.cached_query_schema - if self.description is not None: - body["description"] = self.description - if self.id is not None: - body["id"] = self.id - if self.instruction_id is not None: - body["instruction_id"] = self.instruction_id - if self.instruction_title is not None: - body["instruction_title"] = self.instruction_title - if self.last_updated_timestamp is not None: - body["last_updated_timestamp"] = self.last_updated_timestamp - if self.query is not None: - body["query"] = self.query - if self.statement_id is not None: - body["statement_id"] = self.statement_id - if self.title is not None: - body["title"] = self.title - return body - - @classmethod - def from_dict(cls, d: Dict[str, Any]) -> QueryAttachment: - """Deserializes the QueryAttachment from a dictionary.""" - return cls( - cached_query_schema=_from_dict(d, "cached_query_schema", QuerySchema), - description=d.get("description", None), - id=d.get("id", None), - instruction_id=d.get("instruction_id", None), - instruction_title=d.get("instruction_title", None), - last_updated_timestamp=d.get("last_updated_timestamp", None), - query=d.get("query", None), - statement_id=d.get("statement_id", None), - title=d.get("title", None), - ) - - @dataclass class QueryResponseStatus: canceled: Optional[Empty] = None @@ -1353,78 +1408,6 @@ def from_dict(cls, d: Dict[str, Any]) -> QueryResponseStatus: ) -@dataclass -class QuerySchema: - columns: Optional[List[QuerySchemaColumn]] = None - - statement_id: Optional[str] = None - """Used to determine if the stored query schema is compatible with the latest run. The service - should always clear the schema when the query is re-executed.""" - - def as_dict(self) -> dict: - """Serializes the QuerySchema into a dictionary suitable for use as a JSON request body.""" - body = {} - if self.columns: - body["columns"] = [v.as_dict() for v in self.columns] - if self.statement_id is not None: - body["statement_id"] = self.statement_id - return body - - def as_shallow_dict(self) -> dict: - """Serializes the QuerySchema into a shallow dictionary of its immediate attributes.""" - body = {} - if self.columns: - body["columns"] = self.columns - if self.statement_id is not None: - body["statement_id"] = self.statement_id - return body - - @classmethod - def from_dict(cls, d: Dict[str, Any]) -> QuerySchema: - """Deserializes the QuerySchema from a dictionary.""" - return cls(columns=_repeated_dict(d, "columns", QuerySchemaColumn), statement_id=d.get("statement_id", None)) - - -@dataclass -class QuerySchemaColumn: - name: str - - type_text: str - """Corresponds to type desc""" - - data_type: DataType - """Populated from https://docs.databricks.com/sql/language-manual/sql-ref-datatypes.html""" - - def as_dict(self) -> dict: - """Serializes the QuerySchemaColumn into a dictionary suitable for use as a JSON request body.""" - body = {} - if self.data_type is not None: - body["data_type"] = self.data_type.value - if self.name is not None: - body["name"] = self.name - if self.type_text is not None: - body["type_text"] = self.type_text - return body - - def as_shallow_dict(self) -> dict: - """Serializes the QuerySchemaColumn into a shallow dictionary of its immediate attributes.""" - body = {} - if self.data_type is not None: - body["data_type"] = self.data_type - if self.name is not None: - body["name"] = self.name - if self.type_text is not None: - body["type_text"] = self.type_text - return body - - @classmethod - def from_dict(cls, d: Dict[str, Any]) -> QuerySchemaColumn: - """Deserializes the QuerySchemaColumn from a dictionary.""" - return cls( - data_type=_enum(d, "data_type", DataType), name=d.get("name", None), type_text=d.get("type_text", None) - ) - - @dataclass class Result: is_truncated: Optional[bool] = None @@ -1886,7 +1869,7 @@ def wait_get_message_genie_completed( def create_message(self, space_id: str, conversation_id: str, content: str) -> Wait[GenieMessage]: """Create conversation message. - Create new message in [conversation](:method:genie/startconversation). The AI response uses all + Create new message in a [conversation](:method:genie/startconversation). The AI response uses all previously created messages in the conversation to respond. :param space_id: str @@ -1929,6 +1912,36 @@ def create_message_and_wait( timeout=timeout ) + def execute_message_attachment_query( + self, space_id: str, conversation_id: str, message_id: str, attachment_id: str + ) -> GenieGetMessageQueryResultResponse: + """Execute message attachment SQL query. + + Execute the SQL for a message query attachment. + + :param space_id: str + Genie space ID + :param conversation_id: str + Conversation ID + :param message_id: str + Message ID + :param attachment_id: str + Attachment ID + + :returns: :class:`GenieGetMessageQueryResultResponse` + """ + + headers = { + "Accept": "application/json", + } + + res = self._api.do( + "POST", + f"/api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/execute-query", + headers=headers, + ) + return GenieGetMessageQueryResultResponse.from_dict(res) + def execute_message_query( self, space_id: str, conversation_id: str, message_id: str ) -> GenieGetMessageQueryResultResponse: @@ -1983,10 +1996,41 @@ def get_message(self, space_id: str, conversation_id: str, message_id: str) -> G ) return GenieMessage.from_dict(res) + def get_message_attachment_query_result( + self, space_id: str, conversation_id: str, message_id: str, attachment_id: str + ) -> GenieGetMessageQueryResultResponse: + """Get message attachment SQL query result. + + Get the result of SQL query if the message has a query attachment. This is only available if a message + has a query attachment and the message status is `EXECUTING_QUERY` OR `COMPLETED`. + + :param space_id: str + Genie space ID + :param conversation_id: str + Conversation ID + :param message_id: str + Message ID + :param attachment_id: str + Attachment ID + + :returns: :class:`GenieGetMessageQueryResultResponse` + """ + + headers = { + "Accept": "application/json", + } + + res = self._api.do( + "GET", + f"/api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result", + headers=headers, + ) + return GenieGetMessageQueryResultResponse.from_dict(res) + def get_message_query_result( self, space_id: str, conversation_id: str, message_id: str ) -> GenieGetMessageQueryResultResponse: - """Get conversation message SQL query result. + """[Deprecated] Get conversation message SQL query result. Get the result of SQL query if the message has a query attachment. This is only available if a message has a query attachment and the message status is `EXECUTING_QUERY`. @@ -2015,10 +2059,10 @@ def get_message_query_result( def get_message_query_result_by_attachment( self, space_id: str, conversation_id: str, message_id: str, attachment_id: str ) -> GenieGetMessageQueryResultResponse: - """Get conversation message SQL query result by attachment id. + """[deprecated] Get conversation message SQL query result. - Get the result of SQL query by attachment id This is only available if a message has a query - attachment and the message status is `EXECUTING_QUERY`. + Get the result of SQL query if the message has a query attachment. This is only available if a message + has a query attachment and the message status is `EXECUTING_QUERY` OR `COMPLETED`. :param space_id: str Genie space ID @@ -2043,6 +2087,24 @@ def get_message_query_result_by_attachment( ) return GenieGetMessageQueryResultResponse.from_dict(res) + def get_space(self, space_id: str) -> GenieSpace: + """Get details of a Genie Space. + + Get a Genie Space. + + :param space_id: str + The ID associated with the Genie space + + :returns: :class:`GenieSpace` + """ + + headers = { + "Accept": "application/json", + } + + res = self._api.do("GET", f"/api/2.0/genie/spaces/{space_id}", headers=headers) + return GenieSpace.from_dict(res) + def start_conversation(self, space_id: str, content: str) -> Wait[GenieMessage]: """Start conversation. diff --git a/databricks/sdk/service/jobs.py b/databricks/sdk/service/jobs.py index 8ddd11afc..6a19b8980 100755 --- a/databricks/sdk/service/jobs.py +++ b/databricks/sdk/service/jobs.py @@ -126,9 +126,8 @@ class BaseRun: effective_performance_target: Optional[PerformanceTarget] = None """effective_performance_target is the actual performance target used by the run during execution. - effective_performance_target can differ from performance_target depending on if the job was - eligible to be cost-optimized (e.g. contains at least 1 serverless task) or if we specifically - override the value for the run (ex. RunNow).""" + effective_performance_target can differ from the client-set performance_target depending on if + the job was eligible to be cost-optimized.""" end_time: Optional[int] = None """The time at which this run ended in epoch milliseconds (milliseconds since 1/1/1970 UTC). This @@ -792,6 +791,51 @@ def from_dict(cls, d: Dict[str, Any]) -> ClusterSpec: ) +@dataclass +class ComputeConfig: + """Next field: 4""" + + num_gpus: int + """Number of GPUs.""" + + gpu_node_pool_id: str + """IDof the GPU pool to use.""" + + gpu_type: Optional[str] = None + """GPU type.""" + + def as_dict(self) -> dict: + """Serializes the ComputeConfig into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.gpu_node_pool_id is not None: + body["gpu_node_pool_id"] = self.gpu_node_pool_id + if self.gpu_type is not None: + body["gpu_type"] = self.gpu_type + if self.num_gpus is not None: + body["num_gpus"] = self.num_gpus + return body + + def as_shallow_dict(self) -> dict: + """Serializes the ComputeConfig into a shallow dictionary of its immediate attributes.""" + body = {} + if self.gpu_node_pool_id is not None: + body["gpu_node_pool_id"] = self.gpu_node_pool_id + if self.gpu_type is not None: + body["gpu_type"] = self.gpu_type + if self.num_gpus is not None: + body["num_gpus"] = self.num_gpus + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> ComputeConfig: + """Deserializes the ComputeConfig from a dictionary.""" + return cls( + gpu_node_pool_id=d.get("gpu_node_pool_id", None), + gpu_type=d.get("gpu_type", None), + num_gpus=d.get("num_gpus", None), + ) + + class Condition(Enum): ALL_UPDATED = "ALL_UPDATED" @@ -1835,6 +1879,100 @@ class Format(Enum): SINGLE_TASK = "SINGLE_TASK" +@dataclass +class GenAiComputeTask: + """Next field: 9""" + + dl_runtime_image: str + """Runtime image""" + + command: Optional[str] = None + """Command launcher to run the actual script, e.g. bash, python etc.""" + + compute: Optional[ComputeConfig] = None + """Next field: 4""" + + mlflow_experiment_name: Optional[str] = None + """Optional string containing the name of the MLflow experiment to log the run to. If name is not + found, backend will create the mlflow experiment using the name.""" + + source: Optional[Source] = None + """Optional location type of the training script. When set to `WORKSPACE`, the script will be + retrieved from the local Databricks workspace. When set to `GIT`, the script will be retrieved + from a Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if + `git_source` is defined and `WORKSPACE` otherwise. * `WORKSPACE`: Script is located in + Databricks workspace. * `GIT`: Script is located in cloud Git provider.""" + + training_script_path: Optional[str] = None + """The training script file path to be executed. Cloud file URIs (such as dbfs:/, s3:/, adls:/, + gcs:/) and workspace paths are supported. For python files stored in the Databricks workspace, + the path must be absolute and begin with `/`. For files stored in a remote repository, the path + must be relative. This field is required.""" + + yaml_parameters: Optional[str] = None + """Optional string containing model parameters passed to the training script in yaml format. If + present, then the content in yaml_parameters_file_path will be ignored.""" + + yaml_parameters_file_path: Optional[str] = None + """Optional path to a YAML file containing model parameters passed to the training script.""" + + def as_dict(self) -> dict: + """Serializes the GenAiComputeTask into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.command is not None: + body["command"] = self.command + if self.compute: + body["compute"] = self.compute.as_dict() + if self.dl_runtime_image is not None: + body["dl_runtime_image"] = self.dl_runtime_image + if self.mlflow_experiment_name is not None: + body["mlflow_experiment_name"] = self.mlflow_experiment_name + if self.source is not None: + body["source"] = self.source.value + if self.training_script_path is not None: + body["training_script_path"] = self.training_script_path + if self.yaml_parameters is not None: + body["yaml_parameters"] = self.yaml_parameters + if self.yaml_parameters_file_path is not None: + body["yaml_parameters_file_path"] = self.yaml_parameters_file_path + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GenAiComputeTask into a shallow dictionary of its immediate attributes.""" + body = {} + if self.command is not None: + body["command"] = self.command + if self.compute: + body["compute"] = self.compute + if self.dl_runtime_image is not None: + body["dl_runtime_image"] = self.dl_runtime_image + if self.mlflow_experiment_name is not None: + body["mlflow_experiment_name"] = self.mlflow_experiment_name + if self.source is not None: + body["source"] = self.source + if self.training_script_path is not None: + body["training_script_path"] = self.training_script_path + if self.yaml_parameters is not None: + body["yaml_parameters"] = self.yaml_parameters + if self.yaml_parameters_file_path is not None: + body["yaml_parameters_file_path"] = self.yaml_parameters_file_path + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GenAiComputeTask: + """Deserializes the GenAiComputeTask from a dictionary.""" + return cls( + command=d.get("command", None), + compute=_from_dict(d, "compute", ComputeConfig), + dl_runtime_image=d.get("dl_runtime_image", None), + mlflow_experiment_name=d.get("mlflow_experiment_name", None), + source=_enum(d, "source", Source), + training_script_path=d.get("training_script_path", None), + yaml_parameters=d.get("yaml_parameters", None), + yaml_parameters_file_path=d.get("yaml_parameters_file_path", None), + ) + + @dataclass class GetJobPermissionLevelsResponse: permission_levels: Optional[List[JobPermissionsDescription]] = None @@ -4404,9 +4542,8 @@ class Run: effective_performance_target: Optional[PerformanceTarget] = None """effective_performance_target is the actual performance target used by the run during execution. - effective_performance_target can differ from performance_target depending on if the job was - eligible to be cost-optimized (e.g. contains at least 1 serverless task) or if we specifically - override the value for the run (ex. RunNow).""" + effective_performance_target can differ from the client-set performance_target depending on if + the job was eligible to be cost-optimized.""" end_time: Optional[int] = None """The time at which this run ended in epoch milliseconds (milliseconds since 1/1/1970 UTC). This @@ -5066,6 +5203,7 @@ class RunLifecycleStateV2State(Enum): RUNNING = "RUNNING" TERMINATED = "TERMINATED" TERMINATING = "TERMINATING" + WAITING = "WAITING" @dataclass @@ -5128,8 +5266,8 @@ class RunNow: performance_target: Optional[PerformanceTarget] = None """PerformanceTarget defines how performant or cost efficient the execution of run on serverless - compute should be. For RunNow request, the run will execute with this settings instead of ones - defined in job.""" + compute should be. For RunNow, this performance target will override the target defined on the + job-level.""" pipeline_params: Optional[PipelineParams] = None """Controls whether the pipeline should perform a full refresh""" @@ -5739,9 +5877,8 @@ class RunTask: effective_performance_target: Optional[PerformanceTarget] = None """effective_performance_target is the actual performance target used by the run during execution. - effective_performance_target can differ from performance_target depending on if the job was - eligible to be cost-optimized (e.g. contains at least 1 serverless task) or if an override was - provided for the run (ex. RunNow).""" + effective_performance_target can differ from the client-set performance_target depending on if + the job was eligible to be cost-optimized.""" email_notifications: Optional[JobEmailNotifications] = None """An optional set of email addresses notified when the task run begins or completes. The default @@ -5771,6 +5908,9 @@ class RunTask: """The task executes a nested task for every input provided when the `for_each_task` field is present.""" + gen_ai_compute_task: Optional[GenAiComputeTask] = None + """Next field: 9""" + git_source: Optional[GitSource] = None """An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. @@ -5914,6 +6054,8 @@ def as_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task.as_dict() + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task.as_dict() if self.git_source: body["git_source"] = self.git_source.as_dict() if self.job_cluster_key is not None: @@ -6003,6 +6145,8 @@ def as_shallow_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task if self.git_source: body["git_source"] = self.git_source if self.job_cluster_key is not None: @@ -6077,6 +6221,7 @@ def from_dict(cls, d: Dict[str, Any]) -> RunTask: execution_duration=d.get("execution_duration", None), existing_cluster_id=d.get("existing_cluster_id", None), for_each_task=_from_dict(d, "for_each_task", RunForEachTask), + gen_ai_compute_task=_from_dict(d, "gen_ai_compute_task", GenAiComputeTask), git_source=_from_dict(d, "git_source", GitSource), job_cluster_key=d.get("job_cluster_key", None), libraries=_repeated_dict(d, "libraries", compute.Library), @@ -7106,6 +7251,9 @@ class SubmitTask: """The task executes a nested task for every input provided when the `for_each_task` field is present.""" + gen_ai_compute_task: Optional[GenAiComputeTask] = None + """Next field: 9""" + health: Optional[JobsHealthRules] = None """An optional set of health rules that can be defined for this job.""" @@ -7194,6 +7342,8 @@ def as_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task.as_dict() + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task.as_dict() if self.health: body["health"] = self.health.as_dict() if self.libraries: @@ -7249,6 +7399,8 @@ def as_shallow_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task if self.health: body["health"] = self.health if self.libraries: @@ -7296,6 +7448,7 @@ def from_dict(cls, d: Dict[str, Any]) -> SubmitTask: environment_key=d.get("environment_key", None), existing_cluster_id=d.get("existing_cluster_id", None), for_each_task=_from_dict(d, "for_each_task", ForEachTask), + gen_ai_compute_task=_from_dict(d, "gen_ai_compute_task", GenAiComputeTask), health=_from_dict(d, "health", JobsHealthRules), libraries=_repeated_dict(d, "libraries", compute.Library), new_cluster=_from_dict(d, "new_cluster", compute.ClusterSpec), @@ -7420,6 +7573,9 @@ class Task: """The task executes a nested task for every input provided when the `for_each_task` field is present.""" + gen_ai_compute_task: Optional[GenAiComputeTask] = None + """Next field: 9""" + health: Optional[JobsHealthRules] = None """An optional set of health rules that can be defined for this job.""" @@ -7531,6 +7687,8 @@ def as_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task.as_dict() + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task.as_dict() if self.health: body["health"] = self.health.as_dict() if self.job_cluster_key is not None: @@ -7596,6 +7754,8 @@ def as_shallow_dict(self) -> dict: body["existing_cluster_id"] = self.existing_cluster_id if self.for_each_task: body["for_each_task"] = self.for_each_task + if self.gen_ai_compute_task: + body["gen_ai_compute_task"] = self.gen_ai_compute_task if self.health: body["health"] = self.health if self.job_cluster_key is not None: @@ -7652,6 +7812,7 @@ def from_dict(cls, d: Dict[str, Any]) -> Task: environment_key=d.get("environment_key", None), existing_cluster_id=d.get("existing_cluster_id", None), for_each_task=_from_dict(d, "for_each_task", ForEachTask), + gen_ai_compute_task=_from_dict(d, "gen_ai_compute_task", GenAiComputeTask), health=_from_dict(d, "health", JobsHealthRules), job_cluster_key=d.get("job_cluster_key", None), libraries=_repeated_dict(d, "libraries", compute.Library), @@ -8399,7 +8560,6 @@ def cancel_all_runs(self, *, all_queued_runs: Optional[bool] = None, job_id: Opt if job_id is not None: body["job_id"] = job_id headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -8422,7 +8582,6 @@ def cancel_run(self, run_id: int) -> Wait[Run]: if run_id is not None: body["run_id"] = run_id headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -8634,7 +8793,6 @@ def delete(self, job_id: int): if job_id is not None: body["job_id"] = job_id headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -8654,7 +8812,6 @@ def delete_run(self, run_id: int): if run_id is not None: body["run_id"] = run_id headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -9173,7 +9330,6 @@ def reset(self, job_id: int, new_settings: JobSettings): if new_settings is not None: body["new_settings"] = new_settings.as_dict() headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -9252,8 +9408,8 @@ def run_now( will be run. :param performance_target: :class:`PerformanceTarget` (optional) PerformanceTarget defines how performant or cost efficient the execution of run on serverless - compute should be. For RunNow request, the run will execute with this settings instead of ones - defined in job. + compute should be. For RunNow, this performance target will override the target defined on the + job-level. :param pipeline_params: :class:`PipelineParams` (optional) Controls whether the pipeline should perform a full refresh :param python_named_params: Dict[str,str] (optional) @@ -9589,7 +9745,6 @@ def update( if new_settings is not None: body["new_settings"] = new_settings.as_dict() headers = { - "Accept": "application/json", "Content-Type": "application/json", } diff --git a/databricks/sdk/service/marketplace.py b/databricks/sdk/service/marketplace.py index d424cd0fa..1851bf1d6 100755 --- a/databricks/sdk/service/marketplace.py +++ b/databricks/sdk/service/marketplace.py @@ -71,6 +71,7 @@ def from_dict(cls, d: Dict[str, Any]) -> AddExchangeForListingResponse: class AssetType(Enum): + ASSET_TYPE_APP = "ASSET_TYPE_APP" ASSET_TYPE_DATA_TABLE = "ASSET_TYPE_DATA_TABLE" ASSET_TYPE_GIT_REPO = "ASSET_TYPE_GIT_REPO" ASSET_TYPE_MEDIA = "ASSET_TYPE_MEDIA" diff --git a/databricks/sdk/service/ml.py b/databricks/sdk/service/ml.py index dc29e7ef5..61a7b1bc7 100755 --- a/databricks/sdk/service/ml.py +++ b/databricks/sdk/service/ml.py @@ -744,6 +744,9 @@ class CreateRun: experiment_id: Optional[str] = None """ID of the associated experiment.""" + run_name: Optional[str] = None + """The name of the run.""" + start_time: Optional[int] = None """Unix timestamp in milliseconds of when the run started.""" @@ -759,6 +762,8 @@ def as_dict(self) -> dict: body = {} if self.experiment_id is not None: body["experiment_id"] = self.experiment_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.start_time is not None: body["start_time"] = self.start_time if self.tags: @@ -772,6 +777,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.experiment_id is not None: body["experiment_id"] = self.experiment_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.start_time is not None: body["start_time"] = self.start_time if self.tags: @@ -785,6 +792,7 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateRun: """Deserializes the CreateRun from a dictionary.""" return cls( experiment_id=d.get("experiment_id", None), + run_name=d.get("run_name", None), start_time=d.get("start_time", None), tags=_repeated_dict(d, "tags", RunTag), user_id=d.get("user_id", None), @@ -926,12 +934,22 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateWebhookResponse: @dataclass class Dataset: - digest: Optional[str] = None + """Dataset. Represents a reference to data used for training, testing, or evaluation during the + model development process.""" + + name: str + """The name of the dataset. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”""" + + digest: str """Dataset digest, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.""" - name: Optional[str] = None - """The name of the dataset. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”""" + source_type: str + """The type of the dataset source, e.g. ‘databricks-uc-table’, ‘DBFS’, ‘S3’, ...""" + + source: str + """Source information for the dataset. Note that the source may not exactly reproduce the dataset + if it was transformed / modified before use with MLflow.""" profile: Optional[str] = None """The profile of the dataset. Summary statistics for the dataset, such as the number of rows in a @@ -941,13 +959,6 @@ class Dataset: """The schema of the dataset. E.g., MLflow ColSpec JSON for a dataframe, MLflow TensorSpec JSON for an ndarray, or another schema format.""" - source: Optional[str] = None - """The type of the dataset source, e.g. ‘databricks-uc-table’, ‘DBFS’, ‘S3’, ...""" - - source_type: Optional[str] = None - """Source information for the dataset. Note that the source may not exactly reproduce the dataset - if it was transformed / modified before use with MLflow.""" - def as_dict(self) -> dict: """Serializes the Dataset into a dictionary suitable for use as a JSON request body.""" body = {} @@ -997,7 +1008,9 @@ def from_dict(cls, d: Dict[str, Any]) -> Dataset: @dataclass class DatasetInput: - dataset: Optional[Dataset] = None + """DatasetInput. Represents a dataset and input tags.""" + + dataset: Dataset """The dataset being used as a Run input.""" tags: Optional[List[InputTag]] = None @@ -1369,6 +1382,8 @@ def from_dict(cls, d: Dict[str, Any]) -> DeleteWebhookResponse: @dataclass class Experiment: + """An experiment and its metadata.""" + artifact_location: Optional[str] = None """Location where artifacts for the experiment are stored.""" @@ -1712,6 +1727,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ExperimentPermissionsRequest: @dataclass class ExperimentTag: + """A tag for an experiment.""" + key: Optional[str] = None """The tag key.""" @@ -1744,6 +1761,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ExperimentTag: @dataclass class FileInfo: + """Metadata of a single artifact file or directory.""" + file_size: Optional[int] = None """Size in bytes. Unset for directories.""" @@ -1781,6 +1800,31 @@ def from_dict(cls, d: Dict[str, Any]) -> FileInfo: return cls(file_size=d.get("file_size", None), is_dir=d.get("is_dir", None), path=d.get("path", None)) +@dataclass +class GetExperimentByNameResponse: + experiment: Optional[Experiment] = None + """Experiment details.""" + + def as_dict(self) -> dict: + """Serializes the GetExperimentByNameResponse into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.experiment: + body["experiment"] = self.experiment.as_dict() + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GetExperimentByNameResponse into a shallow dictionary of its immediate attributes.""" + body = {} + if self.experiment: + body["experiment"] = self.experiment + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GetExperimentByNameResponse: + """Deserializes the GetExperimentByNameResponse from a dictionary.""" + return cls(experiment=_from_dict(d, "experiment", Experiment)) + + @dataclass class GetExperimentPermissionLevelsResponse: permission_levels: Optional[List[ExperimentPermissionsDescription]] = None @@ -1892,10 +1936,13 @@ def from_dict(cls, d: Dict[str, Any]) -> GetLatestVersionsResponse: @dataclass class GetMetricHistoryResponse: metrics: Optional[List[Metric]] = None - """All logged values for this metric.""" + """All logged values for this metric if `max_results` is not specified in the request or if the + total count of metrics returned is less than the service level pagination threshold. Otherwise, + this is one page of results.""" next_page_token: Optional[str] = None - """Token that can be used to retrieve the next page of metric history results""" + """A token that can be used to issue a query for the next page of metric history values. A missing + token indicates that no additional metrics are available to fetch.""" def as_dict(self) -> dict: """Serializes the GetMetricHistoryResponse into a dictionary suitable for use as a JSON request body.""" @@ -2140,10 +2187,12 @@ def from_dict(cls, d: Dict[str, Any]) -> HttpUrlSpecWithoutSecret: @dataclass class InputTag: - key: Optional[str] = None + """Tag for a dataset input.""" + + key: str """The tag key.""" - value: Optional[str] = None + value: str """The tag value.""" def as_dict(self) -> dict: @@ -2493,12 +2542,12 @@ def from_dict(cls, d: Dict[str, Any]) -> LogBatchResponse: @dataclass class LogInputs: + run_id: str + """ID of the run to log under""" + datasets: Optional[List[DatasetInput]] = None """Dataset inputs""" - run_id: Optional[str] = None - """ID of the run to log under""" - def as_dict(self) -> dict: """Serializes the LogInputs into a dictionary suitable for use as a JSON request body.""" body = {} @@ -2556,8 +2605,8 @@ class LogMetric: """ID of the run under which to log the metric. Must be provided.""" run_uuid: Optional[str] = None - """[Deprecated, use run_id instead] ID of the run under which to log the metric. This field will be - removed in a future MLflow version.""" + """[Deprecated, use `run_id` instead] ID of the run under which to log the metric. This field will + be removed in a future MLflow version.""" step: Optional[int] = None """Step at which to log the metric""" @@ -2689,8 +2738,8 @@ class LogParam: """ID of the run under which to log the param. Must be provided.""" run_uuid: Optional[str] = None - """[Deprecated, use run_id instead] ID of the run under which to log the param. This field will be - removed in a future MLflow version.""" + """[Deprecated, use `run_id` instead] ID of the run under which to log the param. This field will + be removed in a future MLflow version.""" def as_dict(self) -> dict: """Serializes the LogParam into a dictionary suitable for use as a JSON request body.""" @@ -2749,6 +2798,8 @@ def from_dict(cls, d: Dict[str, Any]) -> LogParamResponse: @dataclass class Metric: + """Metric associated with a run, represented as a key-value pair.""" + key: Optional[str] = None """Key identifying this metric.""" @@ -3312,6 +3363,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ModelVersionTag: @dataclass class Param: + """Param associated with a run.""" + key: Optional[str] = None """Key identifying this param.""" @@ -4072,6 +4125,8 @@ def from_dict(cls, d: Dict[str, Any]) -> RestoreRunsResponse: @dataclass class Run: + """A single run.""" + data: Optional[RunData] = None """Run data.""" @@ -4115,6 +4170,8 @@ def from_dict(cls, d: Dict[str, Any]) -> Run: @dataclass class RunData: + """Run data (metrics, params, and tags).""" + metrics: Optional[List[Metric]] = None """Run metrics.""" @@ -4158,10 +4215,12 @@ def from_dict(cls, d: Dict[str, Any]) -> RunData: @dataclass class RunInfo: + """Metadata of a single run.""" + artifact_uri: Optional[str] = None """URI of the directory where artifacts should be uploaded. This can be a local path (starting with - "/"), or a distributed file system (DFS) path, like `s3://bucket/directory` or - `dbfs:/my/directory`. If not set, the local `./mlruns` directory is chosen.""" + "/"), or a distributed file system (DFS) path, like ``s3://bucket/directory`` or + ``dbfs:/my/directory``. If not set, the local ``./mlruns`` directory is chosen.""" end_time: Optional[int] = None """Unix timestamp of when the run ended in milliseconds.""" @@ -4175,6 +4234,9 @@ class RunInfo: run_id: Optional[str] = None """Unique identifier for the run.""" + run_name: Optional[str] = None + """The name of the run.""" + run_uuid: Optional[str] = None """[Deprecated, use run_id instead] Unique identifier for the run. This field will be removed in a future MLflow version.""" @@ -4202,6 +4264,8 @@ def as_dict(self) -> dict: body["lifecycle_stage"] = self.lifecycle_stage if self.run_id is not None: body["run_id"] = self.run_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.run_uuid is not None: body["run_uuid"] = self.run_uuid if self.start_time is not None: @@ -4225,6 +4289,8 @@ def as_shallow_dict(self) -> dict: body["lifecycle_stage"] = self.lifecycle_stage if self.run_id is not None: body["run_id"] = self.run_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.run_uuid is not None: body["run_uuid"] = self.run_uuid if self.start_time is not None: @@ -4244,6 +4310,7 @@ def from_dict(cls, d: Dict[str, Any]) -> RunInfo: experiment_id=d.get("experiment_id", None), lifecycle_stage=d.get("lifecycle_stage", None), run_id=d.get("run_id", None), + run_name=d.get("run_name", None), run_uuid=d.get("run_uuid", None), start_time=d.get("start_time", None), status=_enum(d, "status", RunInfoStatus), @@ -4252,7 +4319,7 @@ def from_dict(cls, d: Dict[str, Any]) -> RunInfo: class RunInfoStatus(Enum): - """Current status of the run.""" + """Status of a run.""" FAILED = "FAILED" FINISHED = "FINISHED" @@ -4263,6 +4330,8 @@ class RunInfoStatus(Enum): @dataclass class RunInputs: + """Run inputs.""" + dataset_inputs: Optional[List[DatasetInput]] = None """Run metrics.""" @@ -4288,6 +4357,8 @@ def from_dict(cls, d: Dict[str, Any]) -> RunInputs: @dataclass class RunTag: + """Tag for a run.""" + key: Optional[str] = None """The tag key.""" @@ -4334,7 +4405,7 @@ class SearchExperiments: page_token: Optional[str] = None """Token indicating the page of experiments to fetch""" - view_type: Optional[SearchExperimentsViewType] = None + view_type: Optional[ViewType] = None """Qualifier for type of experiments to be returned. If unspecified, return only active experiments.""" @@ -4376,7 +4447,7 @@ def from_dict(cls, d: Dict[str, Any]) -> SearchExperiments: max_results=d.get("max_results", None), order_by=d.get("order_by", None), page_token=d.get("page_token", None), - view_type=_enum(d, "view_type", SearchExperimentsViewType), + view_type=_enum(d, "view_type", ViewType), ) @@ -4415,15 +4486,6 @@ def from_dict(cls, d: Dict[str, Any]) -> SearchExperimentsResponse: ) -class SearchExperimentsViewType(Enum): - """Qualifier for type of experiments to be returned. If unspecified, return only active - experiments.""" - - ACTIVE_ONLY = "ACTIVE_ONLY" - ALL = "ALL" - DELETED_ONLY = "DELETED_ONLY" - - @dataclass class SearchModelVersionsResponse: model_versions: Optional[List[ModelVersion]] = None @@ -4516,15 +4578,15 @@ class SearchRuns: order_by: Optional[List[str]] = None """List of columns to be ordered by, including attributes, params, metrics, and tags with an - optional "DESC" or "ASC" annotation, where "ASC" is the default. Example: ["params.input DESC", - "metrics.alpha ASC", "metrics.rmse"] Tiebreaks are done by start_time DESC followed by run_id - for runs with the same start time (and this is the default ordering criterion if order_by is not - provided).""" + optional `"DESC"` or `"ASC"` annotation, where `"ASC"` is the default. Example: `["params.input + DESC", "metrics.alpha ASC", "metrics.rmse"]`. Tiebreaks are done by start_time `DESC` followed + by `run_id` for runs with the same start time (and this is the default ordering criterion if + order_by is not provided).""" page_token: Optional[str] = None """Token for the current page of runs.""" - run_view_type: Optional[SearchRunsRunViewType] = None + run_view_type: Optional[ViewType] = None """Whether to display only active, only deleted, or all runs. Defaults to only active runs.""" def as_dict(self) -> dict: @@ -4570,7 +4632,7 @@ def from_dict(cls, d: Dict[str, Any]) -> SearchRuns: max_results=d.get("max_results", None), order_by=d.get("order_by", None), page_token=d.get("page_token", None), - run_view_type=_enum(d, "run_view_type", SearchRunsRunViewType), + run_view_type=_enum(d, "run_view_type", ViewType), ) @@ -4606,26 +4668,16 @@ def from_dict(cls, d: Dict[str, Any]) -> SearchRunsResponse: return cls(next_page_token=d.get("next_page_token", None), runs=_repeated_dict(d, "runs", Run)) -class SearchRunsRunViewType(Enum): - """Whether to display only active, only deleted, or all runs. Defaults to only active runs.""" - - ACTIVE_ONLY = "ACTIVE_ONLY" - ALL = "ALL" - DELETED_ONLY = "DELETED_ONLY" - - @dataclass class SetExperimentTag: experiment_id: str """ID of the experiment under which to log the tag. Must be provided.""" key: str - """Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size.""" + """Name of the tag. Keys up to 250 bytes in size are supported.""" value: str - """String value of the tag being logged. Maximum size depends on storage backend. All storage - backends are guaranteed to support key values up to 5000 bytes in size.""" + """String value of the tag being logged. Values up to 64KB in size are supported.""" def as_dict(self) -> dict: """Serializes the SetExperimentTag into a dictionary suitable for use as a JSON request body.""" @@ -4805,18 +4857,16 @@ def from_dict(cls, d: Dict[str, Any]) -> SetModelVersionTagResponse: @dataclass class SetTag: key: str - """Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size.""" + """Name of the tag. Keys up to 250 bytes in size are supported.""" value: str - """String value of the tag being logged. Maximum size depends on storage backend. All storage - backends are guaranteed to support key values up to 5000 bytes in size.""" + """String value of the tag being logged. Values up to 64KB in size are supported.""" run_id: Optional[str] = None """ID of the run under which to log the tag. Must be provided.""" run_uuid: Optional[str] = None - """[Deprecated, use run_id instead] ID of the run under which to log the tag. This field will be + """[Deprecated, use `run_id` instead] ID of the run under which to log the tag. This field will be removed in a future MLflow version.""" def as_dict(self) -> dict: @@ -5476,8 +5526,11 @@ class UpdateRun: run_id: Optional[str] = None """ID of the run to update. Must be provided.""" + run_name: Optional[str] = None + """Updated name of the run.""" + run_uuid: Optional[str] = None - """[Deprecated, use run_id instead] ID of the run to update.. This field will be removed in a + """[Deprecated, use `run_id` instead] ID of the run to update. This field will be removed in a future MLflow version.""" status: Optional[UpdateRunStatus] = None @@ -5490,6 +5543,8 @@ def as_dict(self) -> dict: body["end_time"] = self.end_time if self.run_id is not None: body["run_id"] = self.run_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.run_uuid is not None: body["run_uuid"] = self.run_uuid if self.status is not None: @@ -5503,6 +5558,8 @@ def as_shallow_dict(self) -> dict: body["end_time"] = self.end_time if self.run_id is not None: body["run_id"] = self.run_id + if self.run_name is not None: + body["run_name"] = self.run_name if self.run_uuid is not None: body["run_uuid"] = self.run_uuid if self.status is not None: @@ -5515,6 +5572,7 @@ def from_dict(cls, d: Dict[str, Any]) -> UpdateRun: return cls( end_time=d.get("end_time", None), run_id=d.get("run_id", None), + run_name=d.get("run_name", None), run_uuid=d.get("run_uuid", None), status=_enum(d, "status", UpdateRunStatus), ) @@ -5546,7 +5604,7 @@ def from_dict(cls, d: Dict[str, Any]) -> UpdateRunResponse: class UpdateRunStatus(Enum): - """Updated status of the run.""" + """Status of a run.""" FAILED = "FAILED" FINISHED = "FINISHED" @@ -5573,6 +5631,14 @@ def from_dict(cls, d: Dict[str, Any]) -> UpdateWebhookResponse: return cls() +class ViewType(Enum): + """Qualifier for the view type.""" + + ACTIVE_ONLY = "ACTIVE_ONLY" + ALL = "ALL" + DELETED_ONLY = "DELETED_ONLY" + + class ExperimentsAPI: """Experiments are the primary unit of organization in MLflow; all MLflow runs belong to an experiment. Each experiment lets you visualize, search, and compare runs, as well as download run artifacts or metadata for @@ -5593,7 +5659,7 @@ def create_experiment( another experiment with the same name does not already exist and fails if another experiment with the same name already exists. - Throws `RESOURCE_ALREADY_EXISTS` if a experiment with the given name exists. + Throws `RESOURCE_ALREADY_EXISTS` if an experiment with the given name exists. :param name: str Experiment name. @@ -5627,6 +5693,7 @@ def create_run( self, *, experiment_id: Optional[str] = None, + run_name: Optional[str] = None, start_time: Optional[int] = None, tags: Optional[List[RunTag]] = None, user_id: Optional[str] = None, @@ -5634,11 +5701,13 @@ def create_run( """Create a run. Creates a new run within an experiment. A run is usually a single execution of a machine learning or - data ETL pipeline. MLflow uses runs to track the `mlflowParam`, `mlflowMetric` and `mlflowRunTag` + data ETL pipeline. MLflow uses runs to track the `mlflowParam`, `mlflowMetric`, and `mlflowRunTag` associated with a single execution. :param experiment_id: str (optional) ID of the associated experiment. + :param run_name: str (optional) + The name of the run. :param start_time: int (optional) Unix timestamp in milliseconds of when the run started. :param tags: List[:class:`RunTag`] (optional) @@ -5652,6 +5721,8 @@ def create_run( body = {} if experiment_id is not None: body["experiment_id"] = experiment_id + if run_name is not None: + body["run_name"] = run_name if start_time is not None: body["start_time"] = start_time if tags is not None: @@ -5670,7 +5741,7 @@ def delete_experiment(self, experiment_id: str): """Delete an experiment. Marks an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the - experiment uses FileStore, artifacts associated with experiment are also deleted. + experiment uses FileStore, artifacts associated with the experiment are also deleted. :param experiment_id: str ID of the associated experiment. @@ -5714,7 +5785,7 @@ def delete_runs( Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the - client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-delete. + client code snippet on :param experiment_id: str The ID of the experiment containing the runs to delete. @@ -5743,7 +5814,7 @@ def delete_runs( return DeleteRunsResponse.from_dict(res) def delete_tag(self, run_id: str, key: str): - """Delete a tag. + """Delete a tag on a run. Deletes a tag on a run. Tags are run metadata that can be updated during a run and after a run completes. @@ -5767,8 +5838,8 @@ def delete_tag(self, run_id: str, key: str): self._api.do("POST", "/api/2.0/mlflow/runs/delete-tag", body=body, headers=headers) - def get_by_name(self, experiment_name: str) -> GetExperimentResponse: - """Get metadata. + def get_by_name(self, experiment_name: str) -> GetExperimentByNameResponse: + """Get an experiment by name. Gets metadata for an experiment. @@ -5781,7 +5852,7 @@ def get_by_name(self, experiment_name: str) -> GetExperimentResponse: :param experiment_name: str Name of the associated experiment. - :returns: :class:`GetExperimentResponse` + :returns: :class:`GetExperimentByNameResponse` """ query = {} @@ -5792,7 +5863,7 @@ def get_by_name(self, experiment_name: str) -> GetExperimentResponse: } res = self._api.do("GET", "/api/2.0/mlflow/experiments/get-by-name", query=query, headers=headers) - return GetExperimentResponse.from_dict(res) + return GetExperimentByNameResponse.from_dict(res) def get_experiment(self, experiment_id: str) -> GetExperimentResponse: """Get an experiment. @@ -5824,7 +5895,7 @@ def get_history( run_id: Optional[str] = None, run_uuid: Optional[str] = None, ) -> Iterator[Metric]: - """Get history of a given metric within a run. + """Get metric history for a run. Gets a list of all values for the specified metric for a given run. @@ -5838,8 +5909,8 @@ def get_history( :param run_id: str (optional) ID of the run from which to fetch metric values. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run from which to fetch metric values. This field will be - removed in a future MLflow version. + [Deprecated, use `run_id` instead] ID of the run from which to fetch metric values. This field will + be removed in a future MLflow version. :returns: Iterator over :class:`Metric` """ @@ -5915,7 +5986,7 @@ def get_run(self, run_id: str, *, run_uuid: Optional[str] = None) -> GetRunRespo :param run_id: str ID of the run to fetch. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run to fetch. This field will be removed in a future + [Deprecated, use `run_id` instead] ID of the run to fetch. This field will be removed in a future MLflow version. :returns: :class:`GetRunResponse` @@ -5941,13 +6012,13 @@ def list_artifacts( run_id: Optional[str] = None, run_uuid: Optional[str] = None, ) -> Iterator[FileInfo]: - """Get all artifacts. + """List artifacts. - List artifacts for a run. Takes an optional `artifact_path` prefix. If it is specified, the response - contains only artifacts with the specified prefix. This API does not support pagination when listing - artifacts in UC Volumes. A maximum of 1000 artifacts will be retrieved for UC Volumes. Please call - `/api/2.0/fs/directories{directory_path}` for listing artifacts in UC Volumes, which supports - pagination. See [List directory contents | Files API](/api/workspace/files/listdirectorycontents). + List artifacts for a run. Takes an optional `artifact_path` prefix which if specified, the response + contains only artifacts with the specified prefix. A maximum of 1000 artifacts will be retrieved for + UC Volumes. Please call `/api/2.0/fs/directories{directory_path}` for listing artifacts in UC Volumes, + which supports pagination. See [List directory contents | Files + API](/api/workspace/files/listdirectorycontents). :param page_token: str (optional) Token indicating the page of artifact results to fetch. `page_token` is not supported when listing @@ -5959,7 +6030,7 @@ def list_artifacts( :param run_id: str (optional) ID of the run whose artifacts to list. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run whose artifacts to list. This field will be removed + [Deprecated, use `run_id` instead] ID of the run whose artifacts to list. This field will be removed in a future MLflow version. :returns: Iterator over :class:`FileInfo` @@ -5988,7 +6059,11 @@ def list_artifacts( query["page_token"] = json["next_page_token"] def list_experiments( - self, *, max_results: Optional[int] = None, page_token: Optional[str] = None, view_type: Optional[str] = None + self, + *, + max_results: Optional[int] = None, + page_token: Optional[str] = None, + view_type: Optional[ViewType] = None, ) -> Iterator[Experiment]: """List experiments. @@ -6000,7 +6075,7 @@ def list_experiments( encouraged to pass max_results explicitly and leverage page_token to iterate through experiments. :param page_token: str (optional) Token indicating the page of experiments to fetch - :param view_type: str (optional) + :param view_type: :class:`ViewType` (optional) Qualifier for type of experiments to be returned. If unspecified, return only active experiments. :returns: Iterator over :class:`Experiment` @@ -6012,7 +6087,7 @@ def list_experiments( if page_token is not None: query["page_token"] = page_token if view_type is not None: - query["view_type"] = view_type + query["view_type"] = view_type.value headers = { "Accept": "application/json", } @@ -6034,7 +6109,7 @@ def log_batch( run_id: Optional[str] = None, tags: Optional[List[RunTag]] = None, ): - """Log a batch. + """Log a batch of metrics/params/tags for a run. Logs a batch of metrics, params, and tags for a run. If any data failed to be persisted, the server will respond with an error (non-200 status code). @@ -6060,16 +6135,22 @@ def log_batch( Request Limits ------------------------------- A single JSON-serialized API request may be up to 1 MB in size and contain: - * No more than 1000 metrics, params, and tags in total * Up to 1000 metrics * Up to 100 params * Up to - 100 tags + * No more than 1000 metrics, params, and tags in total + + * Up to 1000 metrics + + * Up to 100 params + + * Up to 100 tags For example, a valid request might contain 900 metrics, 50 params, and 50 tags, but logging 900 metrics, 50 params, and 51 tags is invalid. The following limits also apply to metric, param, and tag keys and values: - * Metric keys, param keys, and tag keys can be up to 250 characters in length * Parameter and tag - values can be up to 250 characters in length + * Metric keys, param keys, and tag keys can be up to 250 characters in length + + * Parameter and tag values can be up to 250 characters in length :param metrics: List[:class:`Metric`] (optional) Metrics to log. A single request can contain up to 1000 metrics, and up to 1000 metrics, params, and @@ -6101,15 +6182,17 @@ def log_batch( self._api.do("POST", "/api/2.0/mlflow/runs/log-batch", body=body, headers=headers) - def log_inputs(self, *, datasets: Optional[List[DatasetInput]] = None, run_id: Optional[str] = None): + def log_inputs(self, run_id: str, *, datasets: Optional[List[DatasetInput]] = None): """Log inputs to a run. **NOTE:** Experimental: This API may change or be removed in a future release without warning. + Logs inputs, such as datasets and models, to an MLflow Run. + + :param run_id: str + ID of the run to log under :param datasets: List[:class:`DatasetInput`] (optional) Dataset inputs - :param run_id: str (optional) - ID of the run to log under """ @@ -6135,9 +6218,9 @@ def log_metric( run_uuid: Optional[str] = None, step: Optional[int] = None, ): - """Log a metric. + """Log a metric for a run. - Logs a metric for a run. A metric is a key-value pair (string key, float value) with an associated + Log a metric for a run. A metric is a key-value pair (string key, float value) with an associated timestamp. Examples include the various metrics that represent ML model accuracy. A metric can be logged multiple times. @@ -6150,7 +6233,7 @@ def log_metric( :param run_id: str (optional) ID of the run under which to log the metric. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the metric. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the metric. This field will be removed in a future MLflow version. :param step: int (optional) Step at which to log the metric @@ -6202,7 +6285,7 @@ def log_model(self, *, model_json: Optional[str] = None, run_id: Optional[str] = self._api.do("POST", "/api/2.0/mlflow/runs/log-model", body=body, headers=headers) def log_param(self, key: str, value: str, *, run_id: Optional[str] = None, run_uuid: Optional[str] = None): - """Log a param. + """Log a param for a run. Logs a param used for a run. A param is a key-value pair (string key, string value). Examples include hyperparameters used for ML model training and constant dates and values used in an ETL pipeline. A @@ -6215,7 +6298,7 @@ def log_param(self, key: str, value: str, *, run_id: Optional[str] = None, run_u :param run_id: str (optional) ID of the run under which to log the param. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the param. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the param. This field will be removed in a future MLflow version. @@ -6237,7 +6320,7 @@ def log_param(self, key: str, value: str, *, run_id: Optional[str] = None, run_u self._api.do("POST", "/api/2.0/mlflow/runs/log-parameter", body=body, headers=headers) def restore_experiment(self, experiment_id: str): - """Restores an experiment. + """Restore an experiment. Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics, params, and tags. If experiment uses FileStore, underlying artifacts associated with experiment are @@ -6263,7 +6346,9 @@ def restore_experiment(self, experiment_id: str): def restore_run(self, run_id: str): """Restore a run. - Restores a deleted run. + Restores a deleted run. This also restores associated metadata, runs, metrics, params, and tags. + + Throws `RESOURCE_DOES_NOT_EXIST` if the run was never created or was permanently deleted. :param run_id: str ID of the run to restore. @@ -6287,7 +6372,7 @@ def restore_runs( Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the - client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-restore. + client code snippet on :param experiment_id: str The ID of the experiment containing the runs to restore. @@ -6322,7 +6407,7 @@ def search_experiments( max_results: Optional[int] = None, order_by: Optional[List[str]] = None, page_token: Optional[str] = None, - view_type: Optional[SearchExperimentsViewType] = None, + view_type: Optional[ViewType] = None, ) -> Iterator[Experiment]: """Search experiments. @@ -6338,7 +6423,7 @@ def search_experiments( done by experiment id DESC. :param page_token: str (optional) Token indicating the page of experiments to fetch - :param view_type: :class:`SearchExperimentsViewType` (optional) + :param view_type: :class:`ViewType` (optional) Qualifier for type of experiments to be returned. If unspecified, return only active experiments. :returns: Iterator over :class:`Experiment` @@ -6376,13 +6461,13 @@ def search_runs( max_results: Optional[int] = None, order_by: Optional[List[str]] = None, page_token: Optional[str] = None, - run_view_type: Optional[SearchRunsRunViewType] = None, + run_view_type: Optional[ViewType] = None, ) -> Iterator[Run]: """Search for runs. Searches for runs that satisfy expressions. - Search expressions can use `mlflowMetric` and `mlflowParam` keys.", + Search expressions can use `mlflowMetric` and `mlflowParam` keys. :param experiment_ids: List[str] (optional) List of experiment IDs to search over. @@ -6401,13 +6486,13 @@ def search_runs( Maximum number of runs desired. Max threshold is 50000 :param order_by: List[str] (optional) List of columns to be ordered by, including attributes, params, metrics, and tags with an optional - "DESC" or "ASC" annotation, where "ASC" is the default. Example: ["params.input DESC", - "metrics.alpha ASC", "metrics.rmse"] Tiebreaks are done by start_time DESC followed by run_id for - runs with the same start time (and this is the default ordering criterion if order_by is not + `"DESC"` or `"ASC"` annotation, where `"ASC"` is the default. Example: `["params.input DESC", + "metrics.alpha ASC", "metrics.rmse"]`. Tiebreaks are done by start_time `DESC` followed by `run_id` + for runs with the same start time (and this is the default ordering criterion if order_by is not provided). :param page_token: str (optional) Token for the current page of runs. - :param run_view_type: :class:`SearchRunsRunViewType` (optional) + :param run_view_type: :class:`ViewType` (optional) Whether to display only active, only deleted, or all runs. Defaults to only active runs. :returns: Iterator over :class:`Run` @@ -6440,18 +6525,16 @@ def search_runs( body["page_token"] = json["next_page_token"] def set_experiment_tag(self, experiment_id: str, key: str, value: str): - """Set a tag. + """Set a tag for an experiment. Sets a tag on an experiment. Experiment tags are metadata that can be updated. :param experiment_id: str ID of the experiment under which to log the tag. Must be provided. :param key: str - Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size. + Name of the tag. Keys up to 250 bytes in size are supported. :param value: str - String value of the tag being logged. Maximum size depends on storage backend. All storage backends - are guaranteed to support key values up to 5000 bytes in size. + String value of the tag being logged. Values up to 64KB in size are supported. """ @@ -6495,20 +6578,18 @@ def set_permissions( return ExperimentPermissions.from_dict(res) def set_tag(self, key: str, value: str, *, run_id: Optional[str] = None, run_uuid: Optional[str] = None): - """Set a tag. + """Set a tag for a run. Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes. :param key: str - Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size. + Name of the tag. Keys up to 250 bytes in size are supported. :param value: str - String value of the tag being logged. Maximum size depends on storage backend. All storage backends - are guaranteed to support key values up to 5000 bytes in size. + String value of the tag being logged. Values up to 64KB in size are supported. :param run_id: str (optional) ID of the run under which to log the tag. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the tag. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the tag. This field will be removed in a future MLflow version. @@ -6582,6 +6663,7 @@ def update_run( *, end_time: Optional[int] = None, run_id: Optional[str] = None, + run_name: Optional[str] = None, run_uuid: Optional[str] = None, status: Optional[UpdateRunStatus] = None, ) -> UpdateRunResponse: @@ -6593,8 +6675,10 @@ def update_run( Unix timestamp in milliseconds of when the run ended. :param run_id: str (optional) ID of the run to update. Must be provided. + :param run_name: str (optional) + Updated name of the run. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run to update.. This field will be removed in a future + [Deprecated, use `run_id` instead] ID of the run to update. This field will be removed in a future MLflow version. :param status: :class:`UpdateRunStatus` (optional) Updated status of the run. @@ -6606,6 +6690,8 @@ def update_run( body["end_time"] = end_time if run_id is not None: body["run_id"] = run_id + if run_name is not None: + body["run_name"] = run_name if run_uuid is not None: body["run_uuid"] = run_uuid if status is not None: diff --git a/databricks/sdk/service/oauth2.py b/databricks/sdk/service/oauth2.py index ab921a24f..366f282f4 100755 --- a/databricks/sdk/service/oauth2.py +++ b/databricks/sdk/service/oauth2.py @@ -186,11 +186,47 @@ def from_dict(cls, d: Dict[str, Any]) -> CreatePublishedAppIntegrationOutput: return cls(integration_id=d.get("integration_id", None)) +@dataclass +class CreateServicePrincipalSecretRequest: + lifetime: Optional[str] = None + """The lifetime of the secret in seconds. If this parameter is not provided, the secret will have a + default lifetime of 730 days (63072000s).""" + + service_principal_id: Optional[int] = None + """The service principal ID.""" + + def as_dict(self) -> dict: + """Serializes the CreateServicePrincipalSecretRequest into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.lifetime is not None: + body["lifetime"] = self.lifetime + if self.service_principal_id is not None: + body["service_principal_id"] = self.service_principal_id + return body + + def as_shallow_dict(self) -> dict: + """Serializes the CreateServicePrincipalSecretRequest into a shallow dictionary of its immediate attributes.""" + body = {} + if self.lifetime is not None: + body["lifetime"] = self.lifetime + if self.service_principal_id is not None: + body["service_principal_id"] = self.service_principal_id + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> CreateServicePrincipalSecretRequest: + """Deserializes the CreateServicePrincipalSecretRequest from a dictionary.""" + return cls(lifetime=d.get("lifetime", None), service_principal_id=d.get("service_principal_id", None)) + + @dataclass class CreateServicePrincipalSecretResponse: create_time: Optional[str] = None """UTC time when the secret was created""" + expire_time: Optional[str] = None + """UTC time when the secret will expire. If the field is not present, the secret does not expire.""" + id: Optional[str] = None """ID of the secret""" @@ -211,6 +247,8 @@ def as_dict(self) -> dict: body = {} if self.create_time is not None: body["create_time"] = self.create_time + if self.expire_time is not None: + body["expire_time"] = self.expire_time if self.id is not None: body["id"] = self.id if self.secret is not None: @@ -228,6 +266,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.create_time is not None: body["create_time"] = self.create_time + if self.expire_time is not None: + body["expire_time"] = self.expire_time if self.id is not None: body["id"] = self.id if self.secret is not None: @@ -245,6 +285,7 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateServicePrincipalSecretResponse: """Deserializes the CreateServicePrincipalSecretResponse from a dictionary.""" return cls( create_time=d.get("create_time", None), + expire_time=d.get("expire_time", None), id=d.get("id", None), secret=d.get("secret", None), secret_hash=d.get("secret_hash", None), @@ -729,10 +770,18 @@ class OidcFederationPolicy: """The required token issuer, as specified in the 'iss' claim of federated tokens.""" jwks_json: Optional[str] = None - """The public keys used to validate the signature of federated tokens, in JWKS format. If - unspecified (recommended), Databricks automatically fetches the public keys from your issuer’s - well known endpoint. Databricks strongly recommends relying on your issuer’s well known - endpoint for discovering public keys.""" + """The public keys used to validate the signature of federated tokens, in JWKS format. Most use + cases should not need to specify this field. If jwks_uri and jwks_json are both unspecified + (recommended), Databricks automatically fetches the public keys from your issuer’s well known + endpoint. Databricks strongly recommends relying on your issuer’s well known endpoint for + discovering public keys.""" + + jwks_uri: Optional[str] = None + """URL of the public keys used to validate the signature of federated tokens, in JWKS format. Most + use cases should not need to specify this field. If jwks_uri and jwks_json are both unspecified + (recommended), Databricks automatically fetches the public keys from your issuer’s well known + endpoint. Databricks strongly recommends relying on your issuer’s well known endpoint for + discovering public keys.""" subject: Optional[str] = None """The required token subject, as specified in the subject claim of federated tokens. Must be @@ -751,6 +800,8 @@ def as_dict(self) -> dict: body["issuer"] = self.issuer if self.jwks_json is not None: body["jwks_json"] = self.jwks_json + if self.jwks_uri is not None: + body["jwks_uri"] = self.jwks_uri if self.subject is not None: body["subject"] = self.subject if self.subject_claim is not None: @@ -766,6 +817,8 @@ def as_shallow_dict(self) -> dict: body["issuer"] = self.issuer if self.jwks_json is not None: body["jwks_json"] = self.jwks_json + if self.jwks_uri is not None: + body["jwks_uri"] = self.jwks_uri if self.subject is not None: body["subject"] = self.subject if self.subject_claim is not None: @@ -779,6 +832,7 @@ def from_dict(cls, d: Dict[str, Any]) -> OidcFederationPolicy: audiences=d.get("audiences", None), issuer=d.get("issuer", None), jwks_json=d.get("jwks_json", None), + jwks_uri=d.get("jwks_uri", None), subject=d.get("subject", None), subject_claim=d.get("subject_claim", None), ) @@ -865,6 +919,9 @@ class SecretInfo: create_time: Optional[str] = None """UTC time when the secret was created""" + expire_time: Optional[str] = None + """UTC time when the secret will expire. If the field is not present, the secret does not expire.""" + id: Optional[str] = None """ID of the secret""" @@ -882,6 +939,8 @@ def as_dict(self) -> dict: body = {} if self.create_time is not None: body["create_time"] = self.create_time + if self.expire_time is not None: + body["expire_time"] = self.expire_time if self.id is not None: body["id"] = self.id if self.secret_hash is not None: @@ -897,6 +956,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.create_time is not None: body["create_time"] = self.create_time + if self.expire_time is not None: + body["expire_time"] = self.expire_time if self.id is not None: body["id"] = self.id if self.secret_hash is not None: @@ -912,6 +973,7 @@ def from_dict(cls, d: Dict[str, Any]) -> SecretInfo: """Deserializes the SecretInfo from a dictionary.""" return cls( create_time=d.get("create_time", None), + expire_time=d.get("expire_time", None), id=d.get("id", None), secret_hash=d.get("secret_hash", None), status=d.get("status", None), @@ -1866,24 +1928,33 @@ class ServicePrincipalSecretsAPI: def __init__(self, api_client): self._api = api_client - def create(self, service_principal_id: int) -> CreateServicePrincipalSecretResponse: + def create( + self, service_principal_id: int, *, lifetime: Optional[str] = None + ) -> CreateServicePrincipalSecretResponse: """Create service principal secret. Create a secret for the given service principal. :param service_principal_id: int The service principal ID. + :param lifetime: str (optional) + The lifetime of the secret in seconds. If this parameter is not provided, the secret will have a + default lifetime of 730 days (63072000s). :returns: :class:`CreateServicePrincipalSecretResponse` """ - + body = {} + if lifetime is not None: + body["lifetime"] = lifetime headers = { "Accept": "application/json", + "Content-Type": "application/json", } res = self._api.do( "POST", f"/api/2.0/accounts/{self._api.account_id}/servicePrincipals/{service_principal_id}/credentials/secrets", + body=body, headers=headers, ) return CreateServicePrincipalSecretResponse.from_dict(res) diff --git a/databricks/sdk/service/serving.py b/databricks/sdk/service/serving.py index 0d6085943..fccad9b79 100755 --- a/databricks/sdk/service/serving.py +++ b/databricks/sdk/service/serving.py @@ -400,6 +400,12 @@ class AmazonBedrockConfig: Databricks Secrets, see `aws_secret_access_key`. You must provide an API key using one of the following fields: `aws_secret_access_key` or `aws_secret_access_key_plaintext`.""" + instance_profile_arn: Optional[str] = None + """ARN of the instance profile that the external model will use to access AWS resources. You must + authenticate using an instance profile or access keys. If you prefer to authenticate using + access keys, see `aws_access_key_id`, `aws_access_key_id_plaintext`, `aws_secret_access_key` and + `aws_secret_access_key_plaintext`.""" + def as_dict(self) -> dict: """Serializes the AmazonBedrockConfig into a dictionary suitable for use as a JSON request body.""" body = {} @@ -415,6 +421,8 @@ def as_dict(self) -> dict: body["aws_secret_access_key_plaintext"] = self.aws_secret_access_key_plaintext if self.bedrock_provider is not None: body["bedrock_provider"] = self.bedrock_provider.value + if self.instance_profile_arn is not None: + body["instance_profile_arn"] = self.instance_profile_arn return body def as_shallow_dict(self) -> dict: @@ -432,6 +440,8 @@ def as_shallow_dict(self) -> dict: body["aws_secret_access_key_plaintext"] = self.aws_secret_access_key_plaintext if self.bedrock_provider is not None: body["bedrock_provider"] = self.bedrock_provider + if self.instance_profile_arn is not None: + body["instance_profile_arn"] = self.instance_profile_arn return body @classmethod @@ -444,6 +454,7 @@ def from_dict(cls, d: Dict[str, Any]) -> AmazonBedrockConfig: aws_secret_access_key=d.get("aws_secret_access_key", None), aws_secret_access_key_plaintext=d.get("aws_secret_access_key_plaintext", None), bedrock_provider=_enum(d, "bedrock_provider", AmazonBedrockConfigBedrockProvider), + instance_profile_arn=d.get("instance_profile_arn", None), ) @@ -756,6 +767,9 @@ class CreateServingEndpoint: """The AI Gateway configuration for the serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported.""" + budget_policy_id: Optional[str] = None + """The budget policy to be applied to the serving endpoint.""" + config: Optional[EndpointCoreConfigInput] = None """The core config of the serving endpoint.""" @@ -774,6 +788,8 @@ def as_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway.as_dict() + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config.as_dict() if self.name is not None: @@ -791,6 +807,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config if self.name is not None: @@ -808,6 +826,7 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateServingEndpoint: """Deserializes the CreateServingEndpoint from a dictionary.""" return cls( ai_gateway=_from_dict(d, "ai_gateway", AiGatewayConfig), + budget_policy_id=d.get("budget_policy_id", None), config=_from_dict(d, "config", EndpointCoreConfigInput), name=d.get("name", None), rate_limits=_repeated_dict(d, "rate_limits", RateLimit), @@ -3326,6 +3345,9 @@ class ServingEndpoint: """The AI Gateway configuration for the serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported.""" + budget_policy_id: Optional[str] = None + """The budget policy associated with the endpoint.""" + config: Optional[EndpointCoreConfigSummary] = None """The config that is currently being served by the endpoint.""" @@ -3358,6 +3380,8 @@ def as_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway.as_dict() + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config.as_dict() if self.creation_timestamp is not None: @@ -3383,6 +3407,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config if self.creation_timestamp is not None: @@ -3408,6 +3434,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ServingEndpoint: """Deserializes the ServingEndpoint from a dictionary.""" return cls( ai_gateway=_from_dict(d, "ai_gateway", AiGatewayConfig), + budget_policy_id=d.get("budget_policy_id", None), config=_from_dict(d, "config", EndpointCoreConfigSummary), creation_timestamp=d.get("creation_timestamp", None), creator=d.get("creator", None), @@ -3536,6 +3563,9 @@ class ServingEndpointDetailed: """The AI Gateway configuration for the serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported.""" + budget_policy_id: Optional[str] = None + """The budget policy associated with the endpoint.""" + config: Optional[EndpointCoreConfigOutput] = None """The config that is currently being served by the endpoint.""" @@ -3584,6 +3614,8 @@ def as_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway.as_dict() + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config.as_dict() if self.creation_timestamp is not None: @@ -3619,6 +3651,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.ai_gateway: body["ai_gateway"] = self.ai_gateway + if self.budget_policy_id is not None: + body["budget_policy_id"] = self.budget_policy_id if self.config: body["config"] = self.config if self.creation_timestamp is not None: @@ -3654,6 +3688,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ServingEndpointDetailed: """Deserializes the ServingEndpointDetailed from a dictionary.""" return cls( ai_gateway=_from_dict(d, "ai_gateway", AiGatewayConfig), + budget_policy_id=d.get("budget_policy_id", None), config=_from_dict(d, "config", EndpointCoreConfigOutput), creation_timestamp=d.get("creation_timestamp", None), creator=d.get("creator", None), @@ -4005,6 +4040,7 @@ def create( name: str, *, ai_gateway: Optional[AiGatewayConfig] = None, + budget_policy_id: Optional[str] = None, config: Optional[EndpointCoreConfigInput] = None, rate_limits: Optional[List[RateLimit]] = None, route_optimized: Optional[bool] = None, @@ -4018,6 +4054,8 @@ def create( :param ai_gateway: :class:`AiGatewayConfig` (optional) The AI Gateway configuration for the serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported. + :param budget_policy_id: str (optional) + The budget policy to be applied to the serving endpoint. :param config: :class:`EndpointCoreConfigInput` (optional) The core config of the serving endpoint. :param rate_limits: List[:class:`RateLimit`] (optional) @@ -4035,6 +4073,8 @@ def create( body = {} if ai_gateway is not None: body["ai_gateway"] = ai_gateway.as_dict() + if budget_policy_id is not None: + body["budget_policy_id"] = budget_policy_id if config is not None: body["config"] = config.as_dict() if name is not None: @@ -4062,6 +4102,7 @@ def create_and_wait( name: str, *, ai_gateway: Optional[AiGatewayConfig] = None, + budget_policy_id: Optional[str] = None, config: Optional[EndpointCoreConfigInput] = None, rate_limits: Optional[List[RateLimit]] = None, route_optimized: Optional[bool] = None, @@ -4070,6 +4111,7 @@ def create_and_wait( ) -> ServingEndpointDetailed: return self.create( ai_gateway=ai_gateway, + budget_policy_id=budget_policy_id, config=config, name=name, rate_limits=rate_limits, @@ -4085,9 +4127,7 @@ def delete(self, name: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.0/serving-endpoints/{name}", headers=headers) diff --git a/databricks/sdk/service/settings.py b/databricks/sdk/service/settings.py index 77b31a95e..317219e7f 100755 --- a/databricks/sdk/service/settings.py +++ b/databricks/sdk/service/settings.py @@ -5090,9 +5090,7 @@ def delete(self, ip_access_list_id: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do( "DELETE", f"/api/2.0/accounts/{self._api.account_id}/ip-access-lists/{ip_access_list_id}", headers=headers @@ -5180,7 +5178,6 @@ def replace( if list_type is not None: body["list_type"] = list_type.value headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -5241,7 +5238,6 @@ def update( if list_type is not None: body["list_type"] = list_type.value headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -6584,9 +6580,7 @@ def delete(self, ip_access_list_id: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.0/ip-access-lists/{ip_access_list_id}", headers=headers) @@ -6671,7 +6665,6 @@ def replace( if list_type is not None: body["list_type"] = list_type.value headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -6728,7 +6721,6 @@ def update( if list_type is not None: body["list_type"] = list_type.value headers = { - "Accept": "application/json", "Content-Type": "application/json", } @@ -7453,9 +7445,7 @@ def delete(self, token_id: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.0/token-management/tokens/{token_id}", headers=headers) diff --git a/databricks/sdk/service/sharing.py b/databricks/sdk/service/sharing.py index 618c49b8f..ab6360b41 100755 --- a/databricks/sdk/service/sharing.py +++ b/databricks/sdk/service/sharing.py @@ -21,9 +21,39 @@ class AuthenticationType(Enum): """The delta sharing authentication type.""" DATABRICKS = "DATABRICKS" + OAUTH_CLIENT_CREDENTIALS = "OAUTH_CLIENT_CREDENTIALS" TOKEN = "TOKEN" +class ColumnTypeName(Enum): + """UC supported column types Copied from + https://src.dev.databricks.com/databricks/universe@23a85902bb58695ab9293adc9f327b0714b55e72/-/blob/managed-catalog/api/messages/table.proto?L68 + """ + + ARRAY = "ARRAY" + BINARY = "BINARY" + BOOLEAN = "BOOLEAN" + BYTE = "BYTE" + CHAR = "CHAR" + DATE = "DATE" + DECIMAL = "DECIMAL" + DOUBLE = "DOUBLE" + FLOAT = "FLOAT" + INT = "INT" + INTERVAL = "INTERVAL" + LONG = "LONG" + MAP = "MAP" + NULL = "NULL" + SHORT = "SHORT" + STRING = "STRING" + STRUCT = "STRUCT" + TABLE_TYPE = "TABLE_TYPE" + TIMESTAMP = "TIMESTAMP" + TIMESTAMP_NTZ = "TIMESTAMP_NTZ" + USER_DEFINED_TYPE = "USER_DEFINED_TYPE" + VARIANT = "VARIANT" + + @dataclass class CreateProvider: name: str @@ -229,6 +259,437 @@ def from_dict(cls, d: Dict[str, Any]) -> DeleteResponse: return cls() +@dataclass +class DeltaSharingDependency: + """Represents a UC dependency.""" + + function: Optional[DeltaSharingFunctionDependency] = None + """A Function in UC as a dependency.""" + + table: Optional[DeltaSharingTableDependency] = None + """A Table in UC as a dependency.""" + + def as_dict(self) -> dict: + """Serializes the DeltaSharingDependency into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.function: + body["function"] = self.function.as_dict() + if self.table: + body["table"] = self.table.as_dict() + return body + + def as_shallow_dict(self) -> dict: + """Serializes the DeltaSharingDependency into a shallow dictionary of its immediate attributes.""" + body = {} + if self.function: + body["function"] = self.function + if self.table: + body["table"] = self.table + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> DeltaSharingDependency: + """Deserializes the DeltaSharingDependency from a dictionary.""" + return cls( + function=_from_dict(d, "function", DeltaSharingFunctionDependency), + table=_from_dict(d, "table", DeltaSharingTableDependency), + ) + + +@dataclass +class DeltaSharingDependencyList: + """Represents a list of dependencies.""" + + dependencies: Optional[List[DeltaSharingDependency]] = None + """An array of Dependency.""" + + def as_dict(self) -> dict: + """Serializes the DeltaSharingDependencyList into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.dependencies: + body["dependencies"] = [v.as_dict() for v in self.dependencies] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the DeltaSharingDependencyList into a shallow dictionary of its immediate attributes.""" + body = {} + if self.dependencies: + body["dependencies"] = self.dependencies + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> DeltaSharingDependencyList: + """Deserializes the DeltaSharingDependencyList from a dictionary.""" + return cls(dependencies=_repeated_dict(d, "dependencies", DeltaSharingDependency)) + + +@dataclass +class DeltaSharingFunctionDependency: + """A Function in UC as a dependency.""" + + function_name: Optional[str] = None + + schema_name: Optional[str] = None + + def as_dict(self) -> dict: + """Serializes the DeltaSharingFunctionDependency into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.function_name is not None: + body["function_name"] = self.function_name + if self.schema_name is not None: + body["schema_name"] = self.schema_name + return body + + def as_shallow_dict(self) -> dict: + """Serializes the DeltaSharingFunctionDependency into a shallow dictionary of its immediate attributes.""" + body = {} + if self.function_name is not None: + body["function_name"] = self.function_name + if self.schema_name is not None: + body["schema_name"] = self.schema_name + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> DeltaSharingFunctionDependency: + """Deserializes the DeltaSharingFunctionDependency from a dictionary.""" + return cls(function_name=d.get("function_name", None), schema_name=d.get("schema_name", None)) + + +@dataclass +class DeltaSharingTableDependency: + """A Table in UC as a dependency.""" + + schema_name: Optional[str] = None + + table_name: Optional[str] = None + + def as_dict(self) -> dict: + """Serializes the DeltaSharingTableDependency into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.schema_name is not None: + body["schema_name"] = self.schema_name + if self.table_name is not None: + body["table_name"] = self.table_name + return body + + def as_shallow_dict(self) -> dict: + """Serializes the DeltaSharingTableDependency into a shallow dictionary of its immediate attributes.""" + body = {} + if self.schema_name is not None: + body["schema_name"] = self.schema_name + if self.table_name is not None: + body["table_name"] = self.table_name + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> DeltaSharingTableDependency: + """Deserializes the DeltaSharingTableDependency from a dictionary.""" + return cls(schema_name=d.get("schema_name", None), table_name=d.get("table_name", None)) + + +@dataclass +class Function: + aliases: Optional[List[RegisteredModelAlias]] = None + """The aliass of registered model.""" + + comment: Optional[str] = None + """The comment of the function.""" + + data_type: Optional[ColumnTypeName] = None + """The data type of the function.""" + + dependency_list: Optional[DeltaSharingDependencyList] = None + """The dependency list of the function.""" + + full_data_type: Optional[str] = None + """The full data type of the function.""" + + id: Optional[str] = None + """The id of the function.""" + + input_params: Optional[FunctionParameterInfos] = None + """The function parameter information.""" + + name: Optional[str] = None + """The name of the function.""" + + properties: Optional[str] = None + """The properties of the function.""" + + routine_definition: Optional[str] = None + """The routine definition of the function.""" + + schema: Optional[str] = None + """The name of the schema that the function belongs to.""" + + securable_kind: Optional[SharedSecurableKind] = None + """The securable kind of the function.""" + + share: Optional[str] = None + """The name of the share that the function belongs to.""" + + share_id: Optional[str] = None + """The id of the share that the function belongs to.""" + + storage_location: Optional[str] = None + """The storage location of the function.""" + + tags: Optional[List[catalog.TagKeyValue]] = None + """The tags of the function.""" + + def as_dict(self) -> dict: + """Serializes the Function into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.aliases: + body["aliases"] = [v.as_dict() for v in self.aliases] + if self.comment is not None: + body["comment"] = self.comment + if self.data_type is not None: + body["data_type"] = self.data_type.value + if self.dependency_list: + body["dependency_list"] = self.dependency_list.as_dict() + if self.full_data_type is not None: + body["full_data_type"] = self.full_data_type + if self.id is not None: + body["id"] = self.id + if self.input_params: + body["input_params"] = self.input_params.as_dict() + if self.name is not None: + body["name"] = self.name + if self.properties is not None: + body["properties"] = self.properties + if self.routine_definition is not None: + body["routine_definition"] = self.routine_definition + if self.schema is not None: + body["schema"] = self.schema + if self.securable_kind is not None: + body["securable_kind"] = self.securable_kind.value + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.tags: + body["tags"] = [v.as_dict() for v in self.tags] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the Function into a shallow dictionary of its immediate attributes.""" + body = {} + if self.aliases: + body["aliases"] = self.aliases + if self.comment is not None: + body["comment"] = self.comment + if self.data_type is not None: + body["data_type"] = self.data_type + if self.dependency_list: + body["dependency_list"] = self.dependency_list + if self.full_data_type is not None: + body["full_data_type"] = self.full_data_type + if self.id is not None: + body["id"] = self.id + if self.input_params: + body["input_params"] = self.input_params + if self.name is not None: + body["name"] = self.name + if self.properties is not None: + body["properties"] = self.properties + if self.routine_definition is not None: + body["routine_definition"] = self.routine_definition + if self.schema is not None: + body["schema"] = self.schema + if self.securable_kind is not None: + body["securable_kind"] = self.securable_kind + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.tags: + body["tags"] = self.tags + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> Function: + """Deserializes the Function from a dictionary.""" + return cls( + aliases=_repeated_dict(d, "aliases", RegisteredModelAlias), + comment=d.get("comment", None), + data_type=_enum(d, "data_type", ColumnTypeName), + dependency_list=_from_dict(d, "dependency_list", DeltaSharingDependencyList), + full_data_type=d.get("full_data_type", None), + id=d.get("id", None), + input_params=_from_dict(d, "input_params", FunctionParameterInfos), + name=d.get("name", None), + properties=d.get("properties", None), + routine_definition=d.get("routine_definition", None), + schema=d.get("schema", None), + securable_kind=_enum(d, "securable_kind", SharedSecurableKind), + share=d.get("share", None), + share_id=d.get("share_id", None), + storage_location=d.get("storage_location", None), + tags=_repeated_dict(d, "tags", catalog.TagKeyValue), + ) + + +@dataclass +class FunctionParameterInfo: + """Represents a parameter of a function. The same message is used for both input and output + columns.""" + + comment: Optional[str] = None + """The comment of the parameter.""" + + name: Optional[str] = None + """The name of the parameter.""" + + parameter_default: Optional[str] = None + """The default value of the parameter.""" + + parameter_mode: Optional[FunctionParameterMode] = None + """The mode of the function parameter.""" + + parameter_type: Optional[FunctionParameterType] = None + """The type of the function parameter.""" + + position: Optional[int] = None + """The position of the parameter.""" + + type_interval_type: Optional[str] = None + """The interval type of the parameter type.""" + + type_json: Optional[str] = None + """The type of the parameter in JSON format.""" + + type_name: Optional[ColumnTypeName] = None + """The type of the parameter in Enum format.""" + + type_precision: Optional[int] = None + """The precision of the parameter type.""" + + type_scale: Optional[int] = None + """The scale of the parameter type.""" + + type_text: Optional[str] = None + """The type of the parameter in text format.""" + + def as_dict(self) -> dict: + """Serializes the FunctionParameterInfo into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.name is not None: + body["name"] = self.name + if self.parameter_default is not None: + body["parameter_default"] = self.parameter_default + if self.parameter_mode is not None: + body["parameter_mode"] = self.parameter_mode.value + if self.parameter_type is not None: + body["parameter_type"] = self.parameter_type.value + if self.position is not None: + body["position"] = self.position + if self.type_interval_type is not None: + body["type_interval_type"] = self.type_interval_type + if self.type_json is not None: + body["type_json"] = self.type_json + if self.type_name is not None: + body["type_name"] = self.type_name.value + if self.type_precision is not None: + body["type_precision"] = self.type_precision + if self.type_scale is not None: + body["type_scale"] = self.type_scale + if self.type_text is not None: + body["type_text"] = self.type_text + return body + + def as_shallow_dict(self) -> dict: + """Serializes the FunctionParameterInfo into a shallow dictionary of its immediate attributes.""" + body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.name is not None: + body["name"] = self.name + if self.parameter_default is not None: + body["parameter_default"] = self.parameter_default + if self.parameter_mode is not None: + body["parameter_mode"] = self.parameter_mode + if self.parameter_type is not None: + body["parameter_type"] = self.parameter_type + if self.position is not None: + body["position"] = self.position + if self.type_interval_type is not None: + body["type_interval_type"] = self.type_interval_type + if self.type_json is not None: + body["type_json"] = self.type_json + if self.type_name is not None: + body["type_name"] = self.type_name + if self.type_precision is not None: + body["type_precision"] = self.type_precision + if self.type_scale is not None: + body["type_scale"] = self.type_scale + if self.type_text is not None: + body["type_text"] = self.type_text + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> FunctionParameterInfo: + """Deserializes the FunctionParameterInfo from a dictionary.""" + return cls( + comment=d.get("comment", None), + name=d.get("name", None), + parameter_default=d.get("parameter_default", None), + parameter_mode=_enum(d, "parameter_mode", FunctionParameterMode), + parameter_type=_enum(d, "parameter_type", FunctionParameterType), + position=d.get("position", None), + type_interval_type=d.get("type_interval_type", None), + type_json=d.get("type_json", None), + type_name=_enum(d, "type_name", ColumnTypeName), + type_precision=d.get("type_precision", None), + type_scale=d.get("type_scale", None), + type_text=d.get("type_text", None), + ) + + +@dataclass +class FunctionParameterInfos: + parameters: Optional[List[FunctionParameterInfo]] = None + """The list of parameters of the function.""" + + def as_dict(self) -> dict: + """Serializes the FunctionParameterInfos into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.parameters: + body["parameters"] = [v.as_dict() for v in self.parameters] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the FunctionParameterInfos into a shallow dictionary of its immediate attributes.""" + body = {} + if self.parameters: + body["parameters"] = self.parameters + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> FunctionParameterInfos: + """Deserializes the FunctionParameterInfos from a dictionary.""" + return cls(parameters=_repeated_dict(d, "parameters", FunctionParameterInfo)) + + +class FunctionParameterMode(Enum): + + IN = "IN" + INOUT = "INOUT" + OUT = "OUT" + + +class FunctionParameterType(Enum): + + COLUMN = "COLUMN" + PARAM = "PARAM" + + @dataclass class GetActivationUrlInfoResponse: def as_dict(self) -> dict: @@ -283,6 +744,42 @@ def from_dict(cls, d: Dict[str, Any]) -> GetRecipientSharePermissionsResponse: ) +@dataclass +class GetSharePermissionsResponse: + next_page_token: Optional[str] = None + """Opaque token to retrieve the next page of results. Absent if there are no more pages. + __page_token__ should be set to this value for the next request (for the next page of results).""" + + privilege_assignments: Optional[List[PrivilegeAssignment]] = None + """The privileges assigned to each principal""" + + def as_dict(self) -> dict: + """Serializes the GetSharePermissionsResponse into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.next_page_token is not None: + body["next_page_token"] = self.next_page_token + if self.privilege_assignments: + body["privilege_assignments"] = [v.as_dict() for v in self.privilege_assignments] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the GetSharePermissionsResponse into a shallow dictionary of its immediate attributes.""" + body = {} + if self.next_page_token is not None: + body["next_page_token"] = self.next_page_token + if self.privilege_assignments: + body["privilege_assignments"] = self.privilege_assignments + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> GetSharePermissionsResponse: + """Deserializes the GetSharePermissionsResponse from a dictionary.""" + return cls( + next_page_token=d.get("next_page_token", None), + privilege_assignments=_repeated_dict(d, "privilege_assignments", PrivilegeAssignment), + ) + + @dataclass class IpAccessList: allowed_ip_addresses: Optional[List[str]] = None @@ -308,6 +805,59 @@ def from_dict(cls, d: Dict[str, Any]) -> IpAccessList: return cls(allowed_ip_addresses=d.get("allowed_ip_addresses", None)) +@dataclass +class ListProviderShareAssetsResponse: + """Response to ListProviderShareAssets, which contains the list of assets of a share.""" + + functions: Optional[List[Function]] = None + """The list of functions in the share.""" + + notebooks: Optional[List[NotebookFile]] = None + """The list of notebooks in the share.""" + + tables: Optional[List[Table]] = None + """The list of tables in the share.""" + + volumes: Optional[List[Volume]] = None + """The list of volumes in the share.""" + + def as_dict(self) -> dict: + """Serializes the ListProviderShareAssetsResponse into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.functions: + body["functions"] = [v.as_dict() for v in self.functions] + if self.notebooks: + body["notebooks"] = [v.as_dict() for v in self.notebooks] + if self.tables: + body["tables"] = [v.as_dict() for v in self.tables] + if self.volumes: + body["volumes"] = [v.as_dict() for v in self.volumes] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the ListProviderShareAssetsResponse into a shallow dictionary of its immediate attributes.""" + body = {} + if self.functions: + body["functions"] = self.functions + if self.notebooks: + body["notebooks"] = self.notebooks + if self.tables: + body["tables"] = self.tables + if self.volumes: + body["volumes"] = self.volumes + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> ListProviderShareAssetsResponse: + """Deserializes the ListProviderShareAssetsResponse from a dictionary.""" + return cls( + functions=_repeated_dict(d, "functions", Function), + notebooks=_repeated_dict(d, "notebooks", NotebookFile), + tables=_repeated_dict(d, "tables", Table), + volumes=_repeated_dict(d, "volumes", Volume), + ) + + @dataclass class ListProviderSharesResponse: next_page_token: Optional[str] = None @@ -445,52 +995,94 @@ def from_dict(cls, d: Dict[str, Any]) -> ListSharesResponse: @dataclass -class Partition: - values: Optional[List[PartitionValue]] = None - """An array of partition values.""" +class NotebookFile: + comment: Optional[str] = None + """The comment of the notebook file.""" + + id: Optional[str] = None + """The id of the notebook file.""" + + name: Optional[str] = None + """Name of the notebook file.""" + + share: Optional[str] = None + """The name of the share that the notebook file belongs to.""" + + share_id: Optional[str] = None + """The id of the share that the notebook file belongs to.""" + + tags: Optional[List[catalog.TagKeyValue]] = None + """The tags of the notebook file.""" def as_dict(self) -> dict: - """Serializes the Partition into a dictionary suitable for use as a JSON request body.""" + """Serializes the NotebookFile into a dictionary suitable for use as a JSON request body.""" body = {} - if self.values: - body["values"] = [v.as_dict() for v in self.values] + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.name is not None: + body["name"] = self.name + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = [v.as_dict() for v in self.tags] return body def as_shallow_dict(self) -> dict: - """Serializes the Partition into a shallow dictionary of its immediate attributes.""" + """Serializes the NotebookFile into a shallow dictionary of its immediate attributes.""" body = {} - if self.values: - body["values"] = self.values + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.name is not None: + body["name"] = self.name + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = self.tags return body @classmethod - def from_dict(cls, d: Dict[str, Any]) -> Partition: - """Deserializes the Partition from a dictionary.""" - return cls(values=_repeated_dict(d, "values", PartitionValue)) + def from_dict(cls, d: Dict[str, Any]) -> NotebookFile: + """Deserializes the NotebookFile from a dictionary.""" + return cls( + comment=d.get("comment", None), + id=d.get("id", None), + name=d.get("name", None), + share=d.get("share", None), + share_id=d.get("share_id", None), + tags=_repeated_dict(d, "tags", catalog.TagKeyValue), + ) @dataclass -class PartitionSpecificationPartition: +class Partition: values: Optional[List[PartitionValue]] = None """An array of partition values.""" def as_dict(self) -> dict: - """Serializes the PartitionSpecificationPartition into a dictionary suitable for use as a JSON request body.""" + """Serializes the Partition into a dictionary suitable for use as a JSON request body.""" body = {} if self.values: body["values"] = [v.as_dict() for v in self.values] return body def as_shallow_dict(self) -> dict: - """Serializes the PartitionSpecificationPartition into a shallow dictionary of its immediate attributes.""" + """Serializes the Partition into a shallow dictionary of its immediate attributes.""" body = {} if self.values: body["values"] = self.values return body @classmethod - def from_dict(cls, d: Dict[str, Any]) -> PartitionSpecificationPartition: - """Deserializes the PartitionSpecificationPartition from a dictionary.""" + def from_dict(cls, d: Dict[str, Any]) -> Partition: + """Deserializes the Partition from a dictionary.""" return cls(values=_repeated_dict(d, "values", PartitionValue)) @@ -553,6 +1145,45 @@ class PartitionValueOp(Enum): LIKE = "LIKE" +@dataclass +class PermissionsChange: + add: Optional[List[str]] = None + """The set of privileges to add.""" + + principal: Optional[str] = None + """The principal whose privileges we are changing.""" + + remove: Optional[List[str]] = None + """The set of privileges to remove.""" + + def as_dict(self) -> dict: + """Serializes the PermissionsChange into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.add: + body["add"] = [v for v in self.add] + if self.principal is not None: + body["principal"] = self.principal + if self.remove: + body["remove"] = [v for v in self.remove] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the PermissionsChange into a shallow dictionary of its immediate attributes.""" + body = {} + if self.add: + body["add"] = self.add + if self.principal is not None: + body["principal"] = self.principal + if self.remove: + body["remove"] = self.remove + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> PermissionsChange: + """Deserializes the PermissionsChange from a dictionary.""" + return cls(add=d.get("add", None), principal=d.get("principal", None), remove=d.get("remove", None)) + + class Privilege(Enum): ACCESS = "ACCESS" @@ -1096,6 +1727,38 @@ def from_dict(cls, d: Dict[str, Any]) -> RecipientTokenInfo: ) +@dataclass +class RegisteredModelAlias: + alias_name: Optional[str] = None + """Name of the alias.""" + + version_num: Optional[int] = None + """Numeric model version that alias will reference.""" + + def as_dict(self) -> dict: + """Serializes the RegisteredModelAlias into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.alias_name is not None: + body["alias_name"] = self.alias_name + if self.version_num is not None: + body["version_num"] = self.version_num + return body + + def as_shallow_dict(self) -> dict: + """Serializes the RegisteredModelAlias into a shallow dictionary of its immediate attributes.""" + body = {} + if self.alias_name is not None: + body["alias_name"] = self.alias_name + if self.version_num is not None: + body["version_num"] = self.version_num + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> RegisteredModelAlias: + """Deserializes the RegisteredModelAlias from a dictionary.""" + return cls(alias_name=d.get("alias_name", None), version_num=d.get("version_num", None)) + + @dataclass class RetrieveTokenResponse: bearer_token: Optional[str] = None @@ -1347,9 +2010,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ShareToPrivilegeAssignment: @dataclass class SharedDataObject: name: str - """A fully qualified name that uniquely identifies a data object. - - For example, a table's fully qualified name is in the format of `..`.""" + """A fully qualified name that uniquely identifies a data object. For example, a table's fully + qualified name is in the format of `..
`,""" added_at: Optional[int] = None """The time when this data object is added to the share, in epoch milliseconds.""" @@ -1361,7 +2023,7 @@ class SharedDataObject: """Whether to enable cdf or indicate if cdf is enabled on the shared object.""" comment: Optional[str] = None - """A user-provided comment when adding the data object to the share. [Update:OPT]""" + """A user-provided comment when adding the data object to the share.""" content: Optional[str] = None """The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be @@ -1395,10 +2057,10 @@ class SharedDataObject: """One of: **ACTIVE**, **PERMISSION_DENIED**.""" string_shared_as: Optional[str] = None - """A user-provided new name for the data object within the share. If this new name is not provided, - the object's original name will be used as the `string_shared_as` name. The `string_shared_as` - name must be unique within a share. For notebooks, the new name should be the new notebook file - name.""" + """A user-provided new name for the shared object within the share. If this new name is not not + provided, the object's original name will be used as the `string_shared_as` name. The + `string_shared_as` name must be unique for objects of the same type within a Share. For + notebooks, the new name should be the new notebook file name.""" def as_dict(self) -> dict: """Serializes the SharedDataObject into a dictionary suitable for use as a JSON request body.""" @@ -1485,7 +2147,6 @@ def from_dict(cls, d: Dict[str, Any]) -> SharedDataObject: class SharedDataObjectDataObjectType(Enum): - """The type of the data object.""" FEATURE_SPEC = "FEATURE_SPEC" FUNCTION = "FUNCTION" @@ -1499,15 +2160,12 @@ class SharedDataObjectDataObjectType(Enum): class SharedDataObjectHistoryDataSharingStatus(Enum): - """Whether to enable or disable sharing of data history. If not specified, the default is - **DISABLED**.""" DISABLED = "DISABLED" ENABLED = "ENABLED" class SharedDataObjectStatus(Enum): - """One of: **ACTIVE**, **PERMISSION_DENIED**.""" ACTIVE = "ACTIVE" PERMISSION_DENIED = "PERMISSION_DENIED" @@ -1549,29 +2207,177 @@ def from_dict(cls, d: Dict[str, Any]) -> SharedDataObjectUpdate: class SharedDataObjectUpdateAction(Enum): - """One of: **ADD**, **REMOVE**, **UPDATE**.""" ADD = "ADD" REMOVE = "REMOVE" UPDATE = "UPDATE" +class SharedSecurableKind(Enum): + """The SecurableKind of a delta-shared object.""" + + FUNCTION_FEATURE_SPEC = "FUNCTION_FEATURE_SPEC" + FUNCTION_REGISTERED_MODEL = "FUNCTION_REGISTERED_MODEL" + FUNCTION_STANDARD = "FUNCTION_STANDARD" + + @dataclass -class UpdatePermissionsResponse: +class Table: + comment: Optional[str] = None + """The comment of the table.""" + + id: Optional[str] = None + """The id of the table.""" + + internal_attributes: Optional[TableInternalAttributes] = None + """Internal information for D2D sharing that should not be disclosed to external users.""" + + materialized_table_name: Optional[str] = None + """The name of a materialized table.""" + + name: Optional[str] = None + """The name of the table.""" + + schema: Optional[str] = None + """The name of the schema that the table belongs to.""" + + share: Optional[str] = None + """The name of the share that the table belongs to.""" + + share_id: Optional[str] = None + """The id of the share that the table belongs to.""" + + tags: Optional[List[catalog.TagKeyValue]] = None + """The Tags of the table.""" + def as_dict(self) -> dict: - """Serializes the UpdatePermissionsResponse into a dictionary suitable for use as a JSON request body.""" + """Serializes the Table into a dictionary suitable for use as a JSON request body.""" body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.internal_attributes: + body["internal_attributes"] = self.internal_attributes.as_dict() + if self.materialized_table_name is not None: + body["materialized_table_name"] = self.materialized_table_name + if self.name is not None: + body["name"] = self.name + if self.schema is not None: + body["schema"] = self.schema + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = [v.as_dict() for v in self.tags] return body def as_shallow_dict(self) -> dict: - """Serializes the UpdatePermissionsResponse into a shallow dictionary of its immediate attributes.""" + """Serializes the Table into a shallow dictionary of its immediate attributes.""" body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.internal_attributes: + body["internal_attributes"] = self.internal_attributes + if self.materialized_table_name is not None: + body["materialized_table_name"] = self.materialized_table_name + if self.name is not None: + body["name"] = self.name + if self.schema is not None: + body["schema"] = self.schema + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = self.tags return body @classmethod - def from_dict(cls, d: Dict[str, Any]) -> UpdatePermissionsResponse: - """Deserializes the UpdatePermissionsResponse from a dictionary.""" - return cls() + def from_dict(cls, d: Dict[str, Any]) -> Table: + """Deserializes the Table from a dictionary.""" + return cls( + comment=d.get("comment", None), + id=d.get("id", None), + internal_attributes=_from_dict(d, "internal_attributes", TableInternalAttributes), + materialized_table_name=d.get("materialized_table_name", None), + name=d.get("name", None), + schema=d.get("schema", None), + share=d.get("share", None), + share_id=d.get("share_id", None), + tags=_repeated_dict(d, "tags", catalog.TagKeyValue), + ) + + +@dataclass +class TableInternalAttributes: + """Internal information for D2D sharing that should not be disclosed to external users.""" + + parent_storage_location: Optional[str] = None + """Will be populated in the reconciliation response for VIEW and FOREIGN_TABLE, with the value of + the parent UC entity's storage_location, following the same logic as getManagedEntityPath in + CreateStagingTableHandler, which is used to store the materialized table for a shared + VIEW/FOREIGN_TABLE for D2O queries. The value will be used on the recipient side to be + whitelisted when SEG is enabled on the workspace of the recipient, to allow the recipient users + to query this shared VIEW/FOREIGN_TABLE.""" + + storage_location: Optional[str] = None + """The cloud storage location of a shard table with DIRECTORY_BASED_TABLE type.""" + + type: Optional[TableInternalAttributesSharedTableType] = None + """The type of the shared table.""" + + view_definition: Optional[str] = None + """The view definition of a shared view. DEPRECATED.""" + + def as_dict(self) -> dict: + """Serializes the TableInternalAttributes into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.parent_storage_location is not None: + body["parent_storage_location"] = self.parent_storage_location + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.type is not None: + body["type"] = self.type.value + if self.view_definition is not None: + body["view_definition"] = self.view_definition + return body + + def as_shallow_dict(self) -> dict: + """Serializes the TableInternalAttributes into a shallow dictionary of its immediate attributes.""" + body = {} + if self.parent_storage_location is not None: + body["parent_storage_location"] = self.parent_storage_location + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.type is not None: + body["type"] = self.type + if self.view_definition is not None: + body["view_definition"] = self.view_definition + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> TableInternalAttributes: + """Deserializes the TableInternalAttributes from a dictionary.""" + return cls( + parent_storage_location=d.get("parent_storage_location", None), + storage_location=d.get("storage_location", None), + type=_enum(d, "type", TableInternalAttributesSharedTableType), + view_definition=d.get("view_definition", None), + ) + + +class TableInternalAttributesSharedTableType(Enum): + + DIRECTORY_BASED_TABLE = "DIRECTORY_BASED_TABLE" + FILE_BASED_TABLE = "FILE_BASED_TABLE" + FOREIGN_TABLE = "FOREIGN_TABLE" + MATERIALIZED_VIEW = "MATERIALIZED_VIEW" + STREAMING_TABLE = "STREAMING_TABLE" + VIEW = "VIEW" @dataclass @@ -1780,35 +2586,19 @@ def from_dict(cls, d: Dict[str, Any]) -> UpdateShare: @dataclass class UpdateSharePermissions: - changes: Optional[List[catalog.PermissionsChange]] = None + changes: Optional[List[PermissionsChange]] = None """Array of permission changes.""" - max_results: Optional[int] = None - """Maximum number of permissions to return. - when set to 0, the page length is set to a server - configured value (recommended); - when set to a value greater than 0, the page length is the - minimum of this value and a server configured value; - when set to a value less than 0, an - invalid parameter error is returned; - If not set, all valid permissions are returned (not - recommended). - Note: The number of returned permissions might be less than the specified - max_results size, even zero. The only definitive indication that no further permissions can be - fetched is when the next_page_token is unset from the response.""" - name: Optional[str] = None """The name of the share.""" - page_token: Optional[str] = None - """Opaque pagination token to go to next page based on previous query.""" - def as_dict(self) -> dict: """Serializes the UpdateSharePermissions into a dictionary suitable for use as a JSON request body.""" body = {} if self.changes: body["changes"] = [v.as_dict() for v in self.changes] - if self.max_results is not None: - body["max_results"] = self.max_results if self.name is not None: body["name"] = self.name - if self.page_token is not None: - body["page_token"] = self.page_token return body def as_shallow_dict(self) -> dict: @@ -1816,25 +2606,159 @@ def as_shallow_dict(self) -> dict: body = {} if self.changes: body["changes"] = self.changes - if self.max_results is not None: - body["max_results"] = self.max_results if self.name is not None: body["name"] = self.name - if self.page_token is not None: - body["page_token"] = self.page_token return body @classmethod def from_dict(cls, d: Dict[str, Any]) -> UpdateSharePermissions: """Deserializes the UpdateSharePermissions from a dictionary.""" + return cls(changes=_repeated_dict(d, "changes", PermissionsChange), name=d.get("name", None)) + + +@dataclass +class UpdateSharePermissionsResponse: + privilege_assignments: Optional[List[PrivilegeAssignment]] = None + """The privileges assigned to each principal""" + + def as_dict(self) -> dict: + """Serializes the UpdateSharePermissionsResponse into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.privilege_assignments: + body["privilege_assignments"] = [v.as_dict() for v in self.privilege_assignments] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the UpdateSharePermissionsResponse into a shallow dictionary of its immediate attributes.""" + body = {} + if self.privilege_assignments: + body["privilege_assignments"] = self.privilege_assignments + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> UpdateSharePermissionsResponse: + """Deserializes the UpdateSharePermissionsResponse from a dictionary.""" + return cls(privilege_assignments=_repeated_dict(d, "privilege_assignments", PrivilegeAssignment)) + + +@dataclass +class Volume: + comment: Optional[str] = None + """The comment of the volume.""" + + id: Optional[str] = None + """This id maps to the shared_volume_id in database Recipient needs shared_volume_id for recon to + check if this volume is already in recipient's DB or not.""" + + internal_attributes: Optional[VolumeInternalAttributes] = None + """Internal attributes for D2D sharing that should not be disclosed to external users.""" + + name: Optional[str] = None + """The name of the volume.""" + + schema: Optional[str] = None + """The name of the schema that the volume belongs to.""" + + share: Optional[str] = None + """The name of the share that the volume belongs to.""" + + share_id: Optional[str] = None + """/ The id of the share that the volume belongs to.""" + + tags: Optional[List[catalog.TagKeyValue]] = None + """The tags of the volume.""" + + def as_dict(self) -> dict: + """Serializes the Volume into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.internal_attributes: + body["internal_attributes"] = self.internal_attributes.as_dict() + if self.name is not None: + body["name"] = self.name + if self.schema is not None: + body["schema"] = self.schema + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = [v.as_dict() for v in self.tags] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the Volume into a shallow dictionary of its immediate attributes.""" + body = {} + if self.comment is not None: + body["comment"] = self.comment + if self.id is not None: + body["id"] = self.id + if self.internal_attributes: + body["internal_attributes"] = self.internal_attributes + if self.name is not None: + body["name"] = self.name + if self.schema is not None: + body["schema"] = self.schema + if self.share is not None: + body["share"] = self.share + if self.share_id is not None: + body["share_id"] = self.share_id + if self.tags: + body["tags"] = self.tags + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> Volume: + """Deserializes the Volume from a dictionary.""" return cls( - changes=_repeated_dict(d, "changes", catalog.PermissionsChange), - max_results=d.get("max_results", None), + comment=d.get("comment", None), + id=d.get("id", None), + internal_attributes=_from_dict(d, "internal_attributes", VolumeInternalAttributes), name=d.get("name", None), - page_token=d.get("page_token", None), + schema=d.get("schema", None), + share=d.get("share", None), + share_id=d.get("share_id", None), + tags=_repeated_dict(d, "tags", catalog.TagKeyValue), ) +@dataclass +class VolumeInternalAttributes: + """Internal information for D2D sharing that should not be disclosed to external users.""" + + storage_location: Optional[str] = None + """The cloud storage location of the volume""" + + type: Optional[str] = None + """The type of the shared volume.""" + + def as_dict(self) -> dict: + """Serializes the VolumeInternalAttributes into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.type is not None: + body["type"] = self.type + return body + + def as_shallow_dict(self) -> dict: + """Serializes the VolumeInternalAttributes into a shallow dictionary of its immediate attributes.""" + body = {} + if self.storage_location is not None: + body["storage_location"] = self.storage_location + if self.type is not None: + body["type"] = self.type + return body + + @classmethod + def from_dict(cls, d: Dict[str, Any]) -> VolumeInternalAttributes: + """Deserializes the VolumeInternalAttributes from a dictionary.""" + return cls(storage_location=d.get("storage_location", None), type=d.get("type", None)) + + class ProvidersAPI: """A data provider is an object representing the organization in the real world who shares the data. A provider contains shares which further contain the shared data.""" @@ -1896,9 +2820,7 @@ def delete(self, name: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.1/unity-catalog/providers/{name}", headers=headers) @@ -1973,6 +2895,55 @@ def list( return query["page_token"] = json["next_page_token"] + def list_provider_share_assets( + self, + provider_name: str, + share_name: str, + *, + function_max_results: Optional[int] = None, + notebook_max_results: Optional[int] = None, + table_max_results: Optional[int] = None, + volume_max_results: Optional[int] = None, + ) -> ListProviderShareAssetsResponse: + """List assets by provider share. + + Get arrays of assets associated with a specified provider's share. The caller is the recipient of the + share. + + :param provider_name: str + The name of the provider who owns the share. + :param share_name: str + The name of the share. + :param function_max_results: int (optional) + Maximum number of functions to return. + :param notebook_max_results: int (optional) + Maximum number of notebooks to return. + :param table_max_results: int (optional) + Maximum number of tables to return. + :param volume_max_results: int (optional) + Maximum number of volumes to return. + + :returns: :class:`ListProviderShareAssetsResponse` + """ + + query = {} + if function_max_results is not None: + query["function_max_results"] = function_max_results + if notebook_max_results is not None: + query["notebook_max_results"] = notebook_max_results + if table_max_results is not None: + query["table_max_results"] = table_max_results + if volume_max_results is not None: + query["volume_max_results"] = volume_max_results + headers = { + "Accept": "application/json", + } + + res = self._api.do( + "GET", f"/api/2.1/data-sharing/providers/{provider_name}/shares/{share_name}", query=query, headers=headers + ) + return ListProviderShareAssetsResponse.from_dict(res) + def list_shares( self, name: str, *, max_results: Optional[int] = None, page_token: Optional[str] = None ) -> Iterator[ProviderShare]: @@ -2217,9 +3188,7 @@ def delete(self, name: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.1/unity-catalog/recipients/{name}", headers=headers) @@ -2468,9 +3437,7 @@ def delete(self, name: str): """ - headers = { - "Accept": "application/json", - } + headers = {} self._api.do("DELETE", f"/api/2.1/unity-catalog/shares/{name}", headers=headers) @@ -2540,7 +3507,7 @@ def list(self, *, max_results: Optional[int] = None, page_token: Optional[str] = def share_permissions( self, name: str, *, max_results: Optional[int] = None, page_token: Optional[str] = None - ) -> catalog.PermissionsList: + ) -> GetSharePermissionsResponse: """Get permissions. Gets the permissions for a data share from the metastore. The caller must be a metastore admin or the @@ -2559,7 +3526,7 @@ def share_permissions( :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - :returns: :class:`PermissionsList` + :returns: :class:`GetSharePermissionsResponse` """ query = {} @@ -2572,7 +3539,7 @@ def share_permissions( } res = self._api.do("GET", f"/api/2.1/unity-catalog/shares/{name}/permissions", query=query, headers=headers) - return catalog.PermissionsList.from_dict(res) + return GetSharePermissionsResponse.from_dict(res) def update( self, @@ -2637,51 +3604,30 @@ def update( return ShareInfo.from_dict(res) def update_permissions( - self, - name: str, - *, - changes: Optional[List[catalog.PermissionsChange]] = None, - max_results: Optional[int] = None, - page_token: Optional[str] = None, - ): + self, name: str, *, changes: Optional[List[PermissionsChange]] = None + ) -> UpdateSharePermissionsResponse: """Update permissions. Updates the permissions for a data share in the metastore. The caller must be a metastore admin or an owner of the share. - For new recipient grants, the user must also be the owner of the recipients. recipient revocations do - not require additional privileges. + For new recipient grants, the user must also be the recipient owner or metastore admin. recipient + revocations do not require additional privileges. :param name: str The name of the share. :param changes: List[:class:`PermissionsChange`] (optional) Array of permission changes. - :param max_results: int (optional) - Maximum number of permissions to return. - when set to 0, the page length is set to a server - configured value (recommended); - when set to a value greater than 0, the page length is the minimum - of this value and a server configured value; - when set to a value less than 0, an invalid parameter - error is returned; - If not set, all valid permissions are returned (not recommended). - Note: The - number of returned permissions might be less than the specified max_results size, even zero. The - only definitive indication that no further permissions can be fetched is when the next_page_token is - unset from the response. - :param page_token: str (optional) - Opaque pagination token to go to next page based on previous query. - + :returns: :class:`UpdateSharePermissionsResponse` """ body = {} - query = {} if changes is not None: body["changes"] = [v.as_dict() for v in changes] - if max_results is not None: - query["max_results"] = max_results - if page_token is not None: - query["page_token"] = page_token headers = { "Accept": "application/json", "Content-Type": "application/json", } - self._api.do( - "PATCH", f"/api/2.1/unity-catalog/shares/{name}/permissions", query=query, body=body, headers=headers - ) + res = self._api.do("PATCH", f"/api/2.1/unity-catalog/shares/{name}/permissions", body=body, headers=headers) + return UpdateSharePermissionsResponse.from_dict(res) diff --git a/databricks/sdk/service/vectorsearch.py b/databricks/sdk/service/vectorsearch.py index 5831517a7..e75578374 100755 --- a/databricks/sdk/service/vectorsearch.py +++ b/databricks/sdk/service/vectorsearch.py @@ -974,6 +974,9 @@ class QueryVectorIndexRequest: columns: List[str] """List of column names to include in the response.""" + columns_to_rerank: Optional[List[str]] = None + """Column names used to retrieve data to send to the reranker.""" + filters_json: Optional[str] = None """JSON string representing query filters. @@ -1005,6 +1008,8 @@ def as_dict(self) -> dict: body = {} if self.columns: body["columns"] = [v for v in self.columns] + if self.columns_to_rerank: + body["columns_to_rerank"] = [v for v in self.columns_to_rerank] if self.filters_json is not None: body["filters_json"] = self.filters_json if self.index_name is not None: @@ -1026,6 +1031,8 @@ def as_shallow_dict(self) -> dict: body = {} if self.columns: body["columns"] = self.columns + if self.columns_to_rerank: + body["columns_to_rerank"] = self.columns_to_rerank if self.filters_json is not None: body["filters_json"] = self.filters_json if self.index_name is not None: @@ -1047,6 +1054,7 @@ def from_dict(cls, d: Dict[str, Any]) -> QueryVectorIndexRequest: """Deserializes the QueryVectorIndexRequest from a dictionary.""" return cls( columns=d.get("columns", None), + columns_to_rerank=d.get("columns_to_rerank", None), filters_json=d.get("filters_json", None), index_name=d.get("index_name", None), num_results=d.get("num_results", None), @@ -1065,7 +1073,7 @@ class QueryVectorIndexResponse: next_page_token: Optional[str] = None """[Optional] Token that can be used in `QueryVectorIndexNextPage` API to get next page of results. If more than 1000 results satisfy the query, they are returned in groups of 1000. Empty value - means no more results.""" + means no more results. The maximum number of results that can be returned is 10,000.""" result: Optional[ResultData] = None """Data returned in the query result.""" @@ -1905,6 +1913,7 @@ def query_index( index_name: str, columns: List[str], *, + columns_to_rerank: Optional[List[str]] = None, filters_json: Optional[str] = None, num_results: Optional[int] = None, query_text: Optional[str] = None, @@ -1920,6 +1929,8 @@ def query_index( Name of the vector index to query. :param columns: List[str] List of column names to include in the response. + :param columns_to_rerank: List[str] (optional) + Column names used to retrieve data to send to the reranker. :param filters_json: str (optional) JSON string representing query filters. @@ -1943,6 +1954,8 @@ def query_index( body = {} if columns is not None: body["columns"] = [v for v in columns] + if columns_to_rerank is not None: + body["columns_to_rerank"] = [v for v in columns_to_rerank] if filters_json is not None: body["filters_json"] = filters_json if num_results is not None: diff --git a/databricks/sdk/service/workspace.py b/databricks/sdk/service/workspace.py index c10e03939..6753ad880 100755 --- a/databricks/sdk/service/workspace.py +++ b/databricks/sdk/service/workspace.py @@ -657,17 +657,22 @@ def from_dict(cls, d: Dict[str, Any]) -> DeleteSecretResponse: class ExportFormat(Enum): + """The format for workspace import and export.""" AUTO = "AUTO" DBC = "DBC" HTML = "HTML" JUPYTER = "JUPYTER" + RAW = "RAW" R_MARKDOWN = "R_MARKDOWN" SOURCE = "SOURCE" @dataclass class ExportResponse: + """The request field `direct_download` determines whether a JSON response or binary contents are + returned by this endpoint.""" + content: Optional[str] = None """The base64-encoded content. If the limit (10MB) is exceeded, exception with error code **MAX_NOTEBOOK_SIZE_EXCEEDED** is thrown.""" @@ -975,17 +980,7 @@ def from_dict(cls, d: Dict[str, Any]) -> Import: class ImportFormat(Enum): - """This specifies the format of the file to be imported. - - The value is case sensitive. - - - `AUTO`: The item is imported depending on an analysis of the item's extension and the header - content provided in the request. If the item is imported as a notebook, then the item's - extension is automatically removed. - `SOURCE`: The notebook or directory is imported as source - code. - `HTML`: The notebook is imported as an HTML file. - `JUPYTER`: The notebook is imported - as a Jupyter/IPython Notebook file. - `DBC`: The notebook is imported in Databricks archive - format. Required for directories. - `R_MARKDOWN`: The notebook is imported from R Markdown - format.""" + """The format for workspace import and export.""" AUTO = "AUTO" DBC = "DBC" @@ -1015,7 +1010,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ImportResponse: class Language(Enum): - """The language of the object. This value is set only if the object type is `NOTEBOOK`.""" + """The language of notebook.""" PYTHON = "PYTHON" R = "R" @@ -1227,11 +1222,13 @@ def from_dict(cls, d: Dict[str, Any]) -> MkdirsResponse: @dataclass class ObjectInfo: + """The information of the object in workspace. It will be returned by ``list`` and ``get-status``.""" + created_at: Optional[int] = None """Only applicable to files. The creation UTC timestamp.""" language: Optional[Language] = None - """The language of the object. This value is set only if the object type is `NOTEBOOK`.""" + """The language of the object. This value is set only if the object type is ``NOTEBOOK``.""" modified_at: Optional[int] = None """Only applicable to files, the last modified UTC timestamp.""" @@ -1313,11 +1310,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ObjectInfo: class ObjectType(Enum): - """The type of the object in workspace. - - - `NOTEBOOK`: document that contains runnable code, visualizations, and explanatory text. - - `DIRECTORY`: directory - `LIBRARY`: library - `FILE`: file - `REPO`: repository - `DASHBOARD`: - Lakeview dashboard""" + """The type of the object in workspace.""" DASHBOARD = "DASHBOARD" DIRECTORY = "DIRECTORY" diff --git a/docs/account/billing/billable_usage.rst b/docs/account/billing/billable_usage.rst index 181b91cc3..b3bda9c61 100644 --- a/docs/account/billing/billable_usage.rst +++ b/docs/account/billing/billable_usage.rst @@ -21,16 +21,16 @@ resp = a.billable_usage.download(start_month="2024-08", end_month="2024-09") Return billable usage logs. - + Returns billable usage logs in CSV format for the specified account and date range. For the data schema, see [CSV file schema]. Note that this method might take multiple minutes to complete. - + **Warning**: Depending on the queried date range, the number of workspaces in the account, the size of the response and the internet speed of the caller, this API may hit a timeout after a few minutes. If you experience this, try to mitigate by calling the API with narrower date ranges. - + [CSV file schema]: https://docs.databricks.com/administration-guide/account-settings/usage-analysis.html#schema - + :param start_month: str Format: `YYYY-MM`. First month to return billable usage logs for. This field is required. :param end_month: str @@ -39,6 +39,6 @@ Specify whether to include personally identifiable information in the billable usage logs, for example the email addresses of cluster creators. Handle this information with care. Defaults to false. - + :returns: :class:`DownloadResponse` \ No newline at end of file diff --git a/docs/account/billing/budget_policy.rst b/docs/account/billing/budget_policy.rst index 6f7d7ede1..e58364d07 100644 --- a/docs/account/billing/budget_policy.rst +++ b/docs/account/billing/budget_policy.rst @@ -6,54 +6,53 @@ A service serves REST API about Budget policies - .. py:method:: create( [, custom_tags: Optional[List[compute.CustomPolicyTag]], policy_name: Optional[str], request_id: Optional[str]]) -> BudgetPolicy + .. py:method:: create( [, policy: Optional[BudgetPolicy], request_id: Optional[str]]) -> BudgetPolicy Create a budget policy. - + Creates a new policy. - - :param custom_tags: List[:class:`CustomPolicyTag`] (optional) - A list of tags defined by the customer. At most 40 entries are allowed per policy. - :param policy_name: str (optional) - The name of the policy. - Must be unique among active policies. - Can contain only characters of - 0-9, a-z, A-Z, -, =, ., :, /, @, _, +, whitespace. + + :param policy: :class:`BudgetPolicy` (optional) + The policy to create. `policy_id` needs to be empty as it will be generated `policy_name` must be + provided, custom_tags may need to be provided depending on the cloud provider. All other fields are + optional. :param request_id: str (optional) A unique identifier for this request. Restricted to 36 ASCII characters. A random UUID is recommended. This request is only idempotent if a `request_id` is provided. - + :returns: :class:`BudgetPolicy` .. py:method:: delete(policy_id: str) Delete a budget policy. - + Deletes a policy - + :param policy_id: str The Id of the policy. - - + + .. py:method:: get(policy_id: str) -> BudgetPolicy Get a budget policy. - + Retrieves a policy by it's ID. - + :param policy_id: str The Id of the policy. - + :returns: :class:`BudgetPolicy` .. py:method:: list( [, filter_by: Optional[Filter], page_size: Optional[int], page_token: Optional[str], sort_spec: Optional[SortSpec]]) -> Iterator[BudgetPolicy] List policies. - + Lists all policies. Policies are returned in the alphabetically ascending order of their names. - + :param filter_by: :class:`Filter` (optional) A filter to apply to the list of policies. :param page_size: int (optional) @@ -62,27 +61,27 @@ :param page_token: str (optional) A page token, received from a previous `ListServerlessPolicies` call. Provide this to retrieve the subsequent page. If unspecified, the first page will be returned. - + When paginating, all other parameters provided to `ListServerlessPoliciesRequest` must match the call that provided the page token. :param sort_spec: :class:`SortSpec` (optional) The sort specification. - + :returns: Iterator over :class:`BudgetPolicy` .. py:method:: update(policy_id: str [, limit_config: Optional[LimitConfig], policy: Optional[BudgetPolicy]]) -> BudgetPolicy Update a budget policy. - + Updates a policy - + :param policy_id: str The Id of the policy. This field is generated by Databricks and globally unique. :param limit_config: :class:`LimitConfig` (optional) DEPRECATED. This is redundant field as LimitConfig is part of the BudgetPolicy :param policy: :class:`BudgetPolicy` (optional) Contains the BudgetPolicy details. - + :returns: :class:`BudgetPolicy` \ No newline at end of file diff --git a/docs/account/billing/budgets.rst b/docs/account/billing/budgets.rst index 43c77d00b..cf87d1424 100644 --- a/docs/account/billing/budgets.rst +++ b/docs/account/billing/budgets.rst @@ -22,52 +22,62 @@ a = AccountClient() - created = a.budgets.create(budget=billing.CreateBudgetConfigurationBudget( - display_name=f'sdk-{time.time_ns()}', - filter=billing.BudgetConfigurationFilter(tags=[ - billing.BudgetConfigurationFilterTagClause(key="tagName", - value=billing.BudgetConfigurationFilterClause( - operator=billing.BudgetConfigurationFilterOperator.IN, - values=["all"])) - ]), - alert_configurations=[ - billing.CreateBudgetConfigurationBudgetAlertConfigurations( - time_period=billing.AlertConfigurationTimePeriod.MONTH, - quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, - trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, - quantity_threshold="100", - action_configurations=[ - billing.CreateBudgetConfigurationBudgetActionConfigurations( - action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, - target="admin@example.com") - ]) - ])) + created = a.budgets.create( + budget=billing.CreateBudgetConfigurationBudget( + display_name=f"sdk-{time.time_ns()}", + filter=billing.BudgetConfigurationFilter( + tags=[ + billing.BudgetConfigurationFilterTagClause( + key="tagName", + value=billing.BudgetConfigurationFilterClause( + operator=billing.BudgetConfigurationFilterOperator.IN, + values=["all"], + ), + ) + ] + ), + alert_configurations=[ + billing.CreateBudgetConfigurationBudgetAlertConfigurations( + time_period=billing.AlertConfigurationTimePeriod.MONTH, + quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, + trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, + quantity_threshold="100", + action_configurations=[ + billing.CreateBudgetConfigurationBudgetActionConfigurations( + action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, + target="admin@example.com", + ) + ], + ) + ], + ) + ) # cleanup a.budgets.delete(budget_id=created.budget.budget_configuration_id) Create new budget. - + Create a new budget configuration for an account. For full details, see https://docs.databricks.com/en/admin/account-settings/budgets.html. - + :param budget: :class:`CreateBudgetConfigurationBudget` Properties of the new budget configuration. - + :returns: :class:`CreateBudgetConfigurationResponse` .. py:method:: delete(budget_id: str) Delete budget. - + Deletes a budget configuration for an account. Both account and budget configuration are specified by ID. This cannot be undone. - + :param budget_id: str The Databricks budget configuration ID. - - + + .. py:method:: get(budget_id: str) -> GetBudgetConfigurationResponse @@ -84,26 +94,36 @@ a = AccountClient() - created = a.budgets.create(budget=billing.CreateBudgetConfigurationBudget( - display_name=f'sdk-{time.time_ns()}', - filter=billing.BudgetConfigurationFilter(tags=[ - billing.BudgetConfigurationFilterTagClause(key="tagName", - value=billing.BudgetConfigurationFilterClause( - operator=billing.BudgetConfigurationFilterOperator.IN, - values=["all"])) - ]), - alert_configurations=[ - billing.CreateBudgetConfigurationBudgetAlertConfigurations( - time_period=billing.AlertConfigurationTimePeriod.MONTH, - quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, - trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, - quantity_threshold="100", - action_configurations=[ - billing.CreateBudgetConfigurationBudgetActionConfigurations( - action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, - target="admin@example.com") - ]) - ])) + created = a.budgets.create( + budget=billing.CreateBudgetConfigurationBudget( + display_name=f"sdk-{time.time_ns()}", + filter=billing.BudgetConfigurationFilter( + tags=[ + billing.BudgetConfigurationFilterTagClause( + key="tagName", + value=billing.BudgetConfigurationFilterClause( + operator=billing.BudgetConfigurationFilterOperator.IN, + values=["all"], + ), + ) + ] + ), + alert_configurations=[ + billing.CreateBudgetConfigurationBudgetAlertConfigurations( + time_period=billing.AlertConfigurationTimePeriod.MONTH, + quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, + trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, + quantity_threshold="100", + action_configurations=[ + billing.CreateBudgetConfigurationBudgetActionConfigurations( + action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, + target="admin@example.com", + ) + ], + ) + ], + ) + ) by_id = a.budgets.get(budget_id=created.budget.budget_configuration_id) @@ -111,12 +131,12 @@ a.budgets.delete(budget_id=created.budget.budget_configuration_id) Get budget. - + Gets a budget configuration for an account. Both account and budget configuration are specified by ID. - + :param budget_id: str The budget configuration ID - + :returns: :class:`GetBudgetConfigurationResponse` @@ -135,13 +155,13 @@ all = a.budgets.list(billing.ListBudgetConfigurationsRequest()) Get all budgets. - + Gets all budgets associated with this account. - + :param page_token: str (optional) A page token received from a previous get all budget configurations call. This token can be used to retrieve the subsequent page. Requests first page if absent. - + :returns: Iterator over :class:`BudgetConfiguration` @@ -159,38 +179,53 @@ a = AccountClient() - created = a.budgets.create(budget=billing.CreateBudgetConfigurationBudget( - display_name=f'sdk-{time.time_ns()}', - filter=billing.BudgetConfigurationFilter(tags=[ - billing.BudgetConfigurationFilterTagClause(key="tagName", - value=billing.BudgetConfigurationFilterClause( - operator=billing.BudgetConfigurationFilterOperator.IN, - values=["all"])) - ]), - alert_configurations=[ - billing.CreateBudgetConfigurationBudgetAlertConfigurations( - time_period=billing.AlertConfigurationTimePeriod.MONTH, - quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, - trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, - quantity_threshold="100", - action_configurations=[ - billing.CreateBudgetConfigurationBudgetActionConfigurations( - action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, - target="admin@example.com") - ]) - ])) + created = a.budgets.create( + budget=billing.CreateBudgetConfigurationBudget( + display_name=f"sdk-{time.time_ns()}", + filter=billing.BudgetConfigurationFilter( + tags=[ + billing.BudgetConfigurationFilterTagClause( + key="tagName", + value=billing.BudgetConfigurationFilterClause( + operator=billing.BudgetConfigurationFilterOperator.IN, + values=["all"], + ), + ) + ] + ), + alert_configurations=[ + billing.CreateBudgetConfigurationBudgetAlertConfigurations( + time_period=billing.AlertConfigurationTimePeriod.MONTH, + quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, + trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, + quantity_threshold="100", + action_configurations=[ + billing.CreateBudgetConfigurationBudgetActionConfigurations( + action_type=billing.ActionConfigurationType.EMAIL_NOTIFICATION, + target="admin@example.com", + ) + ], + ) + ], + ) + ) _ = a.budgets.update( budget_id=created.budget.budget_configuration_id, budget=billing.UpdateBudgetConfigurationBudget( budget_configuration_id=created.budget.budget_configuration_id, - display_name=f'sdk-{time.time_ns()}', - filter=billing.BudgetConfigurationFilter(tags=[ - billing.BudgetConfigurationFilterTagClause( - key="tagName", - value=billing.BudgetConfigurationFilterClause( - operator=billing.BudgetConfigurationFilterOperator.IN, values=["all"])) - ]), + display_name=f"sdk-{time.time_ns()}", + filter=billing.BudgetConfigurationFilter( + tags=[ + billing.BudgetConfigurationFilterTagClause( + key="tagName", + value=billing.BudgetConfigurationFilterClause( + operator=billing.BudgetConfigurationFilterOperator.IN, + values=["all"], + ), + ) + ] + ), alert_configurations=[ billing.AlertConfiguration( alert_configuration_id=created.budget.alert_configurations[0].alert_configuration_id, @@ -198,21 +233,24 @@ quantity_type=billing.AlertConfigurationQuantityType.LIST_PRICE_DOLLARS_USD, trigger_type=billing.AlertConfigurationTriggerType.CUMULATIVE_SPENDING_EXCEEDED, quantity_threshold="50", - action_configurations=created.budget.alert_configurations[0].action_configurations) - ])) + action_configurations=created.budget.alert_configurations[0].action_configurations, + ) + ], + ), + ) # cleanup a.budgets.delete(budget_id=created.budget.budget_configuration_id) Modify budget. - + Updates a budget configuration for an account. Both account and budget configuration are specified by ID. - + :param budget_id: str The Databricks budget configuration ID. :param budget: :class:`UpdateBudgetConfigurationBudget` The updated budget. This will overwrite the budget specified by the budget ID. - + :returns: :class:`UpdateBudgetConfigurationResponse` \ No newline at end of file diff --git a/docs/account/billing/log_delivery.rst b/docs/account/billing/log_delivery.rst index 04ef4e349..ec5e0a945 100644 --- a/docs/account/billing/log_delivery.rst +++ b/docs/account/billing/log_delivery.rst @@ -7,12 +7,12 @@ These APIs manage log delivery configurations for this account. The two supported log types for this API are _billable usage logs_ and _audit logs_. This feature is in Public Preview. This feature works with all account ID types. - + Log delivery works with all account types. However, if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account, you can optionally configure different storage destinations for each workspace. Log delivery status is also provided to know the latest status of log delivery attempts. The high-level flow of billable usage delivery: - + 1. **Create storage**: In AWS, [create a new AWS S3 bucket] with a specific bucket policy. Using Databricks APIs, call the Account API to create a [storage configuration object](:method:Storage/Create) that uses the bucket name. 2. **Create credentials**: In AWS, create the appropriate AWS IAM role. For @@ -26,7 +26,7 @@ Account level log delivery applies to all current and future workspaces plus account level logs, while workspace level log delivery solely delivers logs related to the specified workspaces. You can create multiple types of delivery configurations per account. - + For billable usage delivery: * For more information about billable usage logs, see [Billable usage log delivery]. For the CSV schema, see the [Usage page]. * The delivery location is `//billable-usage/csv/`, where `` is the name of the optional delivery path @@ -35,7 +35,7 @@ workspaces (_workspace level_ logs). You can aggregate usage for your entire account by creating an _account level_ delivery configuration that delivers logs for all current and future workspaces in your account. * The files are delivered daily by overwriting the month's CSV file for each workspace. - + For audit log delivery: * For more information about about audit log delivery, see [Audit log delivery], which includes information about the used JSON schema. * The delivery location is `//workspaceId=/date=/auditlogs_.json`. @@ -45,7 +45,7 @@ level_ delivery configuration), the audit log delivery includes workspace-level audit logs for all workspaces in the account as well as account-level audit logs. See [Audit log delivery] for details. * Auditable events are typically available in logs within 15 minutes. - + [Audit log delivery]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html [Billable usage log delivery]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html [Usage page]: https://docs.databricks.com/administration-guide/account-settings/usage.html @@ -66,52 +66,61 @@ a = AccountClient() - bucket = a.storage.create(storage_configuration_name=f'sdk-{time.time_ns()}', - root_bucket_info=provisioning.RootBucketInfo(bucket_name=f'sdk-{time.time_ns()}')) + bucket = a.storage.create( + storage_configuration_name=f"sdk-{time.time_ns()}", + root_bucket_info=provisioning.RootBucketInfo(bucket_name=f"sdk-{time.time_ns()}"), + ) creds = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_LOGDELIVERY_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_LOGDELIVERY_ARN"]) + ), + ) - created = a.log_delivery.create(log_delivery_configuration=billing.CreateLogDeliveryConfigurationParams( - config_name=f'sdk-{time.time_ns()}', - credentials_id=creds.credentials_id, - storage_configuration_id=bucket.storage_configuration_id, - log_type=billing.LogType.AUDIT_LOGS, - output_format=billing.OutputFormat.JSON)) + created = a.log_delivery.create( + log_delivery_configuration=billing.CreateLogDeliveryConfigurationParams( + config_name=f"sdk-{time.time_ns()}", + credentials_id=creds.credentials_id, + storage_configuration_id=bucket.storage_configuration_id, + log_type=billing.LogType.AUDIT_LOGS, + output_format=billing.OutputFormat.JSON, + ) + ) # cleanup a.storage.delete(storage_configuration_id=bucket.storage_configuration_id) a.credentials.delete(credentials_id=creds.credentials_id) - a.log_delivery.patch_status(log_delivery_configuration_id=created.log_delivery_configuration.config_id, - status=billing.LogDeliveryConfigStatus.DISABLED) + a.log_delivery.patch_status( + log_delivery_configuration_id=created.log_delivery_configuration.config_id, + status=billing.LogDeliveryConfigStatus.DISABLED, + ) Create a new log delivery configuration. - + Creates a new Databricks log delivery configuration to enable delivery of the specified type of logs to your storage location. This requires that you already created a [credential object](:method:Credentials/Create) (which encapsulates a cross-account service IAM role) and a [storage configuration object](:method:Storage/Create) (which encapsulates an S3 bucket). - + For full details, including the required IAM role policies and bucket policies, see [Deliver and access billable usage logs] or [Configure audit logging]. - + **Note**: There is a limit on the number of log delivery configurations available per account (each limit applies separately to each log type including billable usage and audit logs). You can create a maximum of two enabled account-level delivery configurations (configurations without a workspace filter) per type. Additionally, you can create two enabled workspace-level delivery configurations per workspace for each log type, which means that the same workspace ID can occur in the workspace filter for no more than two delivery configurations per log type. - + You cannot delete a log delivery configuration, but you can disable it (see [Enable or disable log delivery configuration](:method:LogDelivery/PatchStatus)). - + [Configure audit logging]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html [Deliver and access billable usage logs]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html - + :param log_delivery_configuration: :class:`CreateLogDeliveryConfigurationParams` (optional) - + :returns: :class:`WrappedLogDeliveryConfiguration` @@ -130,36 +139,45 @@ a = AccountClient() - bucket = a.storage.create(storage_configuration_name=f'sdk-{time.time_ns()}', - root_bucket_info=provisioning.RootBucketInfo(bucket_name=f'sdk-{time.time_ns()}')) + bucket = a.storage.create( + storage_configuration_name=f"sdk-{time.time_ns()}", + root_bucket_info=provisioning.RootBucketInfo(bucket_name=f"sdk-{time.time_ns()}"), + ) creds = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_LOGDELIVERY_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_LOGDELIVERY_ARN"]) + ), + ) - created = a.log_delivery.create(log_delivery_configuration=billing.CreateLogDeliveryConfigurationParams( - config_name=f'sdk-{time.time_ns()}', - credentials_id=creds.credentials_id, - storage_configuration_id=bucket.storage_configuration_id, - log_type=billing.LogType.AUDIT_LOGS, - output_format=billing.OutputFormat.JSON)) + created = a.log_delivery.create( + log_delivery_configuration=billing.CreateLogDeliveryConfigurationParams( + config_name=f"sdk-{time.time_ns()}", + credentials_id=creds.credentials_id, + storage_configuration_id=bucket.storage_configuration_id, + log_type=billing.LogType.AUDIT_LOGS, + output_format=billing.OutputFormat.JSON, + ) + ) by_id = a.log_delivery.get(log_delivery_configuration_id=created.log_delivery_configuration.config_id) # cleanup a.storage.delete(storage_configuration_id=bucket.storage_configuration_id) a.credentials.delete(credentials_id=creds.credentials_id) - a.log_delivery.patch_status(log_delivery_configuration_id=created.log_delivery_configuration.config_id, - status=billing.LogDeliveryConfigStatus.DISABLED) + a.log_delivery.patch_status( + log_delivery_configuration_id=created.log_delivery_configuration.config_id, + status=billing.LogDeliveryConfigStatus.DISABLED, + ) Get log delivery configuration. - + Gets a Databricks log delivery configuration object for an account, both specified by ID. - + :param log_delivery_configuration_id: str Databricks log delivery configuration ID - + :returns: :class:`WrappedLogDeliveryConfiguration` @@ -178,28 +196,28 @@ all = a.log_delivery.list(billing.ListLogDeliveryRequest()) Get all log delivery configurations. - + Gets all Databricks log delivery configurations associated with an account specified by ID. - + :param credentials_id: str (optional) Filter by credential configuration ID. :param status: :class:`LogDeliveryConfigStatus` (optional) Filter by status `ENABLED` or `DISABLED`. :param storage_configuration_id: str (optional) Filter by storage configuration ID. - + :returns: Iterator over :class:`LogDeliveryConfiguration` .. py:method:: patch_status(log_delivery_configuration_id: str, status: LogDeliveryConfigStatus) Enable or disable log delivery configuration. - + Enables or disables a log delivery configuration. Deletion of delivery configurations is not supported, so disable log delivery configurations that are no longer needed. Note that you can't re-enable a delivery configuration if this would violate the delivery configuration limits described under [Create log delivery](:method:LogDelivery/Create). - + :param log_delivery_configuration_id: str Databricks log delivery configuration ID :param status: :class:`LogDeliveryConfigStatus` @@ -207,6 +225,6 @@ to `ENABLED`. You can [enable or disable the configuration](#operation/patch-log-delivery-config-status) later. Deletion of a configuration is not supported, so disable a log delivery configuration that is no longer needed. - - + + \ No newline at end of file diff --git a/docs/account/billing/usage_dashboards.rst b/docs/account/billing/usage_dashboards.rst index 350ef1f08..a316bf232 100644 --- a/docs/account/billing/usage_dashboards.rst +++ b/docs/account/billing/usage_dashboards.rst @@ -11,29 +11,29 @@ .. py:method:: create( [, dashboard_type: Optional[UsageDashboardType], workspace_id: Optional[int]]) -> CreateBillingUsageDashboardResponse Create new usage dashboard. - + Create a usage dashboard specified by workspaceId, accountId, and dashboard type. - + :param dashboard_type: :class:`UsageDashboardType` (optional) Workspace level usage dashboard shows usage data for the specified workspace ID. Global level usage dashboard shows usage data for all workspaces in the account. :param workspace_id: int (optional) The workspace ID of the workspace in which the usage dashboard is created. - + :returns: :class:`CreateBillingUsageDashboardResponse` .. py:method:: get( [, dashboard_type: Optional[UsageDashboardType], workspace_id: Optional[int]]) -> GetBillingUsageDashboardResponse Get usage dashboard. - + Get a usage dashboard specified by workspaceId, accountId, and dashboard type. - + :param dashboard_type: :class:`UsageDashboardType` (optional) Workspace level usage dashboard shows usage data for the specified workspace ID. Global level usage dashboard shows usage data for all workspaces in the account. :param workspace_id: int (optional) The workspace ID of the workspace in which the usage dashboard is created. - + :returns: :class:`GetBillingUsageDashboardResponse` \ No newline at end of file diff --git a/docs/account/catalog/metastore_assignments.rst b/docs/account/catalog/metastore_assignments.rst index f5b00c6b3..1bfeedca0 100644 --- a/docs/account/catalog/metastore_assignments.rst +++ b/docs/account/catalog/metastore_assignments.rst @@ -9,43 +9,43 @@ .. py:method:: create(workspace_id: int, metastore_id: str [, metastore_assignment: Optional[CreateMetastoreAssignment]]) Assigns a workspace to a metastore. - + Creates an assignment to a metastore for a workspace - + :param workspace_id: int Workspace ID. :param metastore_id: str Unity Catalog metastore ID :param metastore_assignment: :class:`CreateMetastoreAssignment` (optional) - - + + .. py:method:: delete(workspace_id: int, metastore_id: str) Delete a metastore assignment. - + Deletes a metastore assignment to a workspace, leaving the workspace with no metastore. - + :param workspace_id: int Workspace ID. :param metastore_id: str Unity Catalog metastore ID - - + + .. py:method:: get(workspace_id: int) -> AccountsMetastoreAssignment Gets the metastore assignment for a workspace. - + Gets the metastore assignment, if any, for the workspace specified by ID. If the workspace is assigned a metastore, the mappig will be returned. If no metastore is assigned to the workspace, the assignment will not be found and a 404 returned. - + :param workspace_id: int Workspace ID. - + :returns: :class:`AccountsMetastoreAssignment` @@ -65,27 +65,27 @@ ws = a.metastore_assignments.list(metastore_id=os.environ["TEST_METASTORE_ID"]) Get all workspaces assigned to a metastore. - + Gets a list of all Databricks workspace IDs that have been assigned to given metastore. - + :param metastore_id: str Unity Catalog metastore ID - + :returns: Iterator over int .. py:method:: update(workspace_id: int, metastore_id: str [, metastore_assignment: Optional[UpdateMetastoreAssignment]]) Updates a metastore assignment to a workspaces. - + Updates an assignment to a metastore for a workspace. Currently, only the default catalog may be updated. - + :param workspace_id: int Workspace ID. :param metastore_id: str Unity Catalog metastore ID :param metastore_assignment: :class:`UpdateMetastoreAssignment` (optional) - - + + \ No newline at end of file diff --git a/docs/account/catalog/metastores.rst b/docs/account/catalog/metastores.rst index 15f39060d..36df616ea 100644 --- a/docs/account/catalog/metastores.rst +++ b/docs/account/catalog/metastores.rst @@ -10,58 +10,58 @@ .. py:method:: create( [, metastore_info: Optional[CreateMetastore]]) -> AccountsMetastoreInfo Create metastore. - + Creates a Unity Catalog metastore. - + :param metastore_info: :class:`CreateMetastore` (optional) - + :returns: :class:`AccountsMetastoreInfo` .. py:method:: delete(metastore_id: str [, force: Optional[bool]]) Delete a metastore. - + Deletes a Unity Catalog metastore for an account, both specified by ID. - + :param metastore_id: str Unity Catalog metastore ID :param force: bool (optional) Force deletion even if the metastore is not empty. Default is false. - - + + .. py:method:: get(metastore_id: str) -> AccountsMetastoreInfo Get a metastore. - + Gets a Unity Catalog metastore from an account, both specified by ID. - + :param metastore_id: str Unity Catalog metastore ID - + :returns: :class:`AccountsMetastoreInfo` .. py:method:: list() -> Iterator[MetastoreInfo] Get all metastores associated with an account. - + Gets all Unity Catalog metastores associated with an account specified by ID. - + :returns: Iterator over :class:`MetastoreInfo` .. py:method:: update(metastore_id: str [, metastore_info: Optional[UpdateMetastore]]) -> AccountsMetastoreInfo Update a metastore. - + Updates an existing Unity Catalog metastore. - + :param metastore_id: str Unity Catalog metastore ID :param metastore_info: :class:`UpdateMetastore` (optional) - + :returns: :class:`AccountsMetastoreInfo` \ No newline at end of file diff --git a/docs/account/catalog/storage_credentials.rst b/docs/account/catalog/storage_credentials.rst index 453b3a1eb..0b9948015 100644 --- a/docs/account/catalog/storage_credentials.rst +++ b/docs/account/catalog/storage_credentials.rst @@ -9,78 +9,78 @@ .. py:method:: create(metastore_id: str [, credential_info: Optional[CreateStorageCredential]]) -> AccountsStorageCredentialInfo Create a storage credential. - + Creates a new storage credential. The request object is specific to the cloud: - + * **AwsIamRole** for AWS credentials * **AzureServicePrincipal** for Azure credentials * **GcpServiceAcountKey** for GCP credentials. - + The caller must be a metastore admin and have the **CREATE_STORAGE_CREDENTIAL** privilege on the metastore. - + :param metastore_id: str Unity Catalog metastore ID :param credential_info: :class:`CreateStorageCredential` (optional) - + :returns: :class:`AccountsStorageCredentialInfo` .. py:method:: delete(metastore_id: str, storage_credential_name: str [, force: Optional[bool]]) Delete a storage credential. - + Deletes a storage credential from the metastore. The caller must be an owner of the storage credential. - + :param metastore_id: str Unity Catalog metastore ID :param storage_credential_name: str Name of the storage credential. :param force: bool (optional) Force deletion even if the Storage Credential is not empty. Default is false. - - + + .. py:method:: get(metastore_id: str, storage_credential_name: str) -> AccountsStorageCredentialInfo Gets the named storage credential. - + Gets a storage credential from the metastore. The caller must be a metastore admin, the owner of the storage credential, or have a level of privilege on the storage credential. - + :param metastore_id: str Unity Catalog metastore ID :param storage_credential_name: str Name of the storage credential. - + :returns: :class:`AccountsStorageCredentialInfo` .. py:method:: list(metastore_id: str) -> Iterator[StorageCredentialInfo] Get all storage credentials assigned to a metastore. - + Gets a list of all storage credentials that have been assigned to given metastore. - + :param metastore_id: str Unity Catalog metastore ID - + :returns: Iterator over :class:`StorageCredentialInfo` .. py:method:: update(metastore_id: str, storage_credential_name: str [, credential_info: Optional[UpdateStorageCredential]]) -> AccountsStorageCredentialInfo Updates a storage credential. - + Updates a storage credential on the metastore. The caller must be the owner of the storage credential. If the caller is a metastore admin, only the __owner__ credential can be changed. - + :param metastore_id: str Unity Catalog metastore ID :param storage_credential_name: str Name of the storage credential. :param credential_info: :class:`UpdateStorageCredential` (optional) - + :returns: :class:`AccountsStorageCredentialInfo` \ No newline at end of file diff --git a/docs/account/iam/access_control.rst b/docs/account/iam/access_control.rst index 2537e262c..4bf03b75e 100644 --- a/docs/account/iam/access_control.rst +++ b/docs/account/iam/access_control.rst @@ -11,23 +11,23 @@ .. py:method:: get_assignable_roles_for_resource(resource: str) -> GetAssignableRolesForResourceResponse Get assignable roles for a resource. - + Gets all the roles that can be granted on an account level resource. A role is grantable if the rule set on the resource can contain an access rule of the role. - + :param resource: str The resource name for which assignable roles will be listed. - + :returns: :class:`GetAssignableRolesForResourceResponse` .. py:method:: get_rule_set(name: str, etag: str) -> RuleSetResponse Get a rule set. - + Get a rule set by its name. A rule set is always attached to a resource and contains a list of access rules on the said resource. Currently only a default rule set for each resource is supported. - + :param name: str The ruleset name associated with the request. :param etag: str @@ -37,20 +37,20 @@ modify -> write pattern to perform rule set updates in order to avoid race conditions that is get an etag from a GET rule set request, and pass it with the PUT update request to identify the rule set version you are updating. - + :returns: :class:`RuleSetResponse` .. py:method:: update_rule_set(name: str, rule_set: RuleSetUpdateRequest) -> RuleSetResponse Update a rule set. - + Replace the rules of a rule set. First, use get to read the current version of the rule set before modifying it. This pattern helps prevent conflicts between concurrent updates. - + :param name: str Name of the rule set. :param rule_set: :class:`RuleSetUpdateRequest` - + :returns: :class:`RuleSetResponse` \ No newline at end of file diff --git a/docs/account/iam/groups.rst b/docs/account/iam/groups.rst index a9a4afeac..adb23f7d7 100644 --- a/docs/account/iam/groups.rst +++ b/docs/account/iam/groups.rst @@ -6,7 +6,7 @@ Groups simplify identity management, making it easier to assign access to Databricks account, data, and other securable objects. - + It is best practice to assign access to workspaces and access-control policies in Unity Catalog to groups, instead of to users individually. All Databricks account identities can be assigned as members of groups, and members inherit permissions that are assigned to their group. @@ -14,15 +14,15 @@ .. py:method:: create( [, display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], members: Optional[List[ComplexValue]], meta: Optional[ResourceMeta], roles: Optional[List[ComplexValue]], schemas: Optional[List[GroupSchema]]]) -> Group Create a new group. - + Creates a group in the Databricks account with a unique name, using the supplied group details. - + :param display_name: str (optional) String that represents a human-readable group name :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the group. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -35,40 +35,40 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`GroupSchema`] (optional) The schema of the group. - + :returns: :class:`Group` .. py:method:: delete(id: str) Delete a group. - + Deletes a group from the Databricks account. - + :param id: str Unique ID for a group in the Databricks account. - - + + .. py:method:: get(id: str) -> Group Get group details. - + Gets the information for a specific group in the Databricks account. - + :param id: str Unique ID for a group in the Databricks account. - + :returns: :class:`Group` .. py:method:: list( [, attributes: Optional[str], count: Optional[int], excluded_attributes: Optional[str], filter: Optional[str], sort_by: Optional[str], sort_order: Optional[ListSortOrder], start_index: Optional[int]]) -> Iterator[Group] List group details. - + Gets all details of the groups associated with the Databricks account. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -80,7 +80,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. @@ -88,31 +88,31 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`Group` .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]]) Update group details. - + Partially updates the details of a group. - + :param id: str Unique ID for a group in the Databricks account. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: update(id: str [, display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], members: Optional[List[ComplexValue]], meta: Optional[ResourceMeta], roles: Optional[List[ComplexValue]], schemas: Optional[List[GroupSchema]]]) Replace a group. - + Updates the details of a group by replacing the entire group entity. - + :param id: str Databricks group ID :param display_name: str (optional) @@ -120,7 +120,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the group. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -131,6 +131,6 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`GroupSchema`] (optional) The schema of the group. - - + + \ No newline at end of file diff --git a/docs/account/iam/service_principals.rst b/docs/account/iam/service_principals.rst index 0631386a1..2823c8d31 100644 --- a/docs/account/iam/service_principals.rst +++ b/docs/account/iam/service_principals.rst @@ -23,15 +23,15 @@ a = AccountClient() - sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}') + sp_create = a.service_principals.create(active=True, display_name=f"sdk-{time.time_ns()}") # cleanup a.service_principals.delete(id=sp_create.id) Create a service principal. - + Creates a new service principal in the Databricks account. - + :param active: bool (optional) If this user is active :param application_id: str (optional) @@ -41,7 +41,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the service principal. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -51,20 +51,20 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`ServicePrincipalSchema`] (optional) The schema of the List response. - + :returns: :class:`ServicePrincipal` .. py:method:: delete(id: str) Delete a service principal. - + Delete a single service principal in the Databricks account. - + :param id: str Unique ID for a service principal in the Databricks account. - - + + .. py:method:: get(id: str) -> ServicePrincipal @@ -80,7 +80,7 @@ a = AccountClient() - sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}') + sp_create = a.service_principals.create(active=True, display_name=f"sdk-{time.time_ns()}") sp = a.service_principals.get(id=sp_create.id) @@ -88,12 +88,12 @@ a.service_principals.delete(id=sp_create.id) Get service principal details. - + Gets the details for a single service principal define in the Databricks account. - + :param id: str Unique ID for a service principal in the Databricks account. - + :returns: :class:`ServicePrincipal` @@ -110,7 +110,7 @@ a = AccountClient() - sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}') + sp_create = a.service_principals.create(active=True, display_name=f"sdk-{time.time_ns()}") sp = a.service_principals.get(id=sp_create.id) @@ -120,9 +120,9 @@ a.service_principals.delete(id=sp_create.id) List service principals. - + Gets the set of service principals associated with a Databricks account. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -134,7 +134,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. @@ -142,7 +142,7 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`ServicePrincipal` @@ -160,28 +160,30 @@ a = AccountClient() - sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}') + sp_create = a.service_principals.create(active=True, display_name=f"sdk-{time.time_ns()}") sp = a.service_principals.get(id=sp_create.id) - a.service_principals.patch(id=sp.id, - operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], - schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP]) + a.service_principals.patch( + id=sp.id, + operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], + schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], + ) # cleanup a.service_principals.delete(id=sp_create.id) Update service principal details. - + Partially updates the details of a single service principal in the Databricks account. - + :param id: str Unique ID for a service principal in the Databricks account. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: update(id: str [, active: Optional[bool], application_id: Optional[str], display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], roles: Optional[List[ComplexValue]], schemas: Optional[List[ServicePrincipalSchema]]]) @@ -197,7 +199,7 @@ a = AccountClient() - sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}') + sp_create = a.service_principals.create(active=True, display_name=f"sdk-{time.time_ns()}") sp = a.service_principals.get(id=sp_create.id) @@ -207,11 +209,11 @@ a.service_principals.delete(id=sp_create.id) Replace service principal. - + Updates the details of a single service principal. - + This action replaces the existing service principal with the same name. - + :param id: str Databricks service principal ID. :param active: bool (optional) @@ -223,7 +225,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the service principal. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -231,6 +233,6 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`ServicePrincipalSchema`] (optional) The schema of the List response. - - + + \ No newline at end of file diff --git a/docs/account/iam/users.rst b/docs/account/iam/users.rst index 4b8b5bb08..54a9f1af8 100644 --- a/docs/account/iam/users.rst +++ b/docs/account/iam/users.rst @@ -5,7 +5,7 @@ .. py:class:: AccountUsersAPI User identities recognized by Databricks and represented by email addresses. - + Databricks recommends using SCIM provisioning to sync users and groups automatically from your identity provider to your Databricks account. SCIM streamlines onboarding a new employee or team by using your identity provider to create users and groups in Databricks account and give them the proper level of @@ -27,29 +27,32 @@ a = AccountClient() - user = a.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = a.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) # cleanup a.users.delete(id=user.id) Create a new user. - + Creates a new user in the Databricks account. This new user will also be added to the Databricks account. - + :param active: bool (optional) If this user is active :param display_name: str (optional) String that represents a concatenation of given and family names. For example `John Smith`. This field cannot be updated through the Workspace SCIM APIs when [identity federation is enabled]. Use Account SCIM APIs to update `displayName`. - + [identity federation is enabled]: https://docs.databricks.com/administration-guide/users-groups/best-practices.html#enable-identity-federation :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the user. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. @@ -64,7 +67,7 @@ The schema of the user. :param user_name: str (optional) Email address of the Databricks user. - + :returns: :class:`User` @@ -81,19 +84,22 @@ a = AccountClient() - user = a.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = a.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) a.users.delete(id=user.id) Delete a user. - + Deletes a user. Deleting a user from a Databricks account also removes objects associated with the user. - + :param id: str Unique ID for a user in the Databricks account. - - + + .. py:method:: get(id: str [, attributes: Optional[str], count: Optional[int], excluded_attributes: Optional[str], filter: Optional[str], sort_by: Optional[str], sort_order: Optional[GetSortOrder], start_index: Optional[int]]) -> User @@ -109,7 +115,10 @@ a = AccountClient() - user = a.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = a.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) by_id = a.users.get(id=user.id) @@ -117,9 +126,9 @@ a.users.delete(id=user.id) Get user details. - + Gets information for a specific user in Databricks account. - + :param id: str Unique ID for a user in the Databricks account. :param attributes: str (optional) @@ -133,7 +142,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. Multi-part paths are supported. For example, `userName`, @@ -142,16 +151,16 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: :class:`User` .. py:method:: list( [, attributes: Optional[str], count: Optional[int], excluded_attributes: Optional[str], filter: Optional[str], sort_by: Optional[str], sort_order: Optional[ListSortOrder], start_index: Optional[int]]) -> Iterator[User] List users. - + Gets details for all the users associated with a Databricks account. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -163,7 +172,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. Multi-part paths are supported. For example, `userName`, @@ -172,7 +181,7 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`User` @@ -190,37 +199,44 @@ a = AccountClient() - user = a.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = a.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) - a.users.patch(id=user.id, - schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], - operations=[ - iam.Patch(op=iam.PatchOp.ADD, - value=iam.User(roles=[iam.ComplexValue(value="account_admin")])) - ]) + a.users.patch( + id=user.id, + schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], + operations=[ + iam.Patch( + op=iam.PatchOp.ADD, + value=iam.User(roles=[iam.ComplexValue(value="account_admin")]), + ) + ], + ) # cleanup a.users.delete(id=user.id) Update user details. - + Partially updates a user resource by applying the supplied operations on specific user attributes. - + :param id: str Unique ID for a user in the Databricks account. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: update(id: str [, active: Optional[bool], display_name: Optional[str], emails: Optional[List[ComplexValue]], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], name: Optional[Name], roles: Optional[List[ComplexValue]], schemas: Optional[List[UserSchema]], user_name: Optional[str]]) Replace a user. - + Replaces a user's information with the data supplied in request. - + :param id: str Databricks user ID. This is automatically set by Databricks. Any value provided by the client will be ignored. @@ -230,13 +246,13 @@ String that represents a concatenation of given and family names. For example `John Smith`. This field cannot be updated through the Workspace SCIM APIs when [identity federation is enabled]. Use Account SCIM APIs to update `displayName`. - + [identity federation is enabled]: https://docs.databricks.com/administration-guide/users-groups/best-practices.html#enable-identity-federation :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the user. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. @@ -248,6 +264,6 @@ The schema of the user. :param user_name: str (optional) Email address of the Databricks user. - - + + \ No newline at end of file diff --git a/docs/account/iam/workspace_assignment.rst b/docs/account/iam/workspace_assignment.rst index 697f0a5da..6f4c66be5 100644 --- a/docs/account/iam/workspace_assignment.rst +++ b/docs/account/iam/workspace_assignment.rst @@ -10,27 +10,27 @@ .. py:method:: delete(workspace_id: int, principal_id: int) Delete permissions assignment. - + Deletes the workspace permissions assignment in a given account and workspace for the specified principal. - + :param workspace_id: int The workspace ID for the account. :param principal_id: int The ID of the user, service principal, or group. - - + + .. py:method:: get(workspace_id: int) -> WorkspacePermissions List workspace permissions. - + Get an array of workspace permissions for the specified account and workspace. - + :param workspace_id: int The workspace ID. - + :returns: :class:`WorkspacePermissions` @@ -52,12 +52,12 @@ all = a.workspace_assignment.list(list=workspace_id) Get permission assignments. - + Get the permission assignments for the specified Databricks account and Databricks workspace. - + :param workspace_id: int The workspace ID for the account. - + :returns: Iterator over :class:`PermissionAssignment` @@ -76,21 +76,23 @@ a = AccountClient() - spn = a.service_principals.create(display_name=f'sdk-{time.time_ns()}') + spn = a.service_principals.create(display_name=f"sdk-{time.time_ns()}") spn_id = spn.id workspace_id = os.environ["DUMMY_WORKSPACE_ID"] - _ = a.workspace_assignment.update(workspace_id=workspace_id, - principal_id=spn_id, - permissions=[iam.WorkspacePermission.USER]) + _ = a.workspace_assignment.update( + workspace_id=workspace_id, + principal_id=spn_id, + permissions=[iam.WorkspacePermission.USER], + ) Create or update permissions assignment. - + Creates or updates the workspace permissions assignment in a given account and workspace for the specified principal. - + :param workspace_id: int The workspace ID. :param principal_id: int @@ -101,6 +103,6 @@ will be ignored. Note that excluding this field, or providing unsupported values, will have the same effect as providing an empty list, which will result in the deletion of all permissions for the principal. - + :returns: :class:`PermissionAssignment` \ No newline at end of file diff --git a/docs/account/oauth2/custom_app_integration.rst b/docs/account/oauth2/custom_app_integration.rst index 7043a343b..5110e70ad 100644 --- a/docs/account/oauth2/custom_app_integration.rst +++ b/docs/account/oauth2/custom_app_integration.rst @@ -10,11 +10,11 @@ .. py:method:: create( [, confidential: Optional[bool], name: Optional[str], redirect_urls: Optional[List[str]], scopes: Optional[List[str]], token_access_policy: Optional[TokenAccessPolicy], user_authorized_scopes: Optional[List[str]]]) -> CreateCustomAppIntegrationOutput Create Custom OAuth App Integration. - + Create Custom OAuth App Integration. - + You can retrieve the custom OAuth app integration via :method:CustomAppIntegration/get. - + :param confidential: bool (optional) This field indicates whether an OAuth client secret is required to authenticate this client. :param name: str (optional) @@ -29,54 +29,54 @@ :param user_authorized_scopes: List[str] (optional) Scopes that will need to be consented by end user to mint the access token. If the user does not authorize the access token will not be minted. Must be a subset of scopes. - + :returns: :class:`CreateCustomAppIntegrationOutput` .. py:method:: delete(integration_id: str) Delete Custom OAuth App Integration. - + Delete an existing Custom OAuth App Integration. You can retrieve the custom OAuth app integration via :method:CustomAppIntegration/get. - + :param integration_id: str - - + + .. py:method:: get(integration_id: str) -> GetCustomAppIntegrationOutput Get OAuth Custom App Integration. - + Gets the Custom OAuth App Integration for the given integration id. - + :param integration_id: str The OAuth app integration ID. - + :returns: :class:`GetCustomAppIntegrationOutput` .. py:method:: list( [, include_creator_username: Optional[bool], page_size: Optional[int], page_token: Optional[str]]) -> Iterator[GetCustomAppIntegrationOutput] Get custom oauth app integrations. - + Get the list of custom OAuth app integrations for the specified Databricks account - + :param include_creator_username: bool (optional) :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`GetCustomAppIntegrationOutput` .. py:method:: update(integration_id: str [, redirect_urls: Optional[List[str]], scopes: Optional[List[str]], token_access_policy: Optional[TokenAccessPolicy], user_authorized_scopes: Optional[List[str]]]) Updates Custom OAuth App Integration. - + Updates an existing custom OAuth App Integration. You can retrieve the custom OAuth app integration via :method:CustomAppIntegration/get. - + :param integration_id: str :param redirect_urls: List[str] (optional) List of OAuth redirect urls to be updated in the custom OAuth app integration @@ -88,6 +88,6 @@ :param user_authorized_scopes: List[str] (optional) Scopes that will need to be consented by end user to mint the access token. If the user does not authorize the access token will not be minted. Must be a subset of scopes. - - + + \ No newline at end of file diff --git a/docs/account/oauth2/federation_policy.rst b/docs/account/oauth2/federation_policy.rst index c95bf563c..4f9db531d 100644 --- a/docs/account/oauth2/federation_policy.rst +++ b/docs/account/oauth2/federation_policy.rst @@ -5,20 +5,20 @@ .. py:class:: AccountFederationPolicyAPI These APIs manage account federation policies. - + Account federation policies allow users and service principals in your Databricks account to securely access Databricks APIs using tokens from your trusted identity providers (IdPs). - + With token federation, your users and service principals can exchange tokens from your IdP for Databricks OAuth tokens, which can be used to access Databricks APIs. Token federation eliminates the need to manage Databricks secrets, and allows you to centralize management of token issuance policies in your IdP. Databricks token federation is typically used in combination with [SCIM], so users in your IdP are synchronized into your Databricks account. - + Token federation is configured in your Databricks account using an account federation policy. An account federation policy specifies: * which IdP, or issuer, your Databricks account should accept tokens from * how to determine which Databricks user, or subject, a token is issued for - + To configure a federation policy, you provide the following: * The required token __issuer__, as specified in the “iss” claim of your tokens. The issuer is an https URL that identifies your IdP. * The allowed token __audiences__, as specified in the “aud” claim of your tokens. This identifier is intended to @@ -29,68 +29,68 @@ public keys used to validate the signature of your tokens, in JWKS format. If unspecified (recommended), Databricks automatically fetches the public keys from your issuer’s well known endpoint. Databricks strongly recommends relying on your issuer’s well known endpoint for discovering public keys. - + An example federation policy is: ``` issuer: "https://idp.mycompany.com/oidc" audiences: ["databricks"] subject_claim: "sub" ``` - + An example JWT token body that matches this policy and could be used to authenticate to Databricks as user `username@mycompany.com` is: ``` { "iss": "https://idp.mycompany.com/oidc", "aud": "databricks", "sub": "username@mycompany.com" } ``` - + You may also need to configure your IdP to generate tokens for your users to exchange with Databricks, if your users do not already have the ability to generate tokens that are compatible with your federation policy. - + You do not need to configure an OAuth application in Databricks to use token federation. - + [SCIM]: https://docs.databricks.com/admin/users-groups/scim/index.html .. py:method:: create( [, policy: Optional[FederationPolicy], policy_id: Optional[str]]) -> FederationPolicy Create account federation policy. - + :param policy: :class:`FederationPolicy` (optional) :param policy_id: str (optional) The identifier for the federation policy. The identifier must contain only lowercase alphanumeric characters, numbers, hyphens, and slashes. If unspecified, the id will be assigned by Databricks. - + :returns: :class:`FederationPolicy` .. py:method:: delete(policy_id: str) Delete account federation policy. - + :param policy_id: str The identifier for the federation policy. - - + + .. py:method:: get(policy_id: str) -> FederationPolicy Get account federation policy. - + :param policy_id: str The identifier for the federation policy. - + :returns: :class:`FederationPolicy` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[FederationPolicy] List account federation policies. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`FederationPolicy` .. py:method:: update(policy_id: str [, policy: Optional[FederationPolicy], update_mask: Optional[str]]) -> FederationPolicy Update account federation policy. - + :param policy_id: str The identifier for the federation policy. :param policy: :class:`FederationPolicy` (optional) @@ -100,6 +100,6 @@ should be updated (full replacement). If unspecified, all fields that are set in the policy provided in the update request will overwrite the corresponding fields in the existing policy. Example value: 'description,oidc_policy.audiences'. - + :returns: :class:`FederationPolicy` \ No newline at end of file diff --git a/docs/account/oauth2/o_auth_published_apps.rst b/docs/account/oauth2/o_auth_published_apps.rst index 18c07c326..873d8a650 100644 --- a/docs/account/oauth2/o_auth_published_apps.rst +++ b/docs/account/oauth2/o_auth_published_apps.rst @@ -11,13 +11,13 @@ .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[PublishedAppOutput] Get all the published OAuth apps. - + Get all the available published OAuth apps in Databricks. - + :param page_size: int (optional) The max number of OAuth published apps to return in one page. :param page_token: str (optional) A token that can be used to get the next page of results. - + :returns: Iterator over :class:`PublishedAppOutput` \ No newline at end of file diff --git a/docs/account/oauth2/published_app_integration.rst b/docs/account/oauth2/published_app_integration.rst index f59f2c4aa..fd61c58fa 100644 --- a/docs/account/oauth2/published_app_integration.rst +++ b/docs/account/oauth2/published_app_integration.rst @@ -10,64 +10,64 @@ .. py:method:: create( [, app_id: Optional[str], token_access_policy: Optional[TokenAccessPolicy]]) -> CreatePublishedAppIntegrationOutput Create Published OAuth App Integration. - + Create Published OAuth App Integration. - + You can retrieve the published OAuth app integration via :method:PublishedAppIntegration/get. - + :param app_id: str (optional) App id of the OAuth published app integration. For example power-bi, tableau-deskop :param token_access_policy: :class:`TokenAccessPolicy` (optional) Token access policy - + :returns: :class:`CreatePublishedAppIntegrationOutput` .. py:method:: delete(integration_id: str) Delete Published OAuth App Integration. - + Delete an existing Published OAuth App Integration. You can retrieve the published OAuth app integration via :method:PublishedAppIntegration/get. - + :param integration_id: str - - + + .. py:method:: get(integration_id: str) -> GetPublishedAppIntegrationOutput Get OAuth Published App Integration. - + Gets the Published OAuth App Integration for the given integration id. - + :param integration_id: str - + :returns: :class:`GetPublishedAppIntegrationOutput` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[GetPublishedAppIntegrationOutput] Get published oauth app integrations. - + Get the list of published OAuth app integrations for the specified Databricks account - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`GetPublishedAppIntegrationOutput` .. py:method:: update(integration_id: str [, token_access_policy: Optional[TokenAccessPolicy]]) Updates Published OAuth App Integration. - + Updates an existing published OAuth App Integration. You can retrieve the published OAuth app integration via :method:PublishedAppIntegration/get. - + :param integration_id: str :param token_access_policy: :class:`TokenAccessPolicy` (optional) Token access policy to be updated in the published OAuth app integration - - + + \ No newline at end of file diff --git a/docs/account/oauth2/service_principal_federation_policy.rst b/docs/account/oauth2/service_principal_federation_policy.rst index 2e0577ba4..be823b7a6 100644 --- a/docs/account/oauth2/service_principal_federation_policy.rst +++ b/docs/account/oauth2/service_principal_federation_policy.rst @@ -5,22 +5,22 @@ .. py:class:: ServicePrincipalFederationPolicyAPI These APIs manage service principal federation policies. - + Service principal federation, also known as Workload Identity Federation, allows your automated workloads running outside of Databricks to securely access Databricks APIs without the need for Databricks secrets. With Workload Identity Federation, your application (or workload) authenticates to Databricks as a Databricks service principal, using tokens provided by the workload runtime. - + Databricks strongly recommends using Workload Identity Federation to authenticate to Databricks from automated workloads, over alternatives such as OAuth client secrets or Personal Access Tokens, whenever possible. Workload Identity Federation is supported by many popular services, including Github Actions, Azure DevOps, GitLab, Terraform Cloud, and Kubernetes clusters, among others. - + Workload identity federation is configured in your Databricks account using a service principal federation policy. A service principal federation policy specifies: * which IdP, or issuer, the service principal is allowed to authenticate from * which workload identity, or subject, is allowed to authenticate as the Databricks service principal - + To configure a federation policy, you provide the following: * The required token __issuer__, as specified in the “iss” claim of workload identity tokens. The issuer is an https URL that identifies the workload identity provider. * The required token __subject__, as specified in the “sub” claim of @@ -32,73 +32,73 @@ of the workload identity tokens, in JWKS format. If unspecified (recommended), Databricks automatically fetches the public keys from the issuer’s well known endpoint. Databricks strongly recommends relying on the issuer’s well known endpoint for discovering public keys. - + An example service principal federation policy, for a Github Actions workload, is: ``` issuer: "https://token.actions.githubusercontent.com" audiences: ["https://github.com/my-github-org"] subject: "repo:my-github-org/my-repo:environment:prod" ``` - + An example JWT token body that matches this policy and could be used to authenticate to Databricks is: ``` { "iss": "https://token.actions.githubusercontent.com", "aud": "https://github.com/my-github-org", "sub": "repo:my-github-org/my-repo:environment:prod" } ``` - + You may also need to configure the workload runtime to generate tokens for your workloads. - + You do not need to configure an OAuth application in Databricks to use token federation. .. py:method:: create(service_principal_id: int [, policy: Optional[FederationPolicy], policy_id: Optional[str]]) -> FederationPolicy Create service principal federation policy. - + :param service_principal_id: int The service principal id for the federation policy. :param policy: :class:`FederationPolicy` (optional) :param policy_id: str (optional) The identifier for the federation policy. The identifier must contain only lowercase alphanumeric characters, numbers, hyphens, and slashes. If unspecified, the id will be assigned by Databricks. - + :returns: :class:`FederationPolicy` .. py:method:: delete(service_principal_id: int, policy_id: str) Delete service principal federation policy. - + :param service_principal_id: int The service principal id for the federation policy. :param policy_id: str The identifier for the federation policy. - - + + .. py:method:: get(service_principal_id: int, policy_id: str) -> FederationPolicy Get service principal federation policy. - + :param service_principal_id: int The service principal id for the federation policy. :param policy_id: str The identifier for the federation policy. - + :returns: :class:`FederationPolicy` .. py:method:: list(service_principal_id: int [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[FederationPolicy] List service principal federation policies. - + :param service_principal_id: int The service principal id for the federation policy. :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`FederationPolicy` .. py:method:: update(service_principal_id: int, policy_id: str [, policy: Optional[FederationPolicy], update_mask: Optional[str]]) -> FederationPolicy Update service principal federation policy. - + :param service_principal_id: int The service principal id for the federation policy. :param policy_id: str @@ -110,6 +110,6 @@ should be updated (full replacement). If unspecified, all fields that are set in the policy provided in the update request will overwrite the corresponding fields in the existing policy. Example value: 'description,oidc_policy.audiences'. - + :returns: :class:`FederationPolicy` \ No newline at end of file diff --git a/docs/account/oauth2/service_principal_secrets.rst b/docs/account/oauth2/service_principal_secrets.rst index 955d6da53..01965a19a 100644 --- a/docs/account/oauth2/service_principal_secrets.rst +++ b/docs/account/oauth2/service_principal_secrets.rst @@ -5,50 +5,54 @@ .. py:class:: ServicePrincipalSecretsAPI These APIs enable administrators to manage service principal secrets. - + You can use the generated secrets to obtain OAuth access tokens for a service principal, which can then be used to access Databricks Accounts and Workspace APIs. For more information, see [Authentication using OAuth tokens for service principals], - + In addition, the generated secrets can be used to configure the Databricks Terraform Provider to authenticate with the service principal. For more information, see [Databricks Terraform Provider]. - + [Authentication using OAuth tokens for service principals]: https://docs.databricks.com/dev-tools/authentication-oauth.html [Databricks Terraform Provider]: https://github.com/databricks/terraform-provider-databricks/blob/master/docs/index.md#authenticating-with-service-principal + - .. py:method:: create(service_principal_id: int) -> CreateServicePrincipalSecretResponse + .. py:method:: create(service_principal_id: int [, lifetime: Optional[str]]) -> CreateServicePrincipalSecretResponse Create service principal secret. - + Create a secret for the given service principal. - + :param service_principal_id: int The service principal ID. - + :param lifetime: str (optional) + The lifetime of the secret in seconds. If this parameter is not provided, the secret will have a + default lifetime of 730 days (63072000s). + :returns: :class:`CreateServicePrincipalSecretResponse` .. py:method:: delete(service_principal_id: int, secret_id: str) Delete service principal secret. - + Delete a secret from the given service principal. - + :param service_principal_id: int The service principal ID. :param secret_id: str The secret ID. - - + + .. py:method:: list(service_principal_id: int [, page_token: Optional[str]]) -> Iterator[SecretInfo] List service principal secrets. - + List all secrets associated with the given service principal. This operation only returns information about the secrets themselves and does not include the secret values. - + :param service_principal_id: int The service principal ID. :param page_token: str (optional) @@ -58,6 +62,6 @@ previous request. To list all of the secrets for a service principal, it is necessary to continue requesting pages of entries until the response contains no `next_page_token`. Note that the number of entries returned must not be used to determine when the listing is complete. - + :returns: Iterator over :class:`SecretInfo` \ No newline at end of file diff --git a/docs/account/provisioning/credentials.rst b/docs/account/provisioning/credentials.rst index 5255a6a29..d023d4f1f 100644 --- a/docs/account/provisioning/credentials.rst +++ b/docs/account/provisioning/credentials.rst @@ -25,46 +25,48 @@ a = AccountClient() role = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]) + ), + ) # cleanup a.credentials.delete(credentials_id=role.credentials_id) Create credential configuration. - + Creates a Databricks credential configuration that represents cloud cross-account credentials for a specified account. Databricks uses this to set up network infrastructure properly to host Databricks clusters. For your AWS IAM role, you need to trust the External ID (the Databricks Account API account ID) in the returned credential object, and configure the required access policy. - + Save the response's `credentials_id` field, which is the ID for your new credential configuration object. - + For information about how to create a new workspace with this API, see [Create a new workspace using the Account API] - + [Create a new workspace using the Account API]: http://docs.databricks.com/administration-guide/account-api/new-workspace.html - + :param credentials_name: str The human-readable name of the credential configuration object. :param aws_credentials: :class:`CreateCredentialAwsCredentials` - + :returns: :class:`Credential` .. py:method:: delete(credentials_id: str) Delete credential configuration. - + Deletes a Databricks credential configuration object for an account, both specified by ID. You cannot delete a credential that is associated with any workspace. - + :param credentials_id: str Databricks Account API credential configuration ID - - + + .. py:method:: get(credentials_id: str) -> Credential @@ -83,9 +85,11 @@ a = AccountClient() role = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]) + ), + ) by_id = a.credentials.get(credentials_id=role.credentials_id) @@ -93,12 +97,12 @@ a.credentials.delete(credentials_id=role.credentials_id) Get credential configuration. - + Gets a Databricks credential configuration object for an account, both specified by ID. - + :param credentials_id: str Databricks Account API credential configuration ID - + :returns: :class:`Credential` @@ -116,8 +120,8 @@ configs = a.credentials.list() Get all credential configurations. - + Gets all Databricks credential configurations associated with an account specified by ID. - + :returns: Iterator over :class:`Credential` \ No newline at end of file diff --git a/docs/account/provisioning/encryption_keys.rst b/docs/account/provisioning/encryption_keys.rst index c711727c5..1c00a2914 100644 --- a/docs/account/provisioning/encryption_keys.rst +++ b/docs/account/provisioning/encryption_keys.rst @@ -7,11 +7,11 @@ These APIs manage encryption key configurations for this workspace (optional). A key configuration encapsulates the AWS KMS key information and some information about how the key configuration can be used. There are two possible uses for key configurations: - + * Managed services: A key configuration can be used to encrypt a workspace's notebook and secret data in the control plane, as well as Databricks SQL queries and query history. * Storage: A key configuration can be used to encrypt a workspace's DBFS and EBS data in the data plane. - + In both of these cases, the key configuration's ID is used when creating a new workspace. This Preview feature is available if your account is on the E2 version of the platform. Updating a running workspace with workspace storage encryption requires that the workspace is on the E2 version of the platform. If you @@ -32,15 +32,19 @@ a = AccountClient() - created = a.encryption_keys.create(aws_key_info=provisioning.CreateAwsKeyInfo( - key_arn=os.environ["TEST_MANAGED_KMS_KEY_ARN"], key_alias=os.environ["TEST_STORAGE_KMS_KEY_ALIAS"]), - use_cases=[provisioning.KeyUseCase.MANAGED_SERVICES]) + created = a.encryption_keys.create( + aws_key_info=provisioning.CreateAwsKeyInfo( + key_arn=os.environ["TEST_MANAGED_KMS_KEY_ARN"], + key_alias=os.environ["TEST_STORAGE_KMS_KEY_ALIAS"], + ), + use_cases=[provisioning.KeyUseCase.MANAGED_SERVICES], + ) # cleanup a.encryption_keys.delete(customer_managed_key_id=created.customer_managed_key_id) Create encryption key configuration. - + Creates a customer-managed key configuration object for an account, specified by ID. This operation uploads a reference to a customer-managed key to Databricks. If the key is assigned as a workspace's customer-managed key for managed services, Databricks uses the key to encrypt the workspaces notebooks @@ -48,32 +52,32 @@ specified as a workspace's customer-managed key for workspace storage, the key encrypts the workspace's root S3 bucket (which contains the workspace's root DBFS and system data) and, optionally, cluster EBS volume data. - + **Important**: Customer-managed keys are supported only for some deployment types, subscription types, and AWS regions that currently support creation of Databricks workspaces. - + This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. - + :param use_cases: List[:class:`KeyUseCase`] The cases that the key can be used for. :param aws_key_info: :class:`CreateAwsKeyInfo` (optional) :param gcp_key_info: :class:`CreateGcpKeyInfo` (optional) - + :returns: :class:`CustomerManagedKey` .. py:method:: delete(customer_managed_key_id: str) Delete encryption key configuration. - + Deletes a customer-managed key configuration object for an account. You cannot delete a configuration that is associated with a running workspace. - + :param customer_managed_key_id: str Databricks encryption key configuration ID. - - + + .. py:method:: get(customer_managed_key_id: str) -> CustomerManagedKey @@ -90,9 +94,13 @@ a = AccountClient() - created = a.encryption_keys.create(aws_key_info=provisioning.CreateAwsKeyInfo( - key_arn=os.environ["TEST_MANAGED_KMS_KEY_ARN"], key_alias=os.environ["TEST_STORAGE_KMS_KEY_ALIAS"]), - use_cases=[provisioning.KeyUseCase.MANAGED_SERVICES]) + created = a.encryption_keys.create( + aws_key_info=provisioning.CreateAwsKeyInfo( + key_arn=os.environ["TEST_MANAGED_KMS_KEY_ARN"], + key_alias=os.environ["TEST_STORAGE_KMS_KEY_ALIAS"], + ), + use_cases=[provisioning.KeyUseCase.MANAGED_SERVICES], + ) by_id = a.encryption_keys.get(customer_managed_key_id=created.customer_managed_key_id) @@ -100,7 +108,7 @@ a.encryption_keys.delete(customer_managed_key_id=created.customer_managed_key_id) Get encryption key configuration. - + Gets a customer-managed key configuration object for an account, specified by ID. This operation uploads a reference to a customer-managed key to Databricks. If assigned as a workspace's customer-managed key for managed services, Databricks uses the key to encrypt the workspaces notebooks @@ -108,15 +116,15 @@ specified as a workspace's customer-managed key for storage, the key encrypts the workspace's root S3 bucket (which contains the workspace's root DBFS and system data) and, optionally, cluster EBS volume data. - + **Important**: Customer-managed keys are supported only for some deployment types, subscription types, and AWS regions. - + This operation is available only if your account is on the E2 version of the platform.", - + :param customer_managed_key_id: str Databricks encryption key configuration ID. - + :returns: :class:`CustomerManagedKey` @@ -134,17 +142,17 @@ all = a.encryption_keys.list() Get all encryption key configurations. - + Gets all customer-managed key configuration objects for an account. If the key is specified as a workspace's managed services customer-managed key, Databricks uses the key to encrypt the workspace's notebooks and secrets in the control plane, in addition to Databricks SQL queries and query history. If the key is specified as a workspace's storage customer-managed key, the key is used to encrypt the workspace's root S3 bucket and optionally can encrypt cluster EBS volumes data in the data plane. - + **Important**: Customer-managed keys are supported only for some deployment types, subscription types, and AWS regions. - + This operation is available only if your account is on the E2 version of the platform. - + :returns: Iterator over :class:`CustomerManagedKey` \ No newline at end of file diff --git a/docs/account/provisioning/networks.rst b/docs/account/provisioning/networks.rst index e7491f202..46bccd872 100644 --- a/docs/account/provisioning/networks.rst +++ b/docs/account/provisioning/networks.rst @@ -20,17 +20,18 @@ a = AccountClient() - netw = a.networks.create(network_name=f'sdk-{time.time_ns()}', - vpc_id=hex(time.time_ns())[2:], - subnet_ids=[hex(time.time_ns())[2:], - hex(time.time_ns())[2:]], - security_group_ids=[hex(time.time_ns())[2:]]) + netw = a.networks.create( + network_name=f"sdk-{time.time_ns()}", + vpc_id=hex(time.time_ns())[2:], + subnet_ids=[hex(time.time_ns())[2:], hex(time.time_ns())[2:]], + security_group_ids=[hex(time.time_ns())[2:]], + ) Create network configuration. - + Creates a Databricks network configuration that represents an VPC and its resources. The VPC will be used for new Databricks clusters. This requires a pre-existing VPC and subnets. - + :param network_name: str The human-readable name of the network configuration. :param gcp_network_info: :class:`GcpNetworkInfo` (optional) @@ -45,28 +46,28 @@ :param vpc_endpoints: :class:`NetworkVpcEndpoints` (optional) If specified, contains the VPC endpoints used to allow cluster communication from this VPC over [AWS PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink/ :param vpc_id: str (optional) The ID of the VPC associated with this network. VPC IDs can be used in multiple network configurations. - + :returns: :class:`Network` .. py:method:: delete(network_id: str) Delete a network configuration. - + Deletes a Databricks network configuration, which represents a cloud VPC and its resources. You cannot delete a network that is associated with a workspace. - + This operation is available only if your account is on the E2 version of the platform. - + :param network_id: str Databricks Account API network configuration ID. - - + + .. py:method:: get(network_id: str) -> Network @@ -82,21 +83,22 @@ a = AccountClient() - netw = a.networks.create(network_name=f'sdk-{time.time_ns()}', - vpc_id=hex(time.time_ns())[2:], - subnet_ids=[hex(time.time_ns())[2:], - hex(time.time_ns())[2:]], - security_group_ids=[hex(time.time_ns())[2:]]) + netw = a.networks.create( + network_name=f"sdk-{time.time_ns()}", + vpc_id=hex(time.time_ns())[2:], + subnet_ids=[hex(time.time_ns())[2:], hex(time.time_ns())[2:]], + security_group_ids=[hex(time.time_ns())[2:]], + ) by_id = a.networks.get(network_id=netw.network_id) Get a network configuration. - + Gets a Databricks network configuration, which represents a cloud VPC and its resources. - + :param network_id: str Databricks Account API network configuration ID. - + :returns: :class:`Network` @@ -114,10 +116,10 @@ configs = a.networks.list() Get all network configurations. - + Gets a list of all Databricks network configurations for an account, specified by ID. - + This operation is available only if your account is on the E2 version of the platform. - + :returns: Iterator over :class:`Network` \ No newline at end of file diff --git a/docs/account/provisioning/private_access.rst b/docs/account/provisioning/private_access.rst index 10022068e..e30ed2585 100644 --- a/docs/account/provisioning/private_access.rst +++ b/docs/account/provisioning/private_access.rst @@ -20,27 +20,29 @@ a = AccountClient() - created = a.private_access.create(private_access_settings_name=f'sdk-{time.time_ns()}', - region=os.environ["AWS_REGION"]) + created = a.private_access.create( + private_access_settings_name=f"sdk-{time.time_ns()}", + region=os.environ["AWS_REGION"], + ) # cleanup a.private_access.delete(private_access_settings_id=created.private_access_settings_id) Create private access settings. - + Creates a private access settings object, which specifies how your workspace is accessed over [AWS PrivateLink]. To use AWS PrivateLink, a workspace must have a private access settings object referenced by ID in the workspace's `private_access_settings_id` property. - + You can share one private access settings with multiple workspaces in a single account. However, private access settings are specific to AWS regions, so only workspaces in the same AWS region can use a given private access settings object. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :param private_access_settings_name: str The human-readable name of the private access settings object. :param region: str @@ -49,14 +51,14 @@ An array of Databricks VPC endpoint IDs. This is the Databricks ID that is returned when registering the VPC endpoint configuration in your Databricks account. This is not the ID of the VPC endpoint in AWS. - + Only used when `private_access_level` is set to `ENDPOINT`. This is an allow list of VPC endpoints that in your account that can connect to your workspace over AWS PrivateLink. - + If hybrid access to your workspace is enabled by setting `public_access_enabled` to `true`, this control only works for PrivateLink connections. To control how your workspace is accessed via public internet, see [IP access lists]. - + [IP access lists]: https://docs.databricks.com/security/network/ip-access-list.html :param private_access_level: :class:`PrivateAccessLevel` (optional) The private access level controls which VPC endpoints can connect to the UI or API of any workspace @@ -68,26 +70,26 @@ Determines if the workspace can be accessed over public internet. For fully private workspaces, you can optionally specify `false`, but only if you implement both the front-end and the back-end PrivateLink connections. Otherwise, specify `true`, which means that public access is enabled. - + :returns: :class:`PrivateAccessSettings` .. py:method:: delete(private_access_settings_id: str) Delete a private access settings object. - + Deletes a private access settings object, which determines how your workspace is accessed over [AWS PrivateLink]. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink].", - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :param private_access_settings_id: str Databricks Account API private access settings ID. - - + + .. py:method:: get(private_access_settings_id: str) -> PrivateAccessSettings @@ -104,8 +106,10 @@ a = AccountClient() - created = a.private_access.create(private_access_settings_name=f'sdk-{time.time_ns()}', - region=os.environ["AWS_REGION"]) + created = a.private_access.create( + private_access_settings_name=f"sdk-{time.time_ns()}", + region=os.environ["AWS_REGION"], + ) by_id = a.private_access.get(private_access_settings_id=created.private_access_settings_id) @@ -113,18 +117,18 @@ a.private_access.delete(private_access_settings_id=created.private_access_settings_id) Get a private access settings object. - + Gets a private access settings object, which specifies how your workspace is accessed over [AWS PrivateLink]. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink].", - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :param private_access_settings_id: str Databricks Account API private access settings ID. - + :returns: :class:`PrivateAccessSettings` @@ -142,9 +146,9 @@ all = a.private_access.list() Get all private access settings objects. - + Gets a list of all private access settings objects for an account, specified by ID. - + :returns: Iterator over :class:`PrivateAccessSettings` @@ -162,36 +166,40 @@ a = AccountClient() - created = a.private_access.create(private_access_settings_name=f'sdk-{time.time_ns()}', - region=os.environ["AWS_REGION"]) + created = a.private_access.create( + private_access_settings_name=f"sdk-{time.time_ns()}", + region=os.environ["AWS_REGION"], + ) - a.private_access.replace(private_access_settings_id=created.private_access_settings_id, - private_access_settings_name=f'sdk-{time.time_ns()}', - region=os.environ["AWS_REGION"]) + a.private_access.replace( + private_access_settings_id=created.private_access_settings_id, + private_access_settings_name=f"sdk-{time.time_ns()}", + region=os.environ["AWS_REGION"], + ) # cleanup a.private_access.delete(private_access_settings_id=created.private_access_settings_id) Replace private access settings. - + Updates an existing private access settings object, which specifies how your workspace is accessed over [AWS PrivateLink]. To use AWS PrivateLink, a workspace must have a private access settings object referenced by ID in the workspace's `private_access_settings_id` property. - + This operation completely overwrites your existing private access settings object attached to your workspaces. All workspaces attached to the private access settings are affected by any change. If `public_access_enabled`, `private_access_level`, or `allowed_vpc_endpoint_ids` are updated, effects of these changes might take several minutes to propagate to the workspace API. - + You can share one private access settings object with multiple workspaces in a single account. However, private access settings are specific to AWS regions, so only workspaces in the same AWS region can use a given private access settings object. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :param private_access_settings_id: str Databricks Account API private access settings ID. :param private_access_settings_name: str @@ -202,14 +210,14 @@ An array of Databricks VPC endpoint IDs. This is the Databricks ID that is returned when registering the VPC endpoint configuration in your Databricks account. This is not the ID of the VPC endpoint in AWS. - + Only used when `private_access_level` is set to `ENDPOINT`. This is an allow list of VPC endpoints that in your account that can connect to your workspace over AWS PrivateLink. - + If hybrid access to your workspace is enabled by setting `public_access_enabled` to `true`, this control only works for PrivateLink connections. To control how your workspace is accessed via public internet, see [IP access lists]. - + [IP access lists]: https://docs.databricks.com/security/network/ip-access-list.html :param private_access_level: :class:`PrivateAccessLevel` (optional) The private access level controls which VPC endpoints can connect to the UI or API of any workspace @@ -221,6 +229,6 @@ Determines if the workspace can be accessed over public internet. For fully private workspaces, you can optionally specify `false`, but only if you implement both the front-end and the back-end PrivateLink connections. Otherwise, specify `true`, which means that public access is enabled. - - + + \ No newline at end of file diff --git a/docs/account/provisioning/storage.rst b/docs/account/provisioning/storage.rst index 611a8cdc6..b8e144f8c 100644 --- a/docs/account/provisioning/storage.rst +++ b/docs/account/provisioning/storage.rst @@ -25,43 +25,44 @@ a = AccountClient() storage = a.storage.create( - storage_configuration_name=f'sdk-{time.time_ns()}', - root_bucket_info=provisioning.RootBucketInfo(bucket_name=os.environ["TEST_ROOT_BUCKET"])) + storage_configuration_name=f"sdk-{time.time_ns()}", + root_bucket_info=provisioning.RootBucketInfo(bucket_name=os.environ["TEST_ROOT_BUCKET"]), + ) # cleanup a.storage.delete(storage_configuration_id=storage.storage_configuration_id) Create new storage configuration. - + Creates new storage configuration for an account, specified by ID. Uploads a storage configuration object that represents the root AWS S3 bucket in your account. Databricks stores related workspace assets including DBFS, cluster logs, and job results. For the AWS S3 bucket, you need to configure the required bucket policy. - + For information about how to create a new workspace with this API, see [Create a new workspace using the Account API] - + [Create a new workspace using the Account API]: http://docs.databricks.com/administration-guide/account-api/new-workspace.html - + :param storage_configuration_name: str The human-readable name of the storage configuration. :param root_bucket_info: :class:`RootBucketInfo` Root S3 bucket information. - + :returns: :class:`StorageConfiguration` .. py:method:: delete(storage_configuration_id: str) Delete storage configuration. - + Deletes a Databricks storage configuration. You cannot delete a storage configuration that is associated with any workspace. - + :param storage_configuration_id: str Databricks Account API storage configuration ID. - - + + .. py:method:: get(storage_configuration_id: str) -> StorageConfiguration @@ -78,18 +79,20 @@ a = AccountClient() - storage = a.storage.create(storage_configuration_name=f'sdk-{time.time_ns()}', - root_bucket_info=provisioning.RootBucketInfo(bucket_name=f'sdk-{time.time_ns()}')) + storage = a.storage.create( + storage_configuration_name=f"sdk-{time.time_ns()}", + root_bucket_info=provisioning.RootBucketInfo(bucket_name=f"sdk-{time.time_ns()}"), + ) by_id = a.storage.get(storage_configuration_id=storage.storage_configuration_id) Get storage configuration. - + Gets a Databricks storage configuration for an account, both specified by ID. - + :param storage_configuration_id: str Databricks Account API storage configuration ID. - + :returns: :class:`StorageConfiguration` @@ -107,8 +110,8 @@ configs = a.storage.list() Get all storage configurations. - + Gets a list of all Databricks storage configurations for your account, specified by ID. - + :returns: Iterator over :class:`StorageConfiguration` \ No newline at end of file diff --git a/docs/account/provisioning/vpc_endpoints.rst b/docs/account/provisioning/vpc_endpoints.rst index d2622dc0f..fecfbec5d 100644 --- a/docs/account/provisioning/vpc_endpoints.rst +++ b/docs/account/provisioning/vpc_endpoints.rst @@ -20,28 +20,30 @@ a = AccountClient() - created = a.vpc_endpoints.create(aws_vpc_endpoint_id=os.environ["TEST_RELAY_VPC_ENDPOINT"], - region=os.environ["AWS_REGION"], - vpc_endpoint_name=f'sdk-{time.time_ns()}') + created = a.vpc_endpoints.create( + aws_vpc_endpoint_id=os.environ["TEST_RELAY_VPC_ENDPOINT"], + region=os.environ["AWS_REGION"], + vpc_endpoint_name=f"sdk-{time.time_ns()}", + ) # cleanup a.vpc_endpoints.delete(vpc_endpoint_id=created.vpc_endpoint_id) Create VPC endpoint configuration. - + Creates a VPC endpoint configuration, which represents a [VPC endpoint] object in AWS used to communicate privately with Databricks over [AWS PrivateLink]. - + After you create the VPC endpoint configuration, the Databricks [endpoint service] automatically accepts the VPC endpoint. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html [VPC endpoint]: https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints.html [endpoint service]: https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html - + :param vpc_endpoint_name: str The human-readable name of the storage configuration. :param aws_vpc_endpoint_id: str (optional) @@ -50,27 +52,27 @@ The Google Cloud specific information for this Private Service Connect endpoint. :param region: str (optional) The AWS region in which this VPC endpoint object exists. - + :returns: :class:`VpcEndpoint` .. py:method:: delete(vpc_endpoint_id: str) Delete VPC endpoint configuration. - + Deletes a VPC endpoint configuration, which represents an [AWS VPC endpoint] that can communicate privately with Databricks over [AWS PrivateLink]. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [AWS VPC endpoint]: https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :param vpc_endpoint_id: str Databricks VPC endpoint ID. - - + + .. py:method:: get(vpc_endpoint_id: str) -> VpcEndpoint @@ -87,9 +89,11 @@ a = AccountClient() - created = a.vpc_endpoints.create(aws_vpc_endpoint_id=os.environ["TEST_RELAY_VPC_ENDPOINT"], - region=os.environ["AWS_REGION"], - vpc_endpoint_name=f'sdk-{time.time_ns()}') + created = a.vpc_endpoints.create( + aws_vpc_endpoint_id=os.environ["TEST_RELAY_VPC_ENDPOINT"], + region=os.environ["AWS_REGION"], + vpc_endpoint_name=f"sdk-{time.time_ns()}", + ) by_id = a.vpc_endpoints.get(vpc_endpoint_id=created.vpc_endpoint_id) @@ -97,16 +101,16 @@ a.vpc_endpoints.delete(vpc_endpoint_id=created.vpc_endpoint_id) Get a VPC endpoint configuration. - + Gets a VPC endpoint configuration, which represents a [VPC endpoint] object in AWS used to communicate privately with Databricks over [AWS PrivateLink]. - + [AWS PrivateLink]: https://aws.amazon.com/privatelink [VPC endpoint]: https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html - + :param vpc_endpoint_id: str Databricks VPC endpoint ID. - + :returns: :class:`VpcEndpoint` @@ -124,12 +128,12 @@ all = a.vpc_endpoints.list() Get all VPC endpoint configurations. - + Gets a list of all VPC endpoints for an account, specified by ID. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink]. - + [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - + :returns: Iterator over :class:`VpcEndpoint` \ No newline at end of file diff --git a/docs/account/provisioning/workspaces.rst b/docs/account/provisioning/workspaces.rst index ad8a75942..26ec685e5 100644 --- a/docs/account/provisioning/workspaces.rst +++ b/docs/account/provisioning/workspaces.rst @@ -7,7 +7,7 @@ These APIs manage workspaces for this account. A Databricks workspace is an environment for accessing all of your Databricks assets. The workspace organizes objects (notebooks, libraries, and experiments) into folders, and provides access to data and computational resources such as clusters and jobs. - + These endpoints are available if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. @@ -27,18 +27,23 @@ a = AccountClient() storage = a.storage.create( - storage_configuration_name=f'sdk-{time.time_ns()}', - root_bucket_info=provisioning.RootBucketInfo(bucket_name=os.environ["TEST_ROOT_BUCKET"])) + storage_configuration_name=f"sdk-{time.time_ns()}", + root_bucket_info=provisioning.RootBucketInfo(bucket_name=os.environ["TEST_ROOT_BUCKET"]), + ) role = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]) + ), + ) - waiter = a.workspaces.create(workspace_name=f'sdk-{time.time_ns()}', - aws_region=os.environ["AWS_REGION"], - credentials_id=role.credentials_id, - storage_configuration_id=storage.storage_configuration_id) + waiter = a.workspaces.create( + workspace_name=f"sdk-{time.time_ns()}", + aws_region=os.environ["AWS_REGION"], + credentials_id=role.credentials_id, + storage_configuration_id=storage.storage_configuration_id, + ) # cleanup a.storage.delete(storage_configuration_id=storage.storage_configuration_id) @@ -46,16 +51,16 @@ a.workspaces.delete(workspace_id=waiter.workspace_id) Create a new workspace. - + Creates a new workspace. - + **Important**: This operation is asynchronous. A response with HTTP status code 200 means the request has been accepted and is in progress, but does not mean that the workspace deployed successfully and is running. The initial workspace status is typically `PROVISIONING`. Use the workspace ID (`workspace_id`) field in the response to identify the new workspace and make repeated `GET` requests with the workspace ID and check its status. The workspace becomes available when the status changes to `RUNNING`. - + :param workspace_name: str The workspace's human-readable name. :param aws_region: str (optional) @@ -77,22 +82,22 @@ deployment name is `abcsales`, your workspace URL will be `https://abcsales.cloud.databricks.com`. Hyphens are allowed. This property supports only the set of characters that are allowed in a subdomain. - + To set this value, you must have a deployment name prefix. Contact your Databricks account team to add an account deployment name prefix to your account. - + Workspace deployment names follow the account prefix and a hyphen. For example, if your account's deployment prefix is `acme` and the workspace deployment name is `workspace-1`, the JSON response for the `deployment_name` field becomes `acme-workspace-1`. The workspace URL would be `acme-workspace-1.cloud.databricks.com`. - + You can also set the `deployment_name` to the reserved keyword `EMPTY` if you want the deployment name to only include the deployment prefix. For example, if your account's deployment prefix is `acme` and the workspace deployment name is `EMPTY`, the `deployment_name` becomes `acme` only and the workspace URL is `acme.cloud.databricks.com`. - + This value must be unique across all non-deleted deployments across all AWS regions. - + If a new workspace omits this property, the server generates a unique deployment name for you with the pattern `dbc-xxxxxxxx-xxxx`. :param gcp_managed_network_config: :class:`GcpManagedNetworkConfig` (optional) @@ -100,19 +105,19 @@ is ignored if you specify a customer-managed VPC in the `network_id` field.", All the IP range configurations must be mutually exclusive. An attempt to create a workspace fails if Databricks detects an IP range overlap. - + Specify custom IP ranges in CIDR format. The IP ranges for these fields must not overlap, and all IP addresses must be entirely within the following ranges: `10.0.0.0/8`, `100.64.0.0/10`, `172.16.0.0/12`, `192.168.0.0/16`, and `240.0.0.0/4`. - + The sizes of these IP ranges affect the maximum number of nodes for the workspace. - + **Important**: Confirm the IP ranges used by your Databricks workspace before creating the workspace. You cannot change them after your workspace is deployed. If the IP address ranges for your Databricks are too small, IP exhaustion can occur, causing your Databricks jobs to fail. To determine the address range sizes that you need, Databricks provides a calculator as a Microsoft Excel spreadsheet. See [calculate subnet sizes for a new workspace]. - + [calculate subnet sizes for a new workspace]: https://docs.gcp.databricks.com/administration-guide/cloud-configurations/gcp/network-sizing.html :param gke_config: :class:`GkeConfig` (optional) The configurations for the GKE cluster of a Databricks workspace. @@ -127,15 +132,15 @@ :param network_id: str (optional) :param pricing_tier: :class:`PricingTier` (optional) The pricing tier of the workspace. For pricing tier information, see [AWS Pricing]. - + [AWS Pricing]: https://databricks.com/product/aws-pricing :param private_access_settings_id: str (optional) ID of the workspace's private access settings object. Only used for PrivateLink. This ID must be specified for customers using [AWS PrivateLink] for either front-end (user-to-workspace connection), back-end (data plane to control plane connection), or both connection types. - + Before configuring PrivateLink, read the [Databricks article about PrivateLink].", - + [AWS PrivateLink]: https://aws.amazon.com/privatelink/ [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html :param storage_configuration_id: str (optional) @@ -144,7 +149,7 @@ The ID of the workspace's storage encryption key configuration object. This is used to encrypt the workspace's root S3 bucket (root DBFS and system data) and, optionally, cluster EBS volumes. The provided key configuration object property `use_cases` must contain `STORAGE`. - + :returns: Long-running operation waiter for :class:`Workspace`. See :method:wait_get_workspace_running for more details. @@ -156,18 +161,18 @@ .. py:method:: delete(workspace_id: int) Delete a workspace. - + Terminates and deletes a Databricks workspace. From an API perspective, deletion is immediate. However, it might take a few minutes for all workspaces resources to be deleted, depending on the size and number of workspace resources. - + This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. - + :param workspace_id: int Workspace ID. - - + + .. py:method:: get(workspace_id: int) -> Workspace @@ -186,23 +191,23 @@ by_id = a.workspaces.get(workspace_id=created.workspace_id) Get a workspace. - + Gets information including status for a Databricks workspace, specified by ID. In the response, the `workspace_status` field indicates the current status. After initial workspace creation (which is asynchronous), make repeated `GET` requests with the workspace ID and check its status. The workspace becomes available when the status changes to `RUNNING`. - + For information about how to create a new workspace with this API **including error handling**, see [Create a new workspace using the Account API]. - + This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. - + [Create a new workspace using the Account API]: http://docs.databricks.com/administration-guide/account-api/new-workspace.html - + :param workspace_id: int Workspace ID. - + :returns: :class:`Workspace` @@ -220,12 +225,12 @@ all = a.workspaces.list() Get all workspaces. - + Gets a list of all workspaces associated with an account, specified by ID. - + This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. - + :returns: Iterator over :class:`Workspace` @@ -245,22 +250,27 @@ a = AccountClient() update_role = a.credentials.create( - credentials_name=f'sdk-{time.time_ns()}', - aws_credentials=provisioning.CreateCredentialAwsCredentials(sts_role=provisioning.CreateCredentialStsRole( - role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]))) + credentials_name=f"sdk-{time.time_ns()}", + aws_credentials=provisioning.CreateCredentialAwsCredentials( + sts_role=provisioning.CreateCredentialStsRole(role_arn=os.environ["TEST_CROSSACCOUNT_ARN"]) + ), + ) created = a.waiter.get() - _ = a.workspaces.update(workspace_id=created.workspace_id, credentials_id=update_role.credentials_id).result() + _ = a.workspaces.update( + workspace_id=created.workspace_id, + credentials_id=update_role.credentials_id, + ).result() # cleanup a.credentials.delete(credentials_id=update_role.credentials_id) Update workspace configuration. - + Updates a workspace configuration for either a running workspace or a failed workspace. The elements that can be updated varies between these two use cases. - + ### Update a failed workspace You can update a Databricks workspace configuration for failed workspace deployment for some fields, but not all fields. For a failed workspace, this request supports updates to the following fields only: - Credential configuration ID - Storage configuration ID - Network @@ -282,14 +292,14 @@ update the network connectivity configuration ID to ensure the workspace uses the same set of stable IP CIDR blocks to access your resources. You cannot remove a network connectivity configuration from the workspace once attached, you can only switch to another one. - + After calling the `PATCH` operation to update the workspace configuration, make repeated `GET` requests with the workspace ID and check the workspace status. The workspace is successful if the status changes to `RUNNING`. - + For information about how to create a new workspace with this API **including error handling**, see [Create a new workspace using the Account API]. - + ### Update a running workspace You can update a Databricks workspace configuration for running workspaces for some fields, but not all fields. For a running workspace, this request supports updating the following fields only: - Credential configuration ID - Network configuration ID. Used @@ -315,12 +325,12 @@ network connectivity configuration ID to ensure the workspace uses the same set of stable IP CIDR blocks to access your resources. You cannot remove a network connectivity configuration from the workspace once attached, you can only switch to another one. - + **Important**: To update a running workspace, your workspace must have no running compute resources that run in your workspace's VPC in the Classic data plane. For example, stop all all-purpose clusters, job clusters, pools with running clusters, and Classic SQL warehouses. If you do not terminate all cluster instances in the workspace before calling this API, the request will fail. - + ### Wait until changes take effect. After calling the `PATCH` operation to update the workspace configuration, make repeated `GET` requests with the workspace ID and check the workspace status and the status of the fields. * For workspaces with a Databricks-managed VPC, the workspace status becomes @@ -336,22 +346,22 @@ silently to its original configuration. After the workspace has been updated, you cannot use or create clusters for another 20 minutes. If you create or use clusters before this time interval elapses, clusters do not launch successfully, fail, or could cause other unexpected behavior. - + If you update the _storage_ customer-managed key configurations, it takes 20 minutes for the changes to fully take effect. During the 20 minute wait, it is important that you stop all REST API calls to the DBFS API. If you are modifying _only the managed services key configuration_, you can omit the 20 minute wait. - + **Important**: Customer-managed keys and customer-managed VPCs are supported by only some deployment types and subscription types. If you have questions about availability, contact your Databricks representative. - + This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account. - + [Account Console]: https://docs.databricks.com/administration-guide/account-settings-e2/account-console-e2.html [Create a new workspace using the Account API]: http://docs.databricks.com/administration-guide/account-api/new-workspace.html - + :param workspace_id: int Workspace ID. :param aws_region: str (optional) @@ -381,7 +391,7 @@ :param storage_customer_managed_key_id: str (optional) The ID of the key configuration object for workspace storage. This parameter is available for updating both failed and running workspaces. - + :returns: Long-running operation waiter for :class:`Workspace`. See :method:wait_get_workspace_running for more details. diff --git a/docs/account/settings/csp_enablement_account.rst b/docs/account/settings/csp_enablement_account.rst index 885aae89f..a2b8cb91a 100644 --- a/docs/account/settings/csp_enablement_account.rst +++ b/docs/account/settings/csp_enablement_account.rst @@ -7,32 +7,32 @@ The compliance security profile settings at the account level control whether to enable it for new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace creation, account admins can enable the compliance security profile individually for each workspace. - + This settings can be disabled so that new workspaces do not have compliance security profile enabled by default. .. py:method:: get( [, etag: Optional[str]]) -> CspEnablementAccountSetting Get the compliance security profile setting for new workspaces. - + Gets the compliance security profile setting for new workspaces. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`CspEnablementAccountSetting` .. py:method:: update(allow_missing: bool, setting: CspEnablementAccountSetting, field_mask: str) -> CspEnablementAccountSetting Update the compliance security profile setting for new workspaces. - + Updates the value of the compliance security profile setting for new workspaces. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`CspEnablementAccountSetting` @@ -42,10 +42,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`CspEnablementAccountSetting` \ No newline at end of file diff --git a/docs/account/settings/disable_legacy_features.rst b/docs/account/settings/disable_legacy_features.rst index b10d7e2dc..212e3f98e 100644 --- a/docs/account/settings/disable_legacy_features.rst +++ b/docs/account/settings/disable_legacy_features.rst @@ -5,7 +5,7 @@ .. py:class:: DisableLegacyFeaturesAPI Disable legacy features for new Databricks workspaces. - + For newly created workspaces: 1. Disables the use of DBFS root and mounts. 2. Hive Metastore will not be provisioned. 3. Disables the use of ‘No-isolation clusters’. 4. Disables Databricks Runtime versions prior to 13.3LTS. @@ -13,41 +13,41 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteDisableLegacyFeaturesResponse Delete the disable legacy features setting. - + Deletes the disable legacy features setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteDisableLegacyFeaturesResponse` .. py:method:: get( [, etag: Optional[str]]) -> DisableLegacyFeatures Get the disable legacy features setting. - + Gets the value of the disable legacy features setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DisableLegacyFeatures` .. py:method:: update(allow_missing: bool, setting: DisableLegacyFeatures, field_mask: str) -> DisableLegacyFeatures Update the disable legacy features setting. - + Updates the value of the disable legacy features setting. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`DisableLegacyFeatures` @@ -57,10 +57,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`DisableLegacyFeatures` \ No newline at end of file diff --git a/docs/account/settings/enable_ip_access_lists.rst b/docs/account/settings/enable_ip_access_lists.rst index 9485b7332..b570b2e37 100644 --- a/docs/account/settings/enable_ip_access_lists.rst +++ b/docs/account/settings/enable_ip_access_lists.rst @@ -10,41 +10,41 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteAccountIpAccessEnableResponse Delete the account IP access toggle setting. - + Reverts the value of the account IP access toggle setting to default (ON) - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteAccountIpAccessEnableResponse` .. py:method:: get( [, etag: Optional[str]]) -> AccountIpAccessEnable Get the account IP access toggle setting. - + Gets the value of the account IP access toggle setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`AccountIpAccessEnable` .. py:method:: update(allow_missing: bool, setting: AccountIpAccessEnable, field_mask: str) -> AccountIpAccessEnable Update the account IP access toggle setting. - + Updates the value of the account IP access toggle setting. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`AccountIpAccessEnable` @@ -54,10 +54,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`AccountIpAccessEnable` \ No newline at end of file diff --git a/docs/account/settings/esm_enablement_account.rst b/docs/account/settings/esm_enablement_account.rst index e9359d907..e14d1a71f 100644 --- a/docs/account/settings/esm_enablement_account.rst +++ b/docs/account/settings/esm_enablement_account.rst @@ -11,25 +11,25 @@ .. py:method:: get( [, etag: Optional[str]]) -> EsmEnablementAccountSetting Get the enhanced security monitoring setting for new workspaces. - + Gets the enhanced security monitoring setting for new workspaces. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`EsmEnablementAccountSetting` .. py:method:: update(allow_missing: bool, setting: EsmEnablementAccountSetting, field_mask: str) -> EsmEnablementAccountSetting Update the enhanced security monitoring setting for new workspaces. - + Updates the value of the enhanced security monitoring setting for new workspaces. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`EsmEnablementAccountSetting` @@ -39,10 +39,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`EsmEnablementAccountSetting` \ No newline at end of file diff --git a/docs/account/settings/ip_access_lists.rst b/docs/account/settings/ip_access_lists.rst index 7718d0c54..031354b15 100644 --- a/docs/account/settings/ip_access_lists.rst +++ b/docs/account/settings/ip_access_lists.rst @@ -6,92 +6,92 @@ The Accounts IP Access List API enables account admins to configure IP access lists for access to the account console. - + Account IP Access Lists affect web application access and REST API access to the account console and account APIs. If the feature is disabled for the account, all access is allowed for this account. There is support for allow lists (inclusion) and block lists (exclusion). - + When a connection is attempted: 1. **First, all block lists are checked.** If the connection IP address matches any block list, the connection is rejected. 2. **If the connection was not rejected by block lists**, the IP address is compared with the allow lists. - + If there is at least one allow list for the account, the connection is allowed only if the IP address matches an allow list. If there are no allow lists for the account, all IP addresses are allowed. - + For all allow lists and block lists combined, the account supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. - + After changes to the account-level IP access lists, it can take a few minutes for changes to take effect. .. py:method:: create(label: str, list_type: ListType [, ip_addresses: Optional[List[str]]]) -> CreateIpAccessListResponse Create access list. - + Creates an IP access list for the account. - + A list can be an allow list or a block list. See the top of this file for a description of how the server treats allow lists and block lists at runtime. - + When creating or updating an IP access list: - + * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value `QUOTA_EXCEEDED`. * If the new list would block the calling user's current IP, error 400 is returned with `error_code` value `INVALID_STATE`. - + It can take a few minutes for the changes to take effect. - + :param label: str Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. :param ip_addresses: List[str] (optional) - + :returns: :class:`CreateIpAccessListResponse` .. py:method:: delete(ip_access_list_id: str) Delete access list. - + Deletes an IP access list, specified by its list ID. - + :param ip_access_list_id: str The ID for the corresponding IP access list - - + + .. py:method:: get(ip_access_list_id: str) -> GetIpAccessListResponse Get IP access list. - + Gets an IP access list, specified by its list ID. - + :param ip_access_list_id: str The ID for the corresponding IP access list - + :returns: :class:`GetIpAccessListResponse` .. py:method:: list() -> Iterator[IpAccessListInfo] Get access lists. - + Gets all IP access lists for the specified account. - + :returns: Iterator over :class:`IpAccessListInfo` .. py:method:: replace(ip_access_list_id: str, label: str, list_type: ListType, enabled: bool [, ip_addresses: Optional[List[str]]]) Replace access list. - + Replaces an IP access list, specified by its ID. - + A list can include allow lists and block lists. See the top of this file for a description of how the server treats allow lists and block lists at run time. When replacing an IP access list: * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one @@ -99,41 +99,41 @@ `QUOTA_EXCEEDED`. * If the resulting list would block the calling user's current IP, error 400 is returned with `error_code` value `INVALID_STATE`. It can take a few minutes for the changes to take effect. - + :param ip_access_list_id: str The ID for the corresponding IP access list :param label: str Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. :param enabled: bool Specifies whether this IP access list is enabled. :param ip_addresses: List[str] (optional) - - + + .. py:method:: update(ip_access_list_id: str [, enabled: Optional[bool], ip_addresses: Optional[List[str]], label: Optional[str], list_type: Optional[ListType]]) Update access list. - + Updates an existing IP access list, specified by its ID. - + A list can include allow lists and block lists. See the top of this file for a description of how the server treats allow lists and block lists at run time. - + When updating an IP access list: - + * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value `QUOTA_EXCEEDED`. * If the updated list would block the calling user's current IP, error 400 is returned with `error_code` value `INVALID_STATE`. - + It can take a few minutes for the changes to take effect. - + :param ip_access_list_id: str The ID for the corresponding IP access list :param enabled: bool (optional) @@ -143,9 +143,9 @@ Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` (optional) Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. - - + + \ No newline at end of file diff --git a/docs/account/settings/network_connectivity.rst b/docs/account/settings/network_connectivity.rst index 30b50abcb..179db3fef 100644 --- a/docs/account/settings/network_connectivity.rst +++ b/docs/account/settings/network_connectivity.rst @@ -10,7 +10,7 @@ .. py:method:: create_network_connectivity_configuration(name: str, region: str) -> NetworkConnectivityConfiguration Create a network connectivity configuration. - + :param name: str The name of the network connectivity configuration. The name can contain alphanumeric characters, hyphens, and underscores. The length must be between 3 and 30 characters. The name must match the @@ -18,24 +18,24 @@ :param region: str The region for the network connectivity configuration. Only workspaces in the same region can be attached to the network connectivity configuration. - + :returns: :class:`NetworkConnectivityConfiguration` .. py:method:: create_private_endpoint_rule(network_connectivity_config_id: str, resource_id: str, group_id: CreatePrivateEndpointRuleRequestGroupId) -> NccAzurePrivateEndpointRule Create a private endpoint rule. - + Create a private endpoint rule for the specified network connectivity config object. Once the object is created, Databricks asynchronously provisions a new Azure private endpoint to your specified Azure resource. - + **IMPORTANT**: You must use Azure portal or other Azure tools to approve the private endpoint to complete the connection. To get the information of the private endpoint created, make a `GET` request on the new private endpoint rule. See [serverless private link]. - + [serverless private link]: https://learn.microsoft.com/azure/databricks/security/network/serverless-network-security/serverless-private-link - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. :param resource_id: str @@ -43,87 +43,87 @@ :param group_id: :class:`CreatePrivateEndpointRuleRequestGroupId` The sub-resource type (group ID) of the target resource. Note that to connect to workspace root storage (root DBFS), you need two endpoints, one for `blob` and one for `dfs`. - + :returns: :class:`NccAzurePrivateEndpointRule` .. py:method:: delete_network_connectivity_configuration(network_connectivity_config_id: str) Delete a network connectivity configuration. - + Deletes a network connectivity configuration. - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. - - + + .. py:method:: delete_private_endpoint_rule(network_connectivity_config_id: str, private_endpoint_rule_id: str) -> NccAzurePrivateEndpointRule Delete a private endpoint rule. - + Initiates deleting a private endpoint rule. If the connection state is PENDING or EXPIRED, the private endpoint is immediately deleted. Otherwise, the private endpoint is deactivated and will be deleted after seven days of deactivation. When a private endpoint is deactivated, the `deactivated` field is set to `true` and the private endpoint is not available to your serverless compute resources. - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. :param private_endpoint_rule_id: str Your private endpoint rule ID. - + :returns: :class:`NccAzurePrivateEndpointRule` .. py:method:: get_network_connectivity_configuration(network_connectivity_config_id: str) -> NetworkConnectivityConfiguration Get a network connectivity configuration. - + Gets a network connectivity configuration. - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. - + :returns: :class:`NetworkConnectivityConfiguration` .. py:method:: get_private_endpoint_rule(network_connectivity_config_id: str, private_endpoint_rule_id: str) -> NccAzurePrivateEndpointRule Get a private endpoint rule. - + Gets the private endpoint rule. - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. :param private_endpoint_rule_id: str Your private endpoint rule ID. - + :returns: :class:`NccAzurePrivateEndpointRule` .. py:method:: list_network_connectivity_configurations( [, page_token: Optional[str]]) -> Iterator[NetworkConnectivityConfiguration] List network connectivity configurations. - + Gets an array of network connectivity configurations. - + :param page_token: str (optional) Pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`NetworkConnectivityConfiguration` .. py:method:: list_private_endpoint_rules(network_connectivity_config_id: str [, page_token: Optional[str]]) -> Iterator[NccAzurePrivateEndpointRule] List private endpoint rules. - + Gets an array of private endpoint rules. - + :param network_connectivity_config_id: str Your Network Connectvity Configuration ID. :param page_token: str (optional) Pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`NccAzurePrivateEndpointRule` \ No newline at end of file diff --git a/docs/account/settings/personal_compute.rst b/docs/account/settings/personal_compute.rst index 54e958a28..58b35e7f7 100644 --- a/docs/account/settings/personal_compute.rst +++ b/docs/account/settings/personal_compute.rst @@ -7,7 +7,7 @@ The Personal Compute enablement setting lets you control which users can use the Personal Compute default policy to create compute resources. By default all users in all workspaces have access (ON), but you can change the setting to instead let individual workspaces configure access control (DELEGATE). - + There is only one instance of this setting per account. Since this setting has a default value, this setting is present on all accounts even though it's never set on a given account. Deletion reverts the value of the setting back to the default value. @@ -15,41 +15,41 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeletePersonalComputeSettingResponse Delete Personal Compute setting. - + Reverts back the Personal Compute setting value to default (ON) - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeletePersonalComputeSettingResponse` .. py:method:: get( [, etag: Optional[str]]) -> PersonalComputeSetting Get Personal Compute setting. - + Gets the value of the Personal Compute setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`PersonalComputeSetting` .. py:method:: update(allow_missing: bool, setting: PersonalComputeSetting, field_mask: str) -> PersonalComputeSetting Update Personal Compute setting. - + Updates the value of the Personal Compute setting. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`PersonalComputeSetting` @@ -59,10 +59,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`PersonalComputeSetting` \ No newline at end of file diff --git a/docs/account/settings/settings.rst b/docs/account/settings/settings.rst index abf1c0e45..19802700d 100644 --- a/docs/account/settings/settings.rst +++ b/docs/account/settings/settings.rst @@ -12,7 +12,7 @@ The compliance security profile settings at the account level control whether to enable it for new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace creation, account admins can enable the compliance security profile individually for each workspace. - + This settings can be disabled so that new workspaces do not have compliance security profile enabled by default. @@ -20,7 +20,7 @@ :type: DisableLegacyFeaturesAPI Disable legacy features for new Databricks workspaces. - + For newly created workspaces: 1. Disables the use of DBFS root and mounts. 2. Hive Metastore will not be provisioned. 3. Disables the use of ‘No-isolation clusters’. 4. Disables Databricks Runtime versions prior to 13.3LTS. @@ -44,7 +44,7 @@ The Personal Compute enablement setting lets you control which users can use the Personal Compute default policy to create compute resources. By default all users in all workspaces have access (ON), but you can change the setting to instead let individual workspaces configure access control (DELEGATE). - + There is only one instance of this setting per account. Since this setting has a default value, this setting is present on all accounts even though it's never set on a given account. Deletion reverts the value of the setting back to the default value. \ No newline at end of file diff --git a/docs/dbdataclasses/catalog.rst b/docs/dbdataclasses/catalog.rst index 17d23b223..e302b781c 100644 --- a/docs/dbdataclasses/catalog.rst +++ b/docs/dbdataclasses/catalog.rst @@ -242,6 +242,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: MYSQL :value: "MYSQL" + .. py:attribute:: ORACLE + :value: "ORACLE" + .. py:attribute:: POSTGRESQL :value: "POSTGRESQL" @@ -257,6 +260,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: SQLSERVER :value: "SQLSERVER" + .. py:attribute:: TERADATA + :value: "TERADATA" + .. autoclass:: ContinuousUpdateStatus :members: :undoc-members: @@ -1359,6 +1365,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: VIEW :value: "VIEW" +.. autoclass:: TagKeyValue + :members: + :undoc-members: + .. autoclass:: TemporaryCredentials :members: :undoc-members: diff --git a/docs/dbdataclasses/compute.rst b/docs/dbdataclasses/compute.rst index b90ec99f7..3be80b79c 100644 --- a/docs/dbdataclasses/compute.rst +++ b/docs/dbdataclasses/compute.rst @@ -320,7 +320,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: DataSecurityMode Data security mode decides what data governance model to use when accessing data from a cluster. - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. The following modes can be used regardless of `kind`. * `NONE`: No security isolation for multiple users sharing the cluster. Data governance features are not available in this mode. * `SINGLE_USER`: A secure cluster that can only be exclusively used by a single user specified in `single_user_name`. Most programming languages, cluster features and data governance features are available in this mode. * `USER_ISOLATION`: A secure cluster that can be shared by multiple users. Cluster users are fully isolated so that they cannot see each other's data and credentials. Most data governance features are supported in this mode. But programming languages and cluster features might be limited. The following modes are deprecated starting with Databricks Runtime 15.0 and will be removed for future Databricks Runtime versions: * `LEGACY_TABLE_ACL`: This mode is for users migrating from legacy Table ACL clusters. * `LEGACY_PASSTHROUGH`: This mode is for users migrating from legacy Passthrough on high concurrency clusters. * `LEGACY_SINGLE_USER`: This mode is for users migrating from legacy Passthrough on standard clusters. * `LEGACY_SINGLE_USER_STANDARD`: This mode provides a way that doesn’t have UC nor passthrough enabled. @@ -812,7 +812,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo The kind of compute described by this compute specification. Depending on `kind`, different validations and default values will be applied. - The first usage of this value is for the simple cluster form where it sets `kind = CLASSIC_PREVIEW`. + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + [simple form]: https://docs.databricks.com/compute/simple-form.html .. py:attribute:: CLASSIC_PREVIEW :value: "CLASSIC_PREVIEW" diff --git a/docs/dbdataclasses/dashboards.rst b/docs/dbdataclasses/dashboards.rst index 114bd1f5b..b68b1f1b6 100644 --- a/docs/dbdataclasses/dashboards.rst +++ b/docs/dbdataclasses/dashboards.rst @@ -25,59 +25,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: DASHBOARD_VIEW_BASIC :value: "DASHBOARD_VIEW_BASIC" -.. py:class:: DataType - - .. py:attribute:: DATA_TYPE_ARRAY - :value: "DATA_TYPE_ARRAY" - - .. py:attribute:: DATA_TYPE_BIG_INT - :value: "DATA_TYPE_BIG_INT" - - .. py:attribute:: DATA_TYPE_BINARY - :value: "DATA_TYPE_BINARY" - - .. py:attribute:: DATA_TYPE_BOOLEAN - :value: "DATA_TYPE_BOOLEAN" - - .. py:attribute:: DATA_TYPE_DATE - :value: "DATA_TYPE_DATE" - - .. py:attribute:: DATA_TYPE_DECIMAL - :value: "DATA_TYPE_DECIMAL" - - .. py:attribute:: DATA_TYPE_DOUBLE - :value: "DATA_TYPE_DOUBLE" - - .. py:attribute:: DATA_TYPE_FLOAT - :value: "DATA_TYPE_FLOAT" - - .. py:attribute:: DATA_TYPE_INT - :value: "DATA_TYPE_INT" - - .. py:attribute:: DATA_TYPE_INTERVAL - :value: "DATA_TYPE_INTERVAL" - - .. py:attribute:: DATA_TYPE_MAP - :value: "DATA_TYPE_MAP" - - .. py:attribute:: DATA_TYPE_SMALL_INT - :value: "DATA_TYPE_SMALL_INT" - - .. py:attribute:: DATA_TYPE_STRING - :value: "DATA_TYPE_STRING" - - .. py:attribute:: DATA_TYPE_STRUCT - :value: "DATA_TYPE_STRUCT" - - .. py:attribute:: DATA_TYPE_TIMESTAMP - :value: "DATA_TYPE_TIMESTAMP" - - .. py:attribute:: DATA_TYPE_TINY_INT - :value: "DATA_TYPE_TINY_INT" - - .. py:attribute:: DATA_TYPE_VOID - :value: "DATA_TYPE_VOID" - .. autoclass:: DeleteScheduleResponse :members: :undoc-members: @@ -118,6 +65,18 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: GenieQueryAttachment + :members: + :undoc-members: + +.. autoclass:: GenieResultMetadata + :members: + :undoc-members: + +.. autoclass:: GenieSpace + :members: + :undoc-members: + .. autoclass:: GenieStartConversationMessageRequest :members: :undoc-members: @@ -189,6 +148,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION :value: "FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION" + .. py:attribute:: FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION + :value: "FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION" + .. py:attribute:: FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION :value: "FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION" @@ -225,6 +187,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: LOCAL_CONTEXT_EXCEEDED_EXCEPTION :value: "LOCAL_CONTEXT_EXCEEDED_EXCEPTION" + .. py:attribute:: MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION + :value: "MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION" + .. py:attribute:: MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION :value: "MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION" @@ -281,7 +246,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: MessageStatus - MesssageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data sources. * `FILTERING_CONTEXT`: Running smart context step to determine relevant context. * `ASKING_AI`: Waiting for the LLM to respond to the users question. * `PENDING_WAREHOUSE`: Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing AI provided SQL query. Get the SQL query result by calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. **Important: The message status will stay in the `EXECUTING_QUERY` until a client calls [getMessageQueryResult](:method:genie/getMessageQueryResult)**. * `FAILED`: Generating a response or the executing the query failed. Please see `error` field. * `COMPLETED`: Message processing is completed. Results are in the `attachments` field. Get the SQL query result by calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message has been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user needs to execute the query again. * `CANCELLED`: Message has been cancelled. + MessageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data sources. * `FILTERING_CONTEXT`: Running smart context step to determine relevant context. * `ASKING_AI`: Waiting for the LLM to respond to the user's question. * `PENDING_WAREHOUSE`: Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing a generated SQL query. Get the SQL query result by calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `FAILED`: The response generation or query execution failed. See `error` field. * `COMPLETED`: Message processing is completed. Results are in the `attachments` field. Get the SQL query result by calling [getMessageQueryResult](:method:genie/getMessageQueryResult) API. * `SUBMITTED`: Message has been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available anymore. The user needs to rerun the query. * `CANCELLED`: Message has been cancelled. .. py:attribute:: ASKING_AI :value: "ASKING_AI" @@ -337,22 +302,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: -.. autoclass:: QueryAttachment - :members: - :undoc-members: - .. autoclass:: QueryResponseStatus :members: :undoc-members: -.. autoclass:: QuerySchema - :members: - :undoc-members: - -.. autoclass:: QuerySchemaColumn - :members: - :undoc-members: - .. autoclass:: Result :members: :undoc-members: diff --git a/docs/dbdataclasses/jobs.rst b/docs/dbdataclasses/jobs.rst index e85322a66..19f1a2208 100644 --- a/docs/dbdataclasses/jobs.rst +++ b/docs/dbdataclasses/jobs.rst @@ -125,6 +125,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: ComputeConfig + :members: + :undoc-members: + .. py:class:: Condition .. py:attribute:: ALL_UPDATED @@ -244,6 +248,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: SINGLE_TASK :value: "SINGLE_TASK" +.. autoclass:: GenAiComputeTask + :members: + :undoc-members: + .. autoclass:: GetJobPermissionLevelsResponse :members: :undoc-members: @@ -686,6 +694,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: TERMINATING :value: "TERMINATING" + .. py:attribute:: WAITING + :value: "WAITING" + .. autoclass:: RunNow :members: :undoc-members: diff --git a/docs/dbdataclasses/marketplace.rst b/docs/dbdataclasses/marketplace.rst index c1029d842..222c5065c 100644 --- a/docs/dbdataclasses/marketplace.rst +++ b/docs/dbdataclasses/marketplace.rst @@ -14,6 +14,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: AssetType + .. py:attribute:: ASSET_TYPE_APP + :value: "ASSET_TYPE_APP" + .. py:attribute:: ASSET_TYPE_DATA_TABLE :value: "ASSET_TYPE_DATA_TABLE" diff --git a/docs/dbdataclasses/ml.rst b/docs/dbdataclasses/ml.rst index 9ee680014..b176e56c4 100644 --- a/docs/dbdataclasses/ml.rst +++ b/docs/dbdataclasses/ml.rst @@ -263,6 +263,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: GetExperimentByNameResponse + :members: + :undoc-members: + .. autoclass:: GetExperimentPermissionLevelsResponse :members: :undoc-members: @@ -601,7 +605,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: RunInfoStatus - Current status of the run. + Status of a run. .. py:attribute:: FAILED :value: "FAILED" @@ -634,19 +638,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: -.. py:class:: SearchExperimentsViewType - - Qualifier for type of experiments to be returned. If unspecified, return only active experiments. - - .. py:attribute:: ACTIVE_ONLY - :value: "ACTIVE_ONLY" - - .. py:attribute:: ALL - :value: "ALL" - - .. py:attribute:: DELETED_ONLY - :value: "DELETED_ONLY" - .. autoclass:: SearchModelVersionsResponse :members: :undoc-members: @@ -663,19 +654,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: -.. py:class:: SearchRunsRunViewType - - Whether to display only active, only deleted, or all runs. Defaults to only active runs. - - .. py:attribute:: ACTIVE_ONLY - :value: "ACTIVE_ONLY" - - .. py:attribute:: ALL - :value: "ALL" - - .. py:attribute:: DELETED_ONLY - :value: "DELETED_ONLY" - .. autoclass:: SetExperimentTag :members: :undoc-members: @@ -813,7 +791,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: UpdateRunStatus - Updated status of the run. + Status of a run. .. py:attribute:: FAILED :value: "FAILED" @@ -833,3 +811,16 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. autoclass:: UpdateWebhookResponse :members: :undoc-members: + +.. py:class:: ViewType + + Qualifier for the view type. + + .. py:attribute:: ACTIVE_ONLY + :value: "ACTIVE_ONLY" + + .. py:attribute:: ALL + :value: "ALL" + + .. py:attribute:: DELETED_ONLY + :value: "DELETED_ONLY" diff --git a/docs/dbdataclasses/oauth2.rst b/docs/dbdataclasses/oauth2.rst index 10202e55e..4097add9e 100644 --- a/docs/dbdataclasses/oauth2.rst +++ b/docs/dbdataclasses/oauth2.rst @@ -20,6 +20,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: CreateServicePrincipalSecretRequest + :members: + :undoc-members: + .. autoclass:: CreateServicePrincipalSecretResponse :members: :undoc-members: diff --git a/docs/dbdataclasses/sharing.rst b/docs/dbdataclasses/sharing.rst index ed4a4c006..2e4437ef6 100644 --- a/docs/dbdataclasses/sharing.rst +++ b/docs/dbdataclasses/sharing.rst @@ -11,9 +11,82 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: DATABRICKS :value: "DATABRICKS" + .. py:attribute:: OAUTH_CLIENT_CREDENTIALS + :value: "OAUTH_CLIENT_CREDENTIALS" + .. py:attribute:: TOKEN :value: "TOKEN" +.. py:class:: ColumnTypeName + + UC supported column types Copied from https://src.dev.databricks.com/databricks/universe@23a85902bb58695ab9293adc9f327b0714b55e72/-/blob/managed-catalog/api/messages/table.proto?L68 + + .. py:attribute:: ARRAY + :value: "ARRAY" + + .. py:attribute:: BINARY + :value: "BINARY" + + .. py:attribute:: BOOLEAN + :value: "BOOLEAN" + + .. py:attribute:: BYTE + :value: "BYTE" + + .. py:attribute:: CHAR + :value: "CHAR" + + .. py:attribute:: DATE + :value: "DATE" + + .. py:attribute:: DECIMAL + :value: "DECIMAL" + + .. py:attribute:: DOUBLE + :value: "DOUBLE" + + .. py:attribute:: FLOAT + :value: "FLOAT" + + .. py:attribute:: INT + :value: "INT" + + .. py:attribute:: INTERVAL + :value: "INTERVAL" + + .. py:attribute:: LONG + :value: "LONG" + + .. py:attribute:: MAP + :value: "MAP" + + .. py:attribute:: NULL + :value: "NULL" + + .. py:attribute:: SHORT + :value: "SHORT" + + .. py:attribute:: STRING + :value: "STRING" + + .. py:attribute:: STRUCT + :value: "STRUCT" + + .. py:attribute:: TABLE_TYPE + :value: "TABLE_TYPE" + + .. py:attribute:: TIMESTAMP + :value: "TIMESTAMP" + + .. py:attribute:: TIMESTAMP_NTZ + :value: "TIMESTAMP_NTZ" + + .. py:attribute:: USER_DEFINED_TYPE + :value: "USER_DEFINED_TYPE" + + .. py:attribute:: VARIANT + :value: "VARIANT" + .. autoclass:: CreateProvider :members: :undoc-members: @@ -30,6 +103,53 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: DeltaSharingDependency + :members: + :undoc-members: + +.. autoclass:: DeltaSharingDependencyList + :members: + :undoc-members: + +.. autoclass:: DeltaSharingFunctionDependency + :members: + :undoc-members: + +.. autoclass:: DeltaSharingTableDependency + :members: + :undoc-members: + +.. autoclass:: Function + :members: + :undoc-members: + +.. autoclass:: FunctionParameterInfo + :members: + :undoc-members: + +.. autoclass:: FunctionParameterInfos + :members: + :undoc-members: + +.. py:class:: FunctionParameterMode + + .. py:attribute:: IN + :value: "IN" + + .. py:attribute:: INOUT + :value: "INOUT" + + .. py:attribute:: OUT + :value: "OUT" + +.. py:class:: FunctionParameterType + + .. py:attribute:: COLUMN + :value: "COLUMN" + + .. py:attribute:: PARAM + :value: "PARAM" + .. autoclass:: GetActivationUrlInfoResponse :members: :undoc-members: @@ -38,10 +158,18 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: GetSharePermissionsResponse + :members: + :undoc-members: + .. autoclass:: IpAccessList :members: :undoc-members: +.. autoclass:: ListProviderShareAssetsResponse + :members: + :undoc-members: + .. autoclass:: ListProviderSharesResponse :members: :undoc-members: @@ -58,11 +186,11 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: -.. autoclass:: Partition +.. autoclass:: NotebookFile :members: :undoc-members: -.. autoclass:: PartitionSpecificationPartition +.. autoclass:: Partition :members: :undoc-members: @@ -78,6 +206,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: LIKE :value: "LIKE" +.. autoclass:: PermissionsChange + :members: + :undoc-members: + .. py:class:: Privilege .. py:attribute:: ACCESS @@ -239,6 +371,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: RegisteredModelAlias + :members: + :undoc-members: + .. autoclass:: RetrieveTokenResponse :members: :undoc-members: @@ -265,8 +401,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: SharedDataObjectDataObjectType - The type of the data object. - .. py:attribute:: FEATURE_SPEC :value: "FEATURE_SPEC" @@ -296,8 +430,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: SharedDataObjectHistoryDataSharingStatus - Whether to enable or disable sharing of data history. If not specified, the default is **DISABLED**. - .. py:attribute:: DISABLED :value: "DISABLED" @@ -306,8 +438,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: SharedDataObjectStatus - One of: **ACTIVE**, **PERMISSION_DENIED**. - .. py:attribute:: ACTIVE :value: "ACTIVE" @@ -320,8 +450,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: SharedDataObjectUpdateAction - One of: **ADD**, **REMOVE**, **UPDATE**. - .. py:attribute:: ADD :value: "ADD" @@ -331,10 +459,47 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: UPDATE :value: "UPDATE" -.. autoclass:: UpdatePermissionsResponse +.. py:class:: SharedSecurableKind + + The SecurableKind of a delta-shared object. + + .. py:attribute:: FUNCTION_FEATURE_SPEC + :value: "FUNCTION_FEATURE_SPEC" + + .. py:attribute:: FUNCTION_REGISTERED_MODEL + :value: "FUNCTION_REGISTERED_MODEL" + + .. py:attribute:: FUNCTION_STANDARD + :value: "FUNCTION_STANDARD" + +.. autoclass:: Table :members: :undoc-members: +.. autoclass:: TableInternalAttributes + :members: + :undoc-members: + +.. py:class:: TableInternalAttributesSharedTableType + + .. py:attribute:: DIRECTORY_BASED_TABLE + :value: "DIRECTORY_BASED_TABLE" + + .. py:attribute:: FILE_BASED_TABLE + :value: "FILE_BASED_TABLE" + + .. py:attribute:: FOREIGN_TABLE + :value: "FOREIGN_TABLE" + + .. py:attribute:: MATERIALIZED_VIEW + :value: "MATERIALIZED_VIEW" + + .. py:attribute:: STREAMING_TABLE + :value: "STREAMING_TABLE" + + .. py:attribute:: VIEW + :value: "VIEW" + .. autoclass:: UpdateProvider :members: :undoc-members: @@ -350,3 +515,15 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. autoclass:: UpdateSharePermissions :members: :undoc-members: + +.. autoclass:: UpdateSharePermissionsResponse + :members: + :undoc-members: + +.. autoclass:: Volume + :members: + :undoc-members: + +.. autoclass:: VolumeInternalAttributes + :members: + :undoc-members: diff --git a/docs/dbdataclasses/workspace.rst b/docs/dbdataclasses/workspace.rst index bd0785db4..e20f4ac7d 100644 --- a/docs/dbdataclasses/workspace.rst +++ b/docs/dbdataclasses/workspace.rst @@ -93,6 +93,8 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: ExportFormat + The format for workspace import and export. + .. py:attribute:: AUTO :value: "AUTO" @@ -105,6 +107,9 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: JUPYTER :value: "JUPYTER" + .. py:attribute:: RAW + :value: "RAW" + .. py:attribute:: R_MARKDOWN :value: "R_MARKDOWN" @@ -141,9 +146,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: ImportFormat - This specifies the format of the file to be imported. - The value is case sensitive. - - `AUTO`: The item is imported depending on an analysis of the item's extension and the header content provided in the request. If the item is imported as a notebook, then the item's extension is automatically removed. - `SOURCE`: The notebook or directory is imported as source code. - `HTML`: The notebook is imported as an HTML file. - `JUPYTER`: The notebook is imported as a Jupyter/IPython Notebook file. - `DBC`: The notebook is imported in Databricks archive format. Required for directories. - `R_MARKDOWN`: The notebook is imported from R Markdown format. + The format for workspace import and export. .. py:attribute:: AUTO :value: "AUTO" @@ -172,7 +175,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: Language - The language of the object. This value is set only if the object type is `NOTEBOOK`. + The language of notebook. .. py:attribute:: PYTHON :value: "PYTHON" @@ -225,7 +228,6 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: ObjectType The type of the object in workspace. - - `NOTEBOOK`: document that contains runnable code, visualizations, and explanatory text. - `DIRECTORY`: directory - `LIBRARY`: library - `FILE`: file - `REPO`: repository - `DASHBOARD`: Lakeview dashboard .. py:attribute:: DASHBOARD :value: "DASHBOARD" diff --git a/docs/workspace/apps/apps.rst b/docs/workspace/apps/apps.rst index af7229f34..dc3c8a8ef 100644 --- a/docs/workspace/apps/apps.rst +++ b/docs/workspace/apps/apps.rst @@ -10,13 +10,13 @@ .. py:method:: create( [, app: Optional[App], no_compute: Optional[bool]]) -> Wait[App] Create an app. - + Creates a new app. - + :param app: :class:`App` (optional) :param no_compute: bool (optional) If true, the app will not be started after creation. - + :returns: Long-running operation waiter for :class:`App`. See :method:wait_get_app_active for more details. @@ -28,25 +28,25 @@ .. py:method:: delete(name: str) -> App Delete an app. - + Deletes an app. - + :param name: str The name of the app. - + :returns: :class:`App` .. py:method:: deploy(app_name: str [, app_deployment: Optional[AppDeployment]]) -> Wait[AppDeployment] Create an app deployment. - + Creates an app deployment for the app with the supplied name. - + :param app_name: str The name of the app. :param app_deployment: :class:`AppDeployment` (optional) - + :returns: Long-running operation waiter for :class:`AppDeployment`. See :method:wait_get_deployment_app_succeeded for more details. @@ -58,106 +58,106 @@ .. py:method:: get(name: str) -> App Get an app. - + Retrieves information for the app with the supplied name. - + :param name: str The name of the app. - + :returns: :class:`App` .. py:method:: get_deployment(app_name: str, deployment_id: str) -> AppDeployment Get an app deployment. - + Retrieves information for the app deployment with the supplied name and deployment id. - + :param app_name: str The name of the app. :param deployment_id: str The unique id of the deployment. - + :returns: :class:`AppDeployment` .. py:method:: get_permission_levels(app_name: str) -> GetAppPermissionLevelsResponse Get app permission levels. - + Gets the permission levels that a user can have on an object. - + :param app_name: str The app for which to get or manage permissions. - + :returns: :class:`GetAppPermissionLevelsResponse` .. py:method:: get_permissions(app_name: str) -> AppPermissions Get app permissions. - + Gets the permissions of an app. Apps can inherit permissions from their root object. - + :param app_name: str The app for which to get or manage permissions. - + :returns: :class:`AppPermissions` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[App] List apps. - + Lists all apps in the workspace. - + :param page_size: int (optional) Upper bound for items returned. :param page_token: str (optional) Pagination token to go to the next page of apps. Requests first page if absent. - + :returns: Iterator over :class:`App` .. py:method:: list_deployments(app_name: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[AppDeployment] List app deployments. - + Lists all app deployments for the app with the supplied name. - + :param app_name: str The name of the app. :param page_size: int (optional) Upper bound for items returned. :param page_token: str (optional) Pagination token to go to the next page of apps. Requests first page if absent. - + :returns: Iterator over :class:`AppDeployment` .. py:method:: set_permissions(app_name: str [, access_control_list: Optional[List[AppAccessControlRequest]]]) -> AppPermissions Set app permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param app_name: str The app for which to get or manage permissions. :param access_control_list: List[:class:`AppAccessControlRequest`] (optional) - + :returns: :class:`AppPermissions` .. py:method:: start(name: str) -> Wait[App] Start an app. - + Start the last active deployment of the app in the workspace. - + :param name: str The name of the app. - + :returns: Long-running operation waiter for :class:`App`. See :method:wait_get_app_active for more details. @@ -169,12 +169,12 @@ .. py:method:: stop(name: str) -> Wait[App] Stop an app. - + Stops the active deployment of the app in the workspace. - + :param name: str The name of the app. - + :returns: Long-running operation waiter for :class:`App`. See :method:wait_get_app_stopped for more details. @@ -186,27 +186,27 @@ .. py:method:: update(name: str [, app: Optional[App]]) -> App Update an app. - + Updates the app with the supplied name. - + :param name: str The name of the app. The name must contain only lowercase alphanumeric characters and hyphens. It must be unique within the workspace. :param app: :class:`App` (optional) - + :returns: :class:`App` .. py:method:: update_permissions(app_name: str [, access_control_list: Optional[List[AppAccessControlRequest]]]) -> AppPermissions Update app permissions. - + Updates the permissions on an app. Apps can inherit permissions from their root object. - + :param app_name: str The app for which to get or manage permissions. :param access_control_list: List[:class:`AppAccessControlRequest`] (optional) - + :returns: :class:`AppPermissions` diff --git a/docs/workspace/catalog/artifact_allowlists.rst b/docs/workspace/catalog/artifact_allowlists.rst index 349bbbd0f..b86ef3bc0 100644 --- a/docs/workspace/catalog/artifact_allowlists.rst +++ b/docs/workspace/catalog/artifact_allowlists.rst @@ -10,28 +10,28 @@ .. py:method:: get(artifact_type: ArtifactType) -> ArtifactAllowlistInfo Get an artifact allowlist. - + Get the artifact allowlist of a certain artifact type. The caller must be a metastore admin or have the **MANAGE ALLOWLIST** privilege on the metastore. - + :param artifact_type: :class:`ArtifactType` The artifact type of the allowlist. - + :returns: :class:`ArtifactAllowlistInfo` .. py:method:: update(artifact_type: ArtifactType, artifact_matchers: List[ArtifactMatcher]) -> ArtifactAllowlistInfo Set an artifact allowlist. - + Set the artifact allowlist of a certain artifact type. The whole artifact allowlist is replaced with the new allowlist. The caller must be a metastore admin or have the **MANAGE ALLOWLIST** privilege on the metastore. - + :param artifact_type: :class:`ArtifactType` The artifact type of the allowlist. :param artifact_matchers: List[:class:`ArtifactMatcher`] A list of allowed artifact match patterns. - + :returns: :class:`ArtifactAllowlistInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/catalogs.rst b/docs/workspace/catalog/catalogs.rst index 1d6b6dc2a..60959cad4 100644 --- a/docs/workspace/catalog/catalogs.rst +++ b/docs/workspace/catalog/catalogs.rst @@ -6,7 +6,7 @@ A catalog is the first layer of Unity Catalog’s three-level namespace. It’s used to organize your data assets. Users can see all catalogs on which they have been assigned the USE_CATALOG data permission. - + In Unity Catalog, admins and data stewards manage users and their access to data centrally across all of the workspaces in a Databricks account. Users in different workspaces can share access to the same data, depending on privileges granted centrally in Unity Catalog. @@ -24,16 +24,16 @@ w = WorkspaceClient() - created = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created = w.catalogs.create(name=f"sdk-{time.time_ns()}") # cleanup w.catalogs.delete(name=created.name, force=True) Create a catalog. - + Creates a new catalog instance in the parent metastore if the caller is a metastore admin or has the **CREATE_CATALOG** privilege. - + :param name: str Name of catalog. :param comment: str (optional) @@ -46,29 +46,29 @@ A map of key-value properties attached to the securable. :param provider_name: str (optional) The name of delta sharing provider. - + A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server. :param share_name: str (optional) The name of the share under the share provider. :param storage_root: str (optional) Storage root URL for managed tables within catalog. - + :returns: :class:`CatalogInfo` .. py:method:: delete(name: str [, force: Optional[bool]]) Delete a catalog. - + Deletes the catalog that matches the supplied name. The caller must be a metastore admin or the owner of the catalog. - + :param name: str The name of the catalog. :param force: bool (optional) Force deletion even if the catalog is not empty. - - + + .. py:method:: get(name: str [, include_browse: Optional[bool]]) -> CatalogInfo @@ -84,7 +84,7 @@ w = WorkspaceClient() - created = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created = w.catalogs.create(name=f"sdk-{time.time_ns()}") _ = w.catalogs.get(name=created.name) @@ -92,16 +92,16 @@ w.catalogs.delete(name=created.name, force=True) Get a catalog. - + Gets the specified catalog in a metastore. The caller must be a metastore admin, the owner of the catalog, or a user that has the **USE_CATALOG** privilege set for their account. - + :param name: str The name of the catalog. :param include_browse: bool (optional) Whether to include catalogs in the response for which the principal can only access selective metadata for - + :returns: :class:`CatalogInfo` @@ -120,12 +120,12 @@ all = w.catalogs.list(catalog.ListCatalogsRequest()) List catalogs. - + Gets an array of catalogs in the metastore. If the caller is the metastore admin, all catalogs will be retrieved. Otherwise, only catalogs owned by the caller (or for which the caller has the **USE_CATALOG** privilege) will be retrieved. There is no guarantee of a specific ordering of the elements in the array. - + :param include_browse: bool (optional) Whether to include catalogs in the response for which the principal can only access selective metadata for @@ -139,7 +139,7 @@ response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`CatalogInfo` @@ -156,7 +156,7 @@ w = WorkspaceClient() - created = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created = w.catalogs.create(name=f"sdk-{time.time_ns()}") _ = w.catalogs.update(name=created.name, comment="updated") @@ -164,10 +164,10 @@ w.catalogs.delete(name=created.name, force=True) Update a catalog. - + Updates the catalog that matches the supplied name. The caller must be either the owner of the catalog, or a metastore admin (when changing the owner field of the catalog). - + :param name: str The name of the catalog. :param comment: str (optional) @@ -184,6 +184,6 @@ Username of current owner of catalog. :param properties: Dict[str,str] (optional) A map of key-value properties attached to the securable. - + :returns: :class:`CatalogInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/connections.rst b/docs/workspace/catalog/connections.rst index b2637c2d0..463c9493e 100644 --- a/docs/workspace/catalog/connections.rst +++ b/docs/workspace/catalog/connections.rst @@ -5,7 +5,7 @@ .. py:class:: ConnectionsAPI Connections allow for creating a connection to an external data source. - + A connection is an abstraction of an external data source that can be connected from Databricks Compute. Creating a connection object is the first step to managing external data sources within Unity Catalog, with the second step being creating a data object (catalog, schema, or table) using the connection. Data @@ -27,28 +27,27 @@ w = WorkspaceClient() - conn_create = w.connections.create(comment="Go SDK Acceptance Test Connection", - connection_type=catalog.ConnectionType.DATABRICKS, - name=f'sdk-{time.time_ns()}', - options={ - "host": - "%s-fake-workspace.cloud.databricks.com" % (f'sdk-{time.time_ns()}'), - "httpPath": - "/sql/1.0/warehouses/%s" % (f'sdk-{time.time_ns()}'), - "personalAccessToken": - f'sdk-{time.time_ns()}', - }) + conn_create = w.connections.create( + comment="Go SDK Acceptance Test Connection", + connection_type=catalog.ConnectionType.DATABRICKS, + name=f"sdk-{time.time_ns()}", + options={ + "host": "%s-fake-workspace.cloud.databricks.com" % (f"sdk-{time.time_ns()}"), + "httpPath": "/sql/1.0/warehouses/%s" % (f"sdk-{time.time_ns()}"), + "personalAccessToken": f"sdk-{time.time_ns()}", + }, + ) # cleanup w.connections.delete(name=conn_create.name) Create a connection. - + Creates a new connection - + Creates a new connection to an external data source. It allows users to specify connection details and configurations for interaction with the external server. - + :param name: str Name of the connection. :param connection_type: :class:`ConnectionType` @@ -61,20 +60,20 @@ An object containing map of key-value properties attached to the connection. :param read_only: bool (optional) If the connection is read only. - + :returns: :class:`ConnectionInfo` .. py:method:: delete(name: str) Delete a connection. - + Deletes the connection that matches the supplied name. - + :param name: str The name of the connection to be deleted. - - + + .. py:method:: get(name: str) -> ConnectionInfo @@ -91,27 +90,25 @@ w = WorkspaceClient() - conn_create = w.connections.create(comment="Go SDK Acceptance Test Connection", - connection_type=catalog.ConnectionType.DATABRICKS, - name=f'sdk-{time.time_ns()}', - options={ - "host": - "%s-fake-workspace.cloud.databricks.com" % (f'sdk-{time.time_ns()}'), - "httpPath": - "/sql/1.0/warehouses/%s" % (f'sdk-{time.time_ns()}'), - "personalAccessToken": - f'sdk-{time.time_ns()}', - }) - - conn_update = w.connections.update(name=conn_create.name, - options={ - "host": - "%s-fake-workspace.cloud.databricks.com" % (f'sdk-{time.time_ns()}'), - "httpPath": - "/sql/1.0/warehouses/%s" % (f'sdk-{time.time_ns()}'), - "personalAccessToken": - f'sdk-{time.time_ns()}', - }) + conn_create = w.connections.create( + comment="Go SDK Acceptance Test Connection", + connection_type=catalog.ConnectionType.DATABRICKS, + name=f"sdk-{time.time_ns()}", + options={ + "host": "%s-fake-workspace.cloud.databricks.com" % (f"sdk-{time.time_ns()}"), + "httpPath": "/sql/1.0/warehouses/%s" % (f"sdk-{time.time_ns()}"), + "personalAccessToken": f"sdk-{time.time_ns()}", + }, + ) + + conn_update = w.connections.update( + name=conn_create.name, + options={ + "host": "%s-fake-workspace.cloud.databricks.com" % (f"sdk-{time.time_ns()}"), + "httpPath": "/sql/1.0/warehouses/%s" % (f"sdk-{time.time_ns()}"), + "personalAccessToken": f"sdk-{time.time_ns()}", + }, + ) conn = w.connections.get(name=conn_update.name) @@ -119,12 +116,12 @@ w.connections.delete(name=conn_create.name) Get a connection. - + Gets a connection from it's name. - + :param name: str Name of the connection. - + :returns: :class:`ConnectionInfo` @@ -143,9 +140,9 @@ conn_list = w.connections.list(catalog.ListConnectionsRequest()) List connections. - + List all connections. - + :param max_results: int (optional) Maximum number of connections to return. - If not set, all connections are returned (not recommended). - when set to a value greater than 0, the page length is the minimum of this value and @@ -153,7 +150,7 @@ (recommended); - when set to a value less than 0, an invalid parameter error is returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ConnectionInfo` @@ -171,35 +168,33 @@ w = WorkspaceClient() - conn_create = w.connections.create(comment="Go SDK Acceptance Test Connection", - connection_type=catalog.ConnectionType.DATABRICKS, - name=f'sdk-{time.time_ns()}', - options={ - "host": - "%s-fake-workspace.cloud.databricks.com" % (f'sdk-{time.time_ns()}'), - "httpPath": - "/sql/1.0/warehouses/%s" % (f'sdk-{time.time_ns()}'), - "personalAccessToken": - f'sdk-{time.time_ns()}', - }) - - conn_update = w.connections.update(name=conn_create.name, - options={ - "host": - "%s-fake-workspace.cloud.databricks.com" % (f'sdk-{time.time_ns()}'), - "httpPath": - "/sql/1.0/warehouses/%s" % (f'sdk-{time.time_ns()}'), - "personalAccessToken": - f'sdk-{time.time_ns()}', - }) + conn_create = w.connections.create( + comment="Go SDK Acceptance Test Connection", + connection_type=catalog.ConnectionType.DATABRICKS, + name=f"sdk-{time.time_ns()}", + options={ + "host": "%s-fake-workspace.cloud.databricks.com" % (f"sdk-{time.time_ns()}"), + "httpPath": "/sql/1.0/warehouses/%s" % (f"sdk-{time.time_ns()}"), + "personalAccessToken": f"sdk-{time.time_ns()}", + }, + ) + + conn_update = w.connections.update( + name=conn_create.name, + options={ + "host": "%s-fake-workspace.cloud.databricks.com" % (f"sdk-{time.time_ns()}"), + "httpPath": "/sql/1.0/warehouses/%s" % (f"sdk-{time.time_ns()}"), + "personalAccessToken": f"sdk-{time.time_ns()}", + }, + ) # cleanup w.connections.delete(name=conn_create.name) Update a connection. - + Updates the connection that matches the supplied name. - + :param name: str Name of the connection. :param options: Dict[str,str] @@ -208,6 +203,6 @@ New name for the connection. :param owner: str (optional) Username of current owner of the connection. - + :returns: :class:`ConnectionInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/credentials.rst b/docs/workspace/catalog/credentials.rst index 3927e6351..661d955b0 100644 --- a/docs/workspace/catalog/credentials.rst +++ b/docs/workspace/catalog/credentials.rst @@ -7,7 +7,7 @@ A credential represents an authentication and authorization mechanism for accessing services on your cloud tenant. Each credential is subject to Unity Catalog access-control policies that control which users and groups can access the credential. - + To create credentials, you must be a Databricks account admin or have the `CREATE SERVICE CREDENTIAL` privilege. The user who creates the credential can delegate ownership to another user or group to manage permissions on it. @@ -15,13 +15,13 @@ .. py:method:: create_credential(name: str [, aws_iam_role: Optional[AwsIamRole], azure_managed_identity: Optional[AzureManagedIdentity], azure_service_principal: Optional[AzureServicePrincipal], comment: Optional[str], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccount], purpose: Optional[CredentialPurpose], read_only: Optional[bool], skip_validation: Optional[bool]]) -> CredentialInfo Create a credential. - + Creates a new credential. The type of credential to be created is determined by the **purpose** field, which should be either **SERVICE** or **STORAGE**. - + The caller must be a metastore admin or have the metastore privilege **CREATE_STORAGE_CREDENTIAL** for storage credentials, or **CREATE_SERVICE_CREDENTIAL** for service credentials. - + :param name: str The credential name. The name must be unique among storage and service credentials within the metastore. @@ -42,66 +42,66 @@ **STORAGE**. :param skip_validation: bool (optional) Optional. Supplying true to this argument skips validation of the created set of credentials. - + :returns: :class:`CredentialInfo` .. py:method:: delete_credential(name_arg: str [, force: Optional[bool]]) Delete a credential. - + Deletes a service or storage credential from the metastore. The caller must be an owner of the credential. - + :param name_arg: str Name of the credential. :param force: bool (optional) Force an update even if there are dependent services (when purpose is **SERVICE**) or dependent external locations and external tables (when purpose is **STORAGE**). - - + + .. py:method:: generate_temporary_service_credential(credential_name: str [, azure_options: Optional[GenerateTemporaryServiceCredentialAzureOptions], gcp_options: Optional[GenerateTemporaryServiceCredentialGcpOptions]]) -> TemporaryCredentials Generate a temporary service credential. - + Returns a set of temporary credentials generated using the specified service credential. The caller must be a metastore admin or have the metastore privilege **ACCESS** on the service credential. - + :param credential_name: str The name of the service credential used to generate a temporary credential :param azure_options: :class:`GenerateTemporaryServiceCredentialAzureOptions` (optional) The Azure cloud options to customize the requested temporary credential :param gcp_options: :class:`GenerateTemporaryServiceCredentialGcpOptions` (optional) The GCP cloud options to customize the requested temporary credential - + :returns: :class:`TemporaryCredentials` .. py:method:: get_credential(name_arg: str) -> CredentialInfo Get a credential. - + Gets a service or storage credential from the metastore. The caller must be a metastore admin, the owner of the credential, or have any permission on the credential. - + :param name_arg: str Name of the credential. - + :returns: :class:`CredentialInfo` .. py:method:: list_credentials( [, max_results: Optional[int], page_token: Optional[str], purpose: Optional[CredentialPurpose]]) -> Iterator[CredentialInfo] List credentials. - + Gets an array of credentials (as __CredentialInfo__ objects). - + The array is limited to only the credentials that the caller has permission to access. If the caller is a metastore admin, retrieval of credentials is unrestricted. There is no guarantee of a specific ordering of the elements in the array. - + :param max_results: int (optional) Maximum number of credentials to return. - If not set, the default max page size is used. - When set to a value greater than 0, the page length is the minimum of this value and a server-configured @@ -111,19 +111,19 @@ Opaque token to retrieve the next page of results. :param purpose: :class:`CredentialPurpose` (optional) Return only credentials for the specified purpose. - + :returns: Iterator over :class:`CredentialInfo` .. py:method:: update_credential(name_arg: str [, aws_iam_role: Optional[AwsIamRole], azure_managed_identity: Optional[AzureManagedIdentity], azure_service_principal: Optional[AzureServicePrincipal], comment: Optional[str], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccount], force: Optional[bool], isolation_mode: Optional[IsolationMode], new_name: Optional[str], owner: Optional[str], read_only: Optional[bool], skip_validation: Optional[bool]]) -> CredentialInfo Update a credential. - + Updates a service or storage credential on the metastore. - + The caller must be the owner of the credential or a metastore admin or have the `MANAGE` permission. If the caller is a metastore admin, only the __owner__ field can be changed. - + :param name_arg: str Name of the credential. :param aws_iam_role: :class:`AwsIamRole` (optional) @@ -150,34 +150,36 @@ **STORAGE**. :param skip_validation: bool (optional) Supply true to this argument to skip validation of the updated credential. - + :returns: :class:`CredentialInfo` - .. py:method:: validate_credential( [, aws_iam_role: Optional[AwsIamRole], azure_managed_identity: Optional[AzureManagedIdentity], credential_name: Optional[str], external_location_name: Optional[str], purpose: Optional[CredentialPurpose], read_only: Optional[bool], url: Optional[str]]) -> ValidateCredentialResponse + .. py:method:: validate_credential( [, aws_iam_role: Optional[AwsIamRole], azure_managed_identity: Optional[AzureManagedIdentity], credential_name: Optional[str], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccount], external_location_name: Optional[str], purpose: Optional[CredentialPurpose], read_only: Optional[bool], url: Optional[str]]) -> ValidateCredentialResponse Validate a credential. - + Validates a credential. - + For service credentials (purpose is **SERVICE**), either the __credential_name__ or the cloud-specific credential must be provided. - + For storage credentials (purpose is **STORAGE**), at least one of __external_location_name__ and __url__ need to be provided. If only one of them is provided, it will be used for validation. And if both are provided, the __url__ will be used for validation, and __external_location_name__ will be ignored when checking overlapping urls. Either the __credential_name__ or the cloud-specific credential must be provided. - + The caller must be a metastore admin or the credential owner or have the required permission on the metastore and the credential (e.g., **CREATE_EXTERNAL_LOCATION** when purpose is **STORAGE**). - + :param aws_iam_role: :class:`AwsIamRole` (optional) The AWS IAM role configuration :param azure_managed_identity: :class:`AzureManagedIdentity` (optional) The Azure managed identity configuration. :param credential_name: str (optional) Required. The name of an existing credential or long-lived cloud credential to validate. + :param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccount` (optional) + GCP long-lived credential. Databricks-created Google Cloud Storage service account. :param external_location_name: str (optional) The name of an existing external location to validate. Only applicable for storage credentials (purpose is **STORAGE**.) @@ -188,6 +190,6 @@ (purpose is **STORAGE**.) :param url: str (optional) The external location url to validate. Only applicable when purpose is **STORAGE**. - + :returns: :class:`ValidateCredentialResponse` \ No newline at end of file diff --git a/docs/workspace/catalog/external_locations.rst b/docs/workspace/catalog/external_locations.rst index fc60b18f6..980467306 100644 --- a/docs/workspace/catalog/external_locations.rst +++ b/docs/workspace/catalog/external_locations.rst @@ -9,9 +9,9 @@ access-control policies that control which users and groups can access the credential. If a user does not have access to an external location in Unity Catalog, the request fails and Unity Catalog does not attempt to authenticate to your cloud tenant on the user’s behalf. - + Databricks recommends using external locations rather than using storage credentials directly. - + To create external locations, you must be a metastore admin or a user with the **CREATE_EXTERNAL_LOCATION** privilege. @@ -31,26 +31,28 @@ w = WorkspaceClient() storage_credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), - comment="created via SDK") + comment="created via SDK", + ) - external_location = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=storage_credential.name, - comment="created via SDK", - url="s3://" + os.environ["TEST_BUCKET"] + "/" + - f'sdk-{time.time_ns()}') + external_location = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=storage_credential.name, + comment="created via SDK", + url="s3://" + os.environ["TEST_BUCKET"] + "/" + f"sdk-{time.time_ns()}", + ) # cleanup w.storage_credentials.delete(name=storage_credential.name) w.external_locations.delete(name=external_location.name) Create an external location. - + Creates a new external location entry in the metastore. The caller must be a metastore admin or have the **CREATE_EXTERNAL_LOCATION** privilege on both the metastore and the associated storage credential. - + :param name: str Name of the external location. :param url: str @@ -71,23 +73,23 @@ Indicates whether the external location is read-only. :param skip_validation: bool (optional) Skips validation of the storage credential associated with the external location. - + :returns: :class:`ExternalLocationInfo` .. py:method:: delete(name: str [, force: Optional[bool]]) Delete an external location. - + Deletes the specified external location from the metastore. The caller must be the owner of the external location. - + :param name: str Name of the external location. :param force: bool (optional) Force deletion even if there are dependent external tables or mounts. - - + + .. py:method:: get(name: str [, include_browse: Optional[bool]]) -> ExternalLocationInfo @@ -106,12 +108,15 @@ w = WorkspaceClient() credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + name=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) - created = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=credential.name, - url=f's3://{os.environ["TEST_BUCKET"]}/sdk-{time.time_ns()}') + created = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=credential.name, + url=f's3://{os.environ["TEST_BUCKET"]}/sdk-{time.time_ns()}', + ) _ = w.external_locations.get(get=created.name) @@ -120,16 +125,16 @@ w.external_locations.delete(delete=created.name) Get an external location. - + Gets an external location from the metastore. The caller must be either a metastore admin, the owner of the external location, or a user that has some privilege on the external location. - + :param name: str Name of the external location. :param include_browse: bool (optional) Whether to include external locations in the response for which the principal can only access selective metadata for - + :returns: :class:`ExternalLocationInfo` @@ -148,11 +153,11 @@ all = w.external_locations.list(catalog.ListExternalLocationsRequest()) List external locations. - + Gets an array of external locations (__ExternalLocationInfo__ objects) from the metastore. The caller must be a metastore admin, the owner of the external location, or a user that has some privilege on the external location. There is no guarantee of a specific ordering of the elements in the array. - + :param include_browse: bool (optional) Whether to include external locations in the response for which the principal can only access selective metadata for @@ -163,7 +168,7 @@ value (recommended); - when set to a value less than 0, an invalid parameter error is returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ExternalLocationInfo` @@ -183,27 +188,32 @@ w = WorkspaceClient() credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + name=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) - created = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=credential.name, - url="s3://%s/%s" % (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=credential.name, + url="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) - _ = w.external_locations.update(name=created.name, - credential_name=credential.name, - url="s3://%s/%s" % (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + _ = w.external_locations.update( + name=created.name, + credential_name=credential.name, + url="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) # cleanup w.storage_credentials.delete(name=credential.name) w.external_locations.delete(name=created.name) Update an external location. - + Updates an external location in the metastore. The caller must be the owner of the external location, or be a metastore admin. In the second case, the admin can only update the name of the external location. - + :param name: str Name of the external location. :param access_point: str (optional) @@ -231,6 +241,6 @@ Skips validation of the storage credential associated with the external location. :param url: str (optional) Path URL of the external location. - + :returns: :class:`ExternalLocationInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/functions.rst b/docs/workspace/catalog/functions.rst index 646488074..3c736e714 100644 --- a/docs/workspace/catalog/functions.rst +++ b/docs/workspace/catalog/functions.rst @@ -5,7 +5,7 @@ .. py:class:: FunctionsAPI Functions implement User-Defined Functions (UDFs) in Unity Catalog. - + The function implementation can be any SQL expression or Query, and it can be invoked wherever a table reference is allowed in a query. In Unity Catalog, a function resides at the same level as a table, so it can be referenced with the form __catalog_name__.__schema_name__.__function_name__. @@ -13,71 +13,71 @@ .. py:method:: create(function_info: CreateFunction) -> FunctionInfo Create a function. - + **WARNING: This API is experimental and will change in future versions** - + Creates a new function - + The user must have the following permissions in order for the function to be created: - **USE_CATALOG** on the function's parent catalog - **USE_SCHEMA** and **CREATE_FUNCTION** on the function's parent schema - + :param function_info: :class:`CreateFunction` Partial __FunctionInfo__ specifying the function to be created. - + :returns: :class:`FunctionInfo` .. py:method:: delete(name: str [, force: Optional[bool]]) Delete a function. - + Deletes the function that matches the supplied name. For the deletion to succeed, the user must satisfy one of the following conditions: - Is the owner of the function's parent catalog - Is the owner of the function's parent schema and have the **USE_CATALOG** privilege on its parent catalog - Is the owner of the function itself and have both the **USE_CATALOG** privilege on its parent catalog and the **USE_SCHEMA** privilege on its parent schema - + :param name: str The fully-qualified name of the function (of the form __catalog_name__.__schema_name__.__function__name__). :param force: bool (optional) Force deletion even if the function is notempty. - - + + .. py:method:: get(name: str [, include_browse: Optional[bool]]) -> FunctionInfo Get a function. - + Gets a function from within a parent catalog and schema. For the fetch to succeed, the user must satisfy one of the following requirements: - Is a metastore admin - Is an owner of the function's parent catalog - Have the **USE_CATALOG** privilege on the function's parent catalog and be the owner of the function - Have the **USE_CATALOG** privilege on the function's parent catalog, the **USE_SCHEMA** privilege on the function's parent schema, and the **EXECUTE** privilege on the function itself - + :param name: str The fully-qualified name of the function (of the form __catalog_name__.__schema_name__.__function__name__). :param include_browse: bool (optional) Whether to include functions in the response for which the principal can only access selective metadata for - + :returns: :class:`FunctionInfo` .. py:method:: list(catalog_name: str, schema_name: str [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[FunctionInfo] List functions. - + List functions within the specified parent catalog and schema. If the user is a metastore admin, all functions are returned in the output list. Otherwise, the user must have the **USE_CATALOG** privilege on the catalog and the **USE_SCHEMA** privilege on the schema, and the output list contains only functions for which either the user has the **EXECUTE** privilege or the user is the owner. There is no guarantee of a specific ordering of the elements in the array. - + :param catalog_name: str Name of parent catalog for functions of interest. :param schema_name: str @@ -92,26 +92,26 @@ (recommended); - when set to a value less than 0, an invalid parameter error is returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`FunctionInfo` .. py:method:: update(name: str [, owner: Optional[str]]) -> FunctionInfo Update a function. - + Updates the function that matches the supplied name. Only the owner of the function can be updated. If the user is not a metastore admin, the user must be a member of the group that is the new function owner. - Is a metastore admin - Is the owner of the function's parent catalog - Is the owner of the function's parent schema and has the **USE_CATALOG** privilege on its parent catalog - Is the owner of the function itself and has the **USE_CATALOG** privilege on its parent catalog as well as the **USE_SCHEMA** privilege on the function's parent schema. - + :param name: str The fully-qualified name of the function (of the form __catalog_name__.__schema_name__.__function__name__). :param owner: str (optional) Username of current owner of function. - + :returns: :class:`FunctionInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/grants.rst b/docs/workspace/catalog/grants.rst index 8def7ff83..73b3dae28 100644 --- a/docs/workspace/catalog/grants.rst +++ b/docs/workspace/catalog/grants.rst @@ -8,7 +8,7 @@ Access can be granted by either a metastore admin, the owner of an object, or the owner of the catalog or schema that contains the object. Securable objects in Unity Catalog are hierarchical and privileges are inherited downward. - + Securable objects in Unity Catalog are hierarchical and privileges are inherited downward. This means that granting a privilege on the catalog automatically grants the privilege to all current and future objects within the catalog. Similarly, privileges granted on a schema are inherited by all current and future @@ -29,22 +29,31 @@ w = WorkspaceClient() - table_name = f'sdk-{time.time_ns()}' + table_name = f"sdk-{time.time_ns()}" - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - _ = w.statement_execution.execute(warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], - catalog=created_catalog.name, - schema=created_schema.name, - statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name)).result() + _ = w.statement_execution.execute( + warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], + catalog=created_catalog.name, + schema=created_schema.name, + statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name), + ).result() - table_full_name = "%s.%s.%s" % (created_catalog.name, created_schema.name, table_name) + table_full_name = "%s.%s.%s" % ( + created_catalog.name, + created_schema.name, + table_name, + ) created_table = w.tables.get(full_name=table_full_name) - grants = w.grants.get_effective(securable_type=catalog.SecurableType.TABLE, full_name=created_table.full_name) + grants = w.grants.get_effective( + securable_type=catalog.SecurableType.TABLE, + full_name=created_table.full_name, + ) # cleanup w.schemas.delete(full_name=created_schema.full_name) @@ -52,16 +61,16 @@ w.tables.delete(full_name=table_full_name) Get permissions. - + Gets the permissions for a securable. - + :param securable_type: :class:`SecurableType` Type of securable. :param full_name: str Full name of securable. :param principal: str (optional) If provided, only the permissions for the specified principal (user or group) are returned. - + :returns: :class:`PermissionsList` @@ -80,22 +89,31 @@ w = WorkspaceClient() - table_name = f'sdk-{time.time_ns()}' + table_name = f"sdk-{time.time_ns()}" - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - _ = w.statement_execution.execute(warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], - catalog=created_catalog.name, - schema=created_schema.name, - statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name)).result() + _ = w.statement_execution.execute( + warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], + catalog=created_catalog.name, + schema=created_schema.name, + statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name), + ).result() - table_full_name = "%s.%s.%s" % (created_catalog.name, created_schema.name, table_name) + table_full_name = "%s.%s.%s" % ( + created_catalog.name, + created_schema.name, + table_name, + ) created_table = w.tables.get(full_name=table_full_name) - grants = w.grants.get_effective(securable_type=catalog.SecurableType.TABLE, full_name=created_table.full_name) + grants = w.grants.get_effective( + securable_type=catalog.SecurableType.TABLE, + full_name=created_table.full_name, + ) # cleanup w.schemas.delete(full_name=created_schema.full_name) @@ -103,9 +121,9 @@ w.tables.delete(full_name=table_full_name) Get effective permissions. - + Gets the effective permissions for a securable. - + :param securable_type: :class:`SecurableType` Type of securable. :param full_name: str @@ -113,7 +131,7 @@ :param principal: str (optional) If provided, only the effective permissions for the specified principal (user or group) are returned. - + :returns: :class:`EffectivePermissionsList` @@ -132,29 +150,39 @@ w = WorkspaceClient() - table_name = f'sdk-{time.time_ns()}' + table_name = f"sdk-{time.time_ns()}" - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - _ = w.statement_execution.execute(warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], - catalog=created_catalog.name, - schema=created_schema.name, - statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name)).result() + _ = w.statement_execution.execute( + warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], + catalog=created_catalog.name, + schema=created_schema.name, + statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name), + ).result() - table_full_name = "%s.%s.%s" % (created_catalog.name, created_schema.name, table_name) + table_full_name = "%s.%s.%s" % ( + created_catalog.name, + created_schema.name, + table_name, + ) account_level_group_name = os.environ["TEST_DATA_ENG_GROUP"] created_table = w.tables.get(full_name=table_full_name) - x = w.grants.update(full_name=created_table.full_name, - securable_type=catalog.SecurableType.TABLE, - changes=[ - catalog.PermissionsChange(add=[catalog.Privilege.MODIFY, catalog.Privilege.SELECT], - principal=account_level_group_name) - ]) + x = w.grants.update( + full_name=created_table.full_name, + securable_type=catalog.SecurableType.TABLE, + changes=[ + catalog.PermissionsChange( + add=[catalog.Privilege.MODIFY, catalog.Privilege.SELECT], + principal=account_level_group_name, + ) + ], + ) # cleanup w.schemas.delete(full_name=created_schema.full_name) @@ -162,15 +190,15 @@ w.tables.delete(full_name=table_full_name) Update permissions. - + Updates the permissions for a securable. - + :param securable_type: :class:`SecurableType` Type of securable. :param full_name: str Full name of securable. :param changes: List[:class:`PermissionsChange`] (optional) Array of permissions change objects. - + :returns: :class:`PermissionsList` \ No newline at end of file diff --git a/docs/workspace/catalog/metastores.rst b/docs/workspace/catalog/metastores.rst index 01a936e0b..52c36437e 100644 --- a/docs/workspace/catalog/metastores.rst +++ b/docs/workspace/catalog/metastores.rst @@ -8,10 +8,10 @@ views) and the permissions that govern access to them. Databricks account admins can create metastores and assign them to Databricks workspaces to control which workloads use each metastore. For a workspace to use Unity Catalog, it must have a Unity Catalog metastore attached. - + Each metastore is configured with a root storage location in a cloud storage account. This storage location is used for metadata and managed tables data. - + NOTE: This metastore is distinct from the metastore included in Databricks workspaces created before Unity Catalog was released. If your workspace includes a legacy Hive metastore, the data in that metastore is available in a catalog named hive_metastore. @@ -32,9 +32,10 @@ workspace_id = os.environ["DUMMY_WORKSPACE_ID"] - created = w.metastores.create(name=f'sdk-{time.time_ns()}', - storage_root="s3://%s/%s" % - (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.metastores.create( + name=f"sdk-{time.time_ns()}", + storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) w.metastores.assign(metastore_id=created.metastore_id, workspace_id=workspace_id) @@ -42,11 +43,11 @@ w.metastores.delete(id=created.metastore_id, force=True) Create an assignment. - + Creates a new metastore assignment. If an assignment for the same __workspace_id__ exists, it will be overwritten by the new __metastore_id__ and __default_catalog_name__. The caller must be an account admin. - + :param workspace_id: int A workspace ID. :param metastore_id: str @@ -54,8 +55,8 @@ :param default_catalog_name: str The name of the default catalog in the metastore. This field is depracted. Please use "Default Namespace API" to configure the default catalog for a Databricks workspace. - - + + .. py:method:: create(name: str [, region: Optional[str], storage_root: Optional[str]]) -> MetastoreInfo @@ -72,20 +73,21 @@ w = WorkspaceClient() - created = w.metastores.create(name=f'sdk-{time.time_ns()}', - storage_root="s3://%s/%s" % - (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.metastores.create( + name=f"sdk-{time.time_ns()}", + storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) # cleanup w.metastores.delete(id=created.metastore_id, force=True) Create a metastore. - + Creates a new metastore based on a provided name and optional storage root path. By default (if the __owner__ field is not set), the owner of the new metastore is the user calling the __createMetastore__ API. If the __owner__ field is set to the empty string (**""**), the ownership is assigned to the System User instead. - + :param name: str The user-specified name of the metastore. :param region: str (optional) @@ -94,7 +96,7 @@ the region of the workspace receiving the request will be used. :param storage_root: str (optional) The storage root URL for metastore - + :returns: :class:`MetastoreInfo` @@ -112,24 +114,24 @@ current_metastore = w.metastores.current() Get metastore assignment for workspace. - + Gets the metastore assignment for the workspace being accessed. - + :returns: :class:`MetastoreAssignment` .. py:method:: delete(id: str [, force: Optional[bool]]) Delete a metastore. - + Deletes a metastore. The caller must be a metastore admin. - + :param id: str Unique ID of the metastore. :param force: bool (optional) Force deletion even if the metastore is not empty. Default is false. - - + + .. py:method:: get(id: str) -> MetastoreInfo @@ -146,9 +148,10 @@ w = WorkspaceClient() - created = w.metastores.create(name=f'sdk-{time.time_ns()}', - storage_root="s3://%s/%s" % - (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.metastores.create( + name=f"sdk-{time.time_ns()}", + storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) _ = w.metastores.get(id=created.metastore_id) @@ -156,13 +159,13 @@ w.metastores.delete(id=created.metastore_id, force=True) Get a metastore. - + Gets a metastore that matches the supplied ID. The caller must be a metastore admin to retrieve this info. - + :param id: str Unique ID of the metastore. - + :returns: :class:`MetastoreInfo` @@ -180,10 +183,10 @@ all = w.metastores.list() List metastores. - + Gets an array of the available metastores (as __MetastoreInfo__ objects). The caller must be an admin to retrieve this info. There is no guarantee of a specific ordering of the elements in the array. - + :returns: Iterator over :class:`MetastoreInfo` @@ -201,10 +204,10 @@ summary = w.metastores.summary() Get a metastore summary. - + Gets information about a metastore. This summary includes the storage credential, the cloud vendor, the cloud region, and the global metastore ID. - + :returns: :class:`GetMetastoreSummaryResponse` @@ -224,9 +227,10 @@ workspace_id = os.environ["DUMMY_WORKSPACE_ID"] - created = w.metastores.create(name=f'sdk-{time.time_ns()}', - storage_root="s3://%s/%s" % - (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.metastores.create( + name=f"sdk-{time.time_ns()}", + storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) w.metastores.unassign(metastore_id=created.metastore_id, workspace_id=workspace_id) @@ -234,15 +238,15 @@ w.metastores.delete(id=created.metastore_id, force=True) Delete an assignment. - + Deletes a metastore assignment. The caller must be an account administrator. - + :param workspace_id: int A workspace ID. :param metastore_id: str Query for the ID of the metastore to delete. - - + + .. py:method:: update(id: str [, delta_sharing_organization_name: Optional[str], delta_sharing_recipient_token_lifetime_in_seconds: Optional[int], delta_sharing_scope: Optional[UpdateMetastoreDeltaSharingScope], new_name: Optional[str], owner: Optional[str], privilege_model_version: Optional[str], storage_root_credential_id: Optional[str]]) -> MetastoreInfo @@ -259,20 +263,21 @@ w = WorkspaceClient() - created = w.metastores.create(name=f'sdk-{time.time_ns()}', - storage_root="s3://%s/%s" % - (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}')) + created = w.metastores.create( + name=f"sdk-{time.time_ns()}", + storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"), + ) - _ = w.metastores.update(id=created.metastore_id, new_name=f'sdk-{time.time_ns()}') + _ = w.metastores.update(id=created.metastore_id, new_name=f"sdk-{time.time_ns()}") # cleanup w.metastores.delete(id=created.metastore_id, force=True) Update a metastore. - + Updates information for a specific metastore. The caller must be a metastore admin. If the __owner__ field is set to the empty string (**""**), the ownership is updated to the System User. - + :param id: str Unique ID of the metastore. :param delta_sharing_organization_name: str (optional) @@ -290,19 +295,19 @@ Privilege model version of the metastore, of the form `major.minor` (e.g., `1.0`). :param storage_root_credential_id: str (optional) UUID of storage credential to access the metastore storage_root. - + :returns: :class:`MetastoreInfo` .. py:method:: update_assignment(workspace_id: int [, default_catalog_name: Optional[str], metastore_id: Optional[str]]) Update an assignment. - + Updates a metastore assignment. This operation can be used to update __metastore_id__ or __default_catalog_name__ for a specified Workspace, if the Workspace is already assigned a metastore. The caller must be an account admin to update __metastore_id__; otherwise, the caller can be a Workspace admin. - + :param workspace_id: int A workspace ID. :param default_catalog_name: str (optional) @@ -310,6 +315,6 @@ Namespace API" to configure the default catalog for a Databricks workspace. :param metastore_id: str (optional) The unique ID of the metastore. - - + + \ No newline at end of file diff --git a/docs/workspace/catalog/model_versions.rst b/docs/workspace/catalog/model_versions.rst index bae6f25f8..99b62ae03 100644 --- a/docs/workspace/catalog/model_versions.rst +++ b/docs/workspace/catalog/model_versions.rst @@ -7,39 +7,39 @@ Databricks provides a hosted version of MLflow Model Registry in Unity Catalog. Models in Unity Catalog provide centralized access control, auditing, lineage, and discovery of ML models across Databricks workspaces. - + This API reference documents the REST endpoints for managing model versions in Unity Catalog. For more details, see the [registered models API docs](/api/workspace/registeredmodels). .. py:method:: delete(full_name: str, version: int) Delete a Model Version. - + Deletes a model version from the specified registered model. Any aliases assigned to the model version will also be deleted. - + The caller must be a metastore admin or an owner of the parent registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the model version :param version: int The integer version number of the model version - - + + .. py:method:: get(full_name: str, version: int [, include_aliases: Optional[bool], include_browse: Optional[bool]]) -> ModelVersionInfo Get a Model Version. - + Get a model version. - + The caller must be a metastore admin or an owner of (or have the **EXECUTE** privilege on) the parent registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the model version :param version: int @@ -49,46 +49,46 @@ :param include_browse: bool (optional) Whether to include model versions in the response for which the principal can only access selective metadata for - + :returns: :class:`ModelVersionInfo` .. py:method:: get_by_alias(full_name: str, alias: str [, include_aliases: Optional[bool]]) -> ModelVersionInfo Get Model Version By Alias. - + Get a model version by alias. - + The caller must be a metastore admin or an owner of (or have the **EXECUTE** privilege on) the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the registered model :param alias: str The name of the alias :param include_aliases: bool (optional) Whether to include aliases associated with the model version in the response - + :returns: :class:`ModelVersionInfo` .. py:method:: list(full_name: str [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ModelVersionInfo] List Model Versions. - + List model versions. You can list model versions under a particular schema, or list all model versions in the current metastore. - + The returned models are filtered based on the privileges of the calling user. For example, the metastore admin is able to list all the model versions. A regular user needs to be the owner or have the **EXECUTE** privilege on the parent registered model to recieve the model versions in the response. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + There is no guarantee of a specific ordering of the elements in the response. The elements in the response will not contain any aliases or tags. - + :param full_name: str The full three-level name of the registered model under which to list model versions :param include_browse: bool (optional) @@ -102,28 +102,28 @@ value less than 0, an invalid parameter error is returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ModelVersionInfo` .. py:method:: update(full_name: str, version: int [, comment: Optional[str]]) -> ModelVersionInfo Update a Model Version. - + Updates the specified model version. - + The caller must be a metastore admin or an owner of the parent registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + Currently only the comment of the model version can be updated. - + :param full_name: str The three-level (fully qualified) name of the model version :param version: int The integer version number of the model version :param comment: str (optional) The comment attached to the model version - + :returns: :class:`ModelVersionInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/online_tables.rst b/docs/workspace/catalog/online_tables.rst index d0119657f..ce6ba50c3 100644 --- a/docs/workspace/catalog/online_tables.rst +++ b/docs/workspace/catalog/online_tables.rst @@ -9,12 +9,12 @@ .. py:method:: create( [, table: Optional[OnlineTable]]) -> Wait[OnlineTable] Create an Online Table. - + Create a new Online Table. - + :param table: :class:`OnlineTable` (optional) Online Table information. - + :returns: Long-running operation waiter for :class:`OnlineTable`. See :method:wait_get_online_table_active for more details. @@ -26,26 +26,26 @@ .. py:method:: delete(name: str) Delete an Online Table. - + Delete an online table. Warning: This will delete all the data in the online table. If the source Delta table was deleted or modified since this Online Table was created, this will lose the data forever! - + :param name: str Full three-part (catalog, schema, table) name of the table. - - + + .. py:method:: get(name: str) -> OnlineTable Get an Online Table. - + Get information about an existing online table and its status. - + :param name: str Full three-part (catalog, schema, table) name of the table. - + :returns: :class:`OnlineTable` diff --git a/docs/workspace/catalog/quality_monitors.rst b/docs/workspace/catalog/quality_monitors.rst index 93f05b69a..255076aac 100644 --- a/docs/workspace/catalog/quality_monitors.rst +++ b/docs/workspace/catalog/quality_monitors.rst @@ -6,7 +6,7 @@ A monitor computes and monitors data or model quality metrics for a table over time. It generates metrics tables and a dashboard that you can use to monitor table health and set alerts. - + Most write operations require the user to be the owner of the table (or its parent schema or parent catalog). Viewing the dashboard, computed metrics, or monitor configuration only requires the user to have **SELECT** privileges on the table (along with **USE_SCHEMA** and **USE_CATALOG**). @@ -14,38 +14,38 @@ .. py:method:: cancel_refresh(table_name: str, refresh_id: str) Cancel refresh. - + Cancel an active monitor refresh for the given refresh ID. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table - + Additionally, the call must be made from the workspace where the monitor was created. - + :param table_name: str Full name of the table. :param refresh_id: str ID of the refresh. - - + + .. py:method:: create(table_name: str, assets_dir: str, output_schema_name: str [, baseline_table_name: Optional[str], custom_metrics: Optional[List[MonitorMetric]], data_classification_config: Optional[MonitorDataClassificationConfig], inference_log: Optional[MonitorInferenceLog], notifications: Optional[MonitorNotifications], schedule: Optional[MonitorCronSchedule], skip_builtin_dashboard: Optional[bool], slicing_exprs: Optional[List[str]], snapshot: Optional[MonitorSnapshot], time_series: Optional[MonitorTimeSeries], warehouse_id: Optional[str]]) -> MonitorInfo Create a table monitor. - + Creates a new monitor for the specified table. - + The caller must either: 1. be an owner of the table's parent catalog, have **USE_SCHEMA** on the table's parent schema, and have **SELECT** access on the table 2. have **USE_CATALOG** on the table's parent catalog, be an owner of the table's parent schema, and have **SELECT** access on the table. 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table. - + Workspace assets, such as the dashboard, will be created in the workspace where this call was made. - + :param table_name: str Full name of the table. :param assets_dir: str @@ -79,152 +79,152 @@ :param warehouse_id: str (optional) Optional argument to specify the warehouse for dashboard creation. If not specified, the first running warehouse will be used. - + :returns: :class:`MonitorInfo` .. py:method:: delete(table_name: str) Delete a table monitor. - + Deletes a monitor for the specified table. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table. - + Additionally, the call must be made from the workspace where the monitor was created. - + Note that the metric tables and dashboard will not be deleted as part of this call; those assets must be manually cleaned up (if desired). - + :param table_name: str Full name of the table. - - + + .. py:method:: get(table_name: str) -> MonitorInfo Get a table monitor. - + Gets a monitor for the specified table. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema. 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - **SELECT** privilege on the table. - + The returned information includes configuration values, as well as information on assets created by the monitor. Some information (e.g., dashboard) may be filtered out if the caller is in a different workspace than where the monitor was created. - + :param table_name: str Full name of the table. - + :returns: :class:`MonitorInfo` .. py:method:: get_refresh(table_name: str, refresh_id: str) -> MonitorRefreshInfo Get refresh. - + Gets info about a specific monitor refresh using the given refresh ID. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - **SELECT** privilege on the table. - + Additionally, the call must be made from the workspace where the monitor was created. - + :param table_name: str Full name of the table. :param refresh_id: str ID of the refresh. - + :returns: :class:`MonitorRefreshInfo` .. py:method:: list_refreshes(table_name: str) -> MonitorRefreshListResponse List refreshes. - + Gets an array containing the history of the most recent refreshes (up to 25) for this table. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - **SELECT** privilege on the table. - + Additionally, the call must be made from the workspace where the monitor was created. - + :param table_name: str Full name of the table. - + :returns: :class:`MonitorRefreshListResponse` .. py:method:: regenerate_dashboard(table_name: str [, warehouse_id: Optional[str]]) -> RegenerateDashboardResponse Regenerate a monitoring dashboard. - + Regenerates the monitoring dashboard for the specified table. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table - + The call must be made from the workspace where the monitor was created. The dashboard will be regenerated in the assets directory that was specified when the monitor was created. - + :param table_name: str Full name of the table. :param warehouse_id: str (optional) Optional argument to specify the warehouse for dashboard regeneration. If not specified, the first running warehouse will be used. - + :returns: :class:`RegenerateDashboardResponse` .. py:method:: run_refresh(table_name: str) -> MonitorRefreshInfo Queue a metric refresh for a monitor. - + Queues a metric refresh on the monitor for the specified table. The refresh will execute in the background. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table - + Additionally, the call must be made from the workspace where the monitor was created. - + :param table_name: str Full name of the table. - + :returns: :class:`MonitorRefreshInfo` .. py:method:: update(table_name: str, output_schema_name: str [, baseline_table_name: Optional[str], custom_metrics: Optional[List[MonitorMetric]], dashboard_id: Optional[str], data_classification_config: Optional[MonitorDataClassificationConfig], inference_log: Optional[MonitorInferenceLog], notifications: Optional[MonitorNotifications], schedule: Optional[MonitorCronSchedule], slicing_exprs: Optional[List[str]], snapshot: Optional[MonitorSnapshot], time_series: Optional[MonitorTimeSeries]]) -> MonitorInfo Update a table monitor. - + Updates a monitor for the specified table. - + The caller must either: 1. be an owner of the table's parent catalog 2. have **USE_CATALOG** on the table's parent catalog and be an owner of the table's parent schema 3. have the following permissions: - **USE_CATALOG** on the table's parent catalog - **USE_SCHEMA** on the table's parent schema - be an owner of the table. - + Additionally, the call must be made from the workspace where the monitor was created, and the caller must be the original creator of the monitor. - + Certain configuration fields, such as output asset identifiers, cannot be updated. - + :param table_name: str Full name of the table. :param output_schema_name: str @@ -254,6 +254,6 @@ Configuration for monitoring snapshot tables. :param time_series: :class:`MonitorTimeSeries` (optional) Configuration for monitoring time series tables. - + :returns: :class:`MonitorInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/registered_models.rst b/docs/workspace/catalog/registered_models.rst index b05a702b5..3f7ced621 100644 --- a/docs/workspace/catalog/registered_models.rst +++ b/docs/workspace/catalog/registered_models.rst @@ -7,17 +7,17 @@ Databricks provides a hosted version of MLflow Model Registry in Unity Catalog. Models in Unity Catalog provide centralized access control, auditing, lineage, and discovery of ML models across Databricks workspaces. - + An MLflow registered model resides in the third layer of Unity Catalog’s three-level namespace. Registered models contain model versions, which correspond to actual ML models (MLflow models). Creating new model versions currently requires use of the MLflow Python client. Once model versions are created, you can load them for batch inference using MLflow Python client APIs, or deploy them for real-time serving using Databricks Model Serving. - + All operations on registered models and model versions require USE_CATALOG permissions on the enclosing catalog and USE_SCHEMA permissions on the enclosing schema. In addition, the following additional privileges are required for various operations: - + * To create a registered model, users must additionally have the CREATE_MODEL permission on the target schema. * To view registered model or model version metadata, model version data files, or invoke a model version, users must additionally have the EXECUTE permission on the registered model * To update @@ -25,24 +25,24 @@ registered model * To update other registered model or model version metadata (comments, aliases) create a new model version, or update permissions on the registered model, users must be owners of the registered model. - + Note: The securable type for models is "FUNCTION". When using REST APIs (e.g. tagging, grants) that specify a securable type, use "FUNCTION" as the securable type. .. py:method:: create(catalog_name: str, schema_name: str, name: str [, comment: Optional[str], storage_location: Optional[str]]) -> RegisteredModelInfo Create a Registered Model. - + Creates a new registered model in Unity Catalog. - + File storage for model versions in the registered model will be located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore. - + For registered model creation to succeed, the user must satisfy the following conditions: - The caller must be a metastore admin, or be the owner of the parent catalog and schema, or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - The caller must have the **CREATE MODEL** or **CREATE FUNCTION** privilege on the parent schema. - + :param catalog_name: str The name of the catalog where the schema and the registered model reside :param schema_name: str @@ -53,54 +53,54 @@ The comment attached to the registered model :param storage_location: str (optional) The storage location on the cloud under which model version data files are stored - + :returns: :class:`RegisteredModelInfo` .. py:method:: delete(full_name: str) Delete a Registered Model. - + Deletes a registered model and all its model versions from the specified parent catalog and schema. - + The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the registered model - - + + .. py:method:: delete_alias(full_name: str, alias: str) Delete a Registered Model Alias. - + Deletes a registered model alias. - + The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the registered model :param alias: str The name of the alias - - + + .. py:method:: get(full_name: str [, include_aliases: Optional[bool], include_browse: Optional[bool]]) -> RegisteredModelInfo Get a Registered Model. - + Get a registered model. - + The caller must be a metastore admin or an owner of (or have the **EXECUTE** privilege on) the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str The three-level (fully qualified) name of the registered model :param include_aliases: bool (optional) @@ -108,25 +108,25 @@ :param include_browse: bool (optional) Whether to include registered models in the response for which the principal can only access selective metadata for - + :returns: :class:`RegisteredModelInfo` .. py:method:: list( [, catalog_name: Optional[str], include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str], schema_name: Optional[str]]) -> Iterator[RegisteredModelInfo] List Registered Models. - + List registered models. You can list registered models under a particular schema, or list all registered models in the current metastore. - + The returned models are filtered based on the privileges of the calling user. For example, the metastore admin is able to list all the registered models. A regular user needs to be the owner or have the **EXECUTE** privilege on the registered model to recieve the registered models in the response. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + There is no guarantee of a specific ordering of the elements in the response. - + :param catalog_name: str (optional) The identifier of the catalog under which to list registered models. If specified, schema_name must be specified. @@ -135,13 +135,13 @@ selective metadata for :param max_results: int (optional) Max number of registered models to return. - + If both catalog and schema are specified: - when max_results is not specified, the page length is set to a server configured value (10000, as of 4/2/2024). - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 4/2/2024); - when set to 0, the page length is set to a server configured value (10000, as of 4/2/2024); - when set to a value less than 0, an invalid parameter error is returned; - + If neither schema nor catalog is specified: - when max_results is not specified, the page length is set to a server configured value (100, as of 4/2/2024). - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (1000, as of 4/2/2024); - @@ -152,42 +152,42 @@ :param schema_name: str (optional) The identifier of the schema under which to list registered models. If specified, catalog_name must be specified. - + :returns: Iterator over :class:`RegisteredModelInfo` .. py:method:: set_alias(full_name: str, alias: str, version_num: int) -> RegisteredModelAlias Set a Registered Model Alias. - + Set an alias on the specified registered model. - + The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str Full name of the registered model :param alias: str The name of the alias :param version_num: int The version number of the model version to which the alias points - + :returns: :class:`RegisteredModelAlias` .. py:method:: update(full_name: str [, comment: Optional[str], new_name: Optional[str], owner: Optional[str]]) -> RegisteredModelInfo Update a Registered Model. - + Updates the specified registered model. - + The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + Currently only the name, the owner or the comment of the registered model can be updated. - + :param full_name: str The three-level (fully qualified) name of the registered model :param comment: str (optional) @@ -196,6 +196,6 @@ New name for the registered model. :param owner: str (optional) The identifier of the user who owns the registered model - + :returns: :class:`RegisteredModelInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/resource_quotas.rst b/docs/workspace/catalog/resource_quotas.rst index 3396011f0..c1e14687c 100644 --- a/docs/workspace/catalog/resource_quotas.rst +++ b/docs/workspace/catalog/resource_quotas.rst @@ -8,38 +8,39 @@ can be created. Quotas are expressed in terms of a resource type and a parent (for example, tables per metastore or schemas per catalog). The resource quota APIs enable you to monitor your current usage and limits. For more information on resource quotas see the [Unity Catalog documentation]. - + [Unity Catalog documentation]: https://docs.databricks.com/en/data-governance/unity-catalog/index.html#resource-quotas + .. py:method:: get_quota(parent_securable_type: str, parent_full_name: str, quota_name: str) -> GetQuotaResponse Get information for a single resource quota. - + The GetQuota API returns usage information for a single resource quota, defined as a child-parent pair. This API also refreshes the quota count if it is out of date. Refreshes are triggered asynchronously. The updated count might not be returned in the first call. - + :param parent_securable_type: str Securable type of the quota parent. :param parent_full_name: str Full name of the parent resource. Provide the metastore ID if the parent is a metastore. :param quota_name: str Name of the quota. Follows the pattern of the quota type, with "-quota" added as a suffix. - + :returns: :class:`GetQuotaResponse` .. py:method:: list_quotas( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[QuotaInfo] List all resource quotas under a metastore. - + ListQuotas returns all quota values under the metastore. There are no SLAs on the freshness of the counts returned. This API does not trigger a refresh of quota counts. - + :param max_results: int (optional) The number of quotas to return. :param page_token: str (optional) Opaque token for the next page of results. - + :returns: Iterator over :class:`QuotaInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/schemas.rst b/docs/workspace/catalog/schemas.rst index feaf7c7a0..7c4a84e53 100644 --- a/docs/workspace/catalog/schemas.rst +++ b/docs/workspace/catalog/schemas.rst @@ -22,19 +22,19 @@ w = WorkspaceClient() - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) # cleanup w.catalogs.delete(name=created_catalog.name, force=True) w.schemas.delete(full_name=created_schema.full_name) Create a schema. - + Creates a new schema for catalog in the Metatastore. The caller must be a metastore admin, or have the **CREATE_SCHEMA** privilege in the parent catalog. - + :param name: str Name of schema, relative to parent catalog. :param catalog_name: str @@ -45,23 +45,23 @@ A map of key-value properties attached to the securable. :param storage_root: str (optional) Storage root URL for managed tables within schema. - + :returns: :class:`SchemaInfo` .. py:method:: delete(full_name: str [, force: Optional[bool]]) Delete a schema. - + Deletes the specified schema from the parent catalog. The caller must be the owner of the schema or an owner of the parent catalog. - + :param full_name: str Full name of the schema. :param force: bool (optional) Force deletion even if the schema is not empty. - - + + .. py:method:: get(full_name: str [, include_browse: Optional[bool]]) -> SchemaInfo @@ -77,9 +77,9 @@ w = WorkspaceClient() - new_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + new_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=new_catalog.name) + created = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=new_catalog.name) _ = w.schemas.get(full_name=created.full_name) @@ -88,16 +88,16 @@ w.schemas.delete(full_name=created.full_name) Get a schema. - + Gets the specified schema within the metastore. The caller must be a metastore admin, the owner of the schema, or a user that has the **USE_SCHEMA** privilege on the schema. - + :param full_name: str Full name of the schema. :param include_browse: bool (optional) Whether to include schemas in the response for which the principal can only access selective metadata for - + :returns: :class:`SchemaInfo` @@ -114,7 +114,7 @@ w = WorkspaceClient() - new_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + new_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") all = w.schemas.list(catalog_name=new_catalog.name) @@ -122,12 +122,12 @@ w.catalogs.delete(name=new_catalog.name, force=True) List schemas. - + Gets an array of schemas for a catalog in the metastore. If the caller is the metastore admin or the owner of the parent catalog, all schemas for the catalog will be retrieved. Otherwise, only schemas owned by the caller (or for which the caller has the **USE_SCHEMA** privilege) will be retrieved. There is no guarantee of a specific ordering of the elements in the array. - + :param catalog_name: str Parent catalog for schemas of interest. :param include_browse: bool (optional) @@ -140,7 +140,7 @@ (recommended); - when set to a value less than 0, an invalid parameter error is returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`SchemaInfo` @@ -157,23 +157,23 @@ w = WorkspaceClient() - new_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + new_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=new_catalog.name) + created = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=new_catalog.name) - _ = w.schemas.update(full_name=created.full_name, comment=f'sdk-{time.time_ns()}') + _ = w.schemas.update(full_name=created.full_name, comment=f"sdk-{time.time_ns()}") # cleanup w.catalogs.delete(name=new_catalog.name, force=True) w.schemas.delete(full_name=created.full_name) Update a schema. - + Updates a schema for a catalog. The caller must be the owner of the schema or a metastore admin. If the caller is a metastore admin, only the __owner__ field can be changed in the update. If the __name__ field must be updated, the caller must be a metastore admin or have the **CREATE_SCHEMA** privilege on the parent catalog. - + :param full_name: str Full name of the schema. :param comment: str (optional) @@ -186,6 +186,6 @@ Username of current owner of schema. :param properties: Dict[str,str] (optional) A map of key-value properties attached to the securable. - + :returns: :class:`SchemaInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/storage_credentials.rst b/docs/workspace/catalog/storage_credentials.rst index cac70a944..ea2aece71 100644 --- a/docs/workspace/catalog/storage_credentials.rst +++ b/docs/workspace/catalog/storage_credentials.rst @@ -9,9 +9,9 @@ control which users and groups can access the credential. If a user does not have access to a storage credential in Unity Catalog, the request fails and Unity Catalog does not attempt to authenticate to your cloud tenant on the user’s behalf. - + Databricks recommends using external locations rather than using storage credentials directly. - + To create storage credentials, you must be a Databricks account admin. The account admin who creates the storage credential can delegate ownership to another user or group to manage permissions on it. @@ -31,16 +31,17 @@ w = WorkspaceClient() created = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + name=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) # cleanup w.storage_credentials.delete(delete=created.name) Create a storage credential. - + Creates a new storage credential. - + :param name: str The credential name. The name must be unique within the metastore. :param aws_iam_role: :class:`AwsIamRoleRequest` (optional) @@ -59,23 +60,23 @@ Whether the storage credential is only usable for read operations. :param skip_validation: bool (optional) Supplying true to this argument skips validation of the created credential. - + :returns: :class:`StorageCredentialInfo` .. py:method:: delete(name: str [, force: Optional[bool]]) Delete a credential. - + Deletes a storage credential from the metastore. The caller must be an owner of the storage credential. - + :param name: str Name of the storage credential. :param force: bool (optional) Force deletion even if there are dependent external locations or external tables. - - + + .. py:method:: get(name: str) -> StorageCredentialInfo @@ -94,8 +95,9 @@ w = WorkspaceClient() created = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + name=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) by_name = w.storage_credentials.get(name=created.name) @@ -103,13 +105,13 @@ w.storage_credentials.delete(name=created.name) Get a credential. - + Gets a storage credential from the metastore. The caller must be a metastore admin, the owner of the storage credential, or have some permission on the storage credential. - + :param name: str Name of the storage credential. - + :returns: :class:`StorageCredentialInfo` @@ -127,12 +129,12 @@ all = w.storage_credentials.list() List credentials. - + Gets an array of storage credentials (as __StorageCredentialInfo__ objects). The array is limited to only those storage credentials the caller has permission to access. If the caller is a metastore admin, retrieval of credentials is unrestricted. There is no guarantee of a specific ordering of the elements in the array. - + :param max_results: int (optional) Maximum number of storage credentials to return. If not set, all the storage credentials are returned (not recommended). - when set to a value greater than 0, the page length is the minimum of @@ -141,7 +143,7 @@ returned; :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`StorageCredentialInfo` @@ -161,21 +163,23 @@ w = WorkspaceClient() created = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + name=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) _ = w.storage_credentials.update( name=created.name, - comment=f'sdk-{time.time_ns()}', - aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"])) + comment=f"sdk-{time.time_ns()}", + aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), + ) # cleanup w.storage_credentials.delete(delete=created.name) Update a credential. - + Updates a storage credential on the metastore. - + :param name: str Name of the storage credential. :param aws_iam_role: :class:`AwsIamRoleRequest` (optional) @@ -201,24 +205,24 @@ Whether the storage credential is only usable for read operations. :param skip_validation: bool (optional) Supplying true to this argument skips validation of the updated credential. - + :returns: :class:`StorageCredentialInfo` .. py:method:: validate( [, aws_iam_role: Optional[AwsIamRoleRequest], azure_managed_identity: Optional[AzureManagedIdentityRequest], azure_service_principal: Optional[AzureServicePrincipal], cloudflare_api_token: Optional[CloudflareApiToken], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccountRequest], external_location_name: Optional[str], read_only: Optional[bool], storage_credential_name: Optional[str], url: Optional[str]]) -> ValidateStorageCredentialResponse Validate a storage credential. - + Validates a storage credential. At least one of __external_location_name__ and __url__ need to be provided. If only one of them is provided, it will be used for validation. And if both are provided, the __url__ will be used for validation, and __external_location_name__ will be ignored when checking overlapping urls. - + Either the __storage_credential_name__ or the cloud-specific credential must be provided. - + The caller must be a metastore admin or the storage credential owner or have the **CREATE_EXTERNAL_LOCATION** privilege on the metastore and the storage credential. - + :param aws_iam_role: :class:`AwsIamRoleRequest` (optional) The AWS IAM role configuration. :param azure_managed_identity: :class:`AzureManagedIdentityRequest` (optional) @@ -237,6 +241,6 @@ The name of the storage credential to validate. :param url: str (optional) The external location url to validate. - + :returns: :class:`ValidateStorageCredentialResponse` \ No newline at end of file diff --git a/docs/workspace/catalog/system_schemas.rst b/docs/workspace/catalog/system_schemas.rst index 2028a3623..4ef2294cc 100644 --- a/docs/workspace/catalog/system_schemas.rst +++ b/docs/workspace/catalog/system_schemas.rst @@ -10,40 +10,40 @@ .. py:method:: disable(metastore_id: str, schema_name: str) Disable a system schema. - + Disables the system schema and removes it from the system catalog. The caller must be an account admin or a metastore admin. - + :param metastore_id: str The metastore ID under which the system schema lives. :param schema_name: str Full name of the system schema. - - + + .. py:method:: enable(metastore_id: str, schema_name: str) Enable a system schema. - + Enables the system schema and adds it to the system catalog. The caller must be an account admin or a metastore admin. - + :param metastore_id: str The metastore ID under which the system schema lives. :param schema_name: str Full name of the system schema. - - + + .. py:method:: list(metastore_id: str [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[SystemSchemaInfo] List system schemas. - + Gets an array of system schemas for a metastore. The caller must be an account admin or a metastore admin. - + :param metastore_id: str The ID for the metastore in which the system schema resides. :param max_results: int (optional) @@ -53,6 +53,6 @@ is returned; - If not set, all the schemas are returned (not recommended). :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`SystemSchemaInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/table_constraints.rst b/docs/workspace/catalog/table_constraints.rst index dd46c42f3..6b974c463 100644 --- a/docs/workspace/catalog/table_constraints.rst +++ b/docs/workspace/catalog/table_constraints.rst @@ -5,51 +5,51 @@ .. py:class:: TableConstraintsAPI Primary key and foreign key constraints encode relationships between fields in tables. - + Primary and foreign keys are informational only and are not enforced. Foreign keys must reference a primary key in another table. This primary key is the parent constraint of the foreign key and the table this primary key is on is the parent table of the foreign key. Similarly, the foreign key is the child constraint of its referenced primary key; the table of the foreign key is the child table of the primary key. - + You can declare primary keys and foreign keys as part of the table specification during table creation. You can also add or drop constraints on existing tables. .. py:method:: create(full_name_arg: str, constraint: TableConstraint) -> TableConstraint Create a table constraint. - + Creates a new table constraint. - + For the table constraint creation to succeed, the user must satisfy both of these conditions: - the user must have the **USE_CATALOG** privilege on the table's parent catalog, the **USE_SCHEMA** privilege on the table's parent schema, and be the owner of the table. - if the new constraint is a __ForeignKeyConstraint__, the user must have the **USE_CATALOG** privilege on the referenced parent table's catalog, the **USE_SCHEMA** privilege on the referenced parent table's schema, and be the owner of the referenced parent table. - + :param full_name_arg: str The full name of the table referenced by the constraint. :param constraint: :class:`TableConstraint` A table constraint, as defined by *one* of the following fields being set: __primary_key_constraint__, __foreign_key_constraint__, __named_table_constraint__. - + :returns: :class:`TableConstraint` .. py:method:: delete(full_name: str, constraint_name: str, cascade: bool) Delete a table constraint. - + Deletes a table constraint. - + For the table constraint deletion to succeed, the user must satisfy both of these conditions: - the user must have the **USE_CATALOG** privilege on the table's parent catalog, the **USE_SCHEMA** privilege on the table's parent schema, and be the owner of the table. - if __cascade__ argument is **true**, the user must have the following permissions on all of the child tables: the **USE_CATALOG** privilege on the table's catalog, the **USE_SCHEMA** privilege on the table's schema, and be the owner of the table. - + :param full_name: str Full name of the table referenced by the constraint. :param constraint_name: str @@ -57,6 +57,6 @@ :param cascade: bool If true, try deleting all child constraints of the current constraint. If false, reject this operation if the current constraint has any child constraints. - - + + \ No newline at end of file diff --git a/docs/workspace/catalog/tables.rst b/docs/workspace/catalog/tables.rst index 15cfb1cac..4bbd3faad 100644 --- a/docs/workspace/catalog/tables.rst +++ b/docs/workspace/catalog/tables.rst @@ -9,39 +9,39 @@ have the USE_CATALOG permission on its parent catalog. To query a table, users must have the SELECT permission on the table, and they must have the USE_CATALOG permission on its parent catalog and the USE_SCHEMA permission on its parent schema. - + A table can be managed or external. From an API perspective, a __VIEW__ is a particular kind of table (rather than a managed or external table). .. py:method:: delete(full_name: str) Delete a table. - + Deletes a table from the specified parent catalog and schema. The caller must be the owner of the parent catalog, have the **USE_CATALOG** privilege on the parent catalog and be the owner of the parent schema, or be the owner of the table and have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str Full name of the table. - - + + .. py:method:: exists(full_name: str) -> TableExistsResponse Get boolean reflecting if table exists. - + Gets if a table exists in the metastore for a specific catalog and schema. The caller must satisfy one of the following requirements: * Be a metastore admin * Be the owner of the parent catalog * Be the owner of the parent schema and have the USE_CATALOG privilege on the parent catalog * Have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema, and either be the table owner or have the SELECT privilege on the table. * Have BROWSE privilege on the parent catalog * Have BROWSE privilege on the parent schema. - + :param full_name: str Full name of the table. - + :returns: :class:`TableExistsResponse` @@ -59,18 +59,24 @@ w = WorkspaceClient() - table_name = f'sdk-{time.time_ns()}' + table_name = f"sdk-{time.time_ns()}" - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - _ = w.statement_execution.execute(warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], - catalog=created_catalog.name, - schema=created_schema.name, - statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name)).result() + _ = w.statement_execution.execute( + warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], + catalog=created_catalog.name, + schema=created_schema.name, + statement="CREATE TABLE %s AS SELECT 2+2 as four" % (table_name), + ).result() - table_full_name = "%s.%s.%s" % (created_catalog.name, created_schema.name, table_name) + table_full_name = "%s.%s.%s" % ( + created_catalog.name, + created_schema.name, + table_name, + ) created_table = w.tables.get(full_name=table_full_name) @@ -80,13 +86,13 @@ w.tables.delete(full_name=table_full_name) Get a table. - + Gets a table from the metastore for a specific catalog and schema. The caller must satisfy one of the following requirements: * Be a metastore admin * Be the owner of the parent catalog * Be the owner of the parent schema and have the USE_CATALOG privilege on the parent catalog * Have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema, and either be the table owner or have the SELECT privilege on the table. - + :param full_name: str Full name of the table. :param include_browse: bool (optional) @@ -96,7 +102,7 @@ Whether delta metadata should be included in the response. :param include_manifest_capabilities: bool (optional) Whether to include a manifest containing capabilities the table has. - + :returns: :class:`TableInfo` @@ -113,9 +119,9 @@ w = WorkspaceClient() - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) all_tables = w.tables.list(catalog_name=created_catalog.name, schema_name=created_schema.name) @@ -124,13 +130,13 @@ w.catalogs.delete(name=created_catalog.name, force=True) List tables. - + Gets an array of all tables for the current metastore under the parent catalog and schema. The caller must be a metastore admin or an owner of (or have the **SELECT** privilege on) the table. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. There is no guarantee of a specific ordering of the elements in the array. - + :param catalog_name: str Name of parent catalog for tables of interest. :param schema_name: str @@ -156,7 +162,7 @@ not. :param page_token: str (optional) Opaque token to send for the next page of results (pagination). - + :returns: Iterator over :class:`TableInfo` @@ -173,30 +179,29 @@ w = WorkspaceClient() - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - summaries = w.tables.list_summaries(catalog_name=created_catalog.name, - schema_name_pattern=created_schema.name) + summaries = w.tables.list_summaries(catalog_name=created_catalog.name, schema_name_pattern=created_schema.name) # cleanup w.schemas.delete(full_name=created_schema.full_name) w.catalogs.delete(name=created_catalog.name, force=True) List table summaries. - + Gets an array of summaries for tables for a schema and catalog within the metastore. The table summaries returned are either: - + * summaries for tables (within the current metastore and parent catalog and schema), when the user is a metastore admin, or: * summaries for tables and schemas (within the current metastore and parent catalog) for which the user has ownership or the **SELECT** privilege on the table and ownership or **USE_SCHEMA** privilege on the schema, provided that the user also has ownership or the **USE_CATALOG** privilege on the parent catalog. - + There is no guarantee of a specific ordering of the elements in the array. - + :param catalog_name: str Name of parent catalog for tables of interest. :param include_manifest_capabilities: bool (optional) @@ -213,22 +218,22 @@ A sql LIKE pattern (% and _) for schema names. All schemas will be returned if not set or empty. :param table_name_pattern: str (optional) A sql LIKE pattern (% and _) for table names. All tables will be returned if not set or empty. - + :returns: Iterator over :class:`TableSummary` .. py:method:: update(full_name: str [, owner: Optional[str]]) Update a table owner. - + Change the owner of the table. The caller must be the owner of the parent catalog, have the **USE_CATALOG** privilege on the parent catalog and be the owner of the parent schema, or be the owner of the table and have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param full_name: str Full name of the table. :param owner: str (optional) - - + + \ No newline at end of file diff --git a/docs/workspace/catalog/temporary_table_credentials.rst b/docs/workspace/catalog/temporary_table_credentials.rst index 1acd462b7..b6ebbe819 100644 --- a/docs/workspace/catalog/temporary_table_credentials.rst +++ b/docs/workspace/catalog/temporary_table_credentials.rst @@ -20,17 +20,17 @@ .. py:method:: generate_temporary_table_credentials( [, operation: Optional[TableOperation], table_id: Optional[str]]) -> GenerateTemporaryTableCredentialResponse Generate a temporary table credential. - + Get a short-lived credential for directly accessing the table data on cloud storage. The metastore must have external_access_enabled flag set to true (default false). The caller must have EXTERNAL_USE_SCHEMA privilege on the parent schema and this privilege can only be granted by catalog owners. - + :param operation: :class:`TableOperation` (optional) The operation performed against the table data, either READ or READ_WRITE. If READ_WRITE is specified, the credentials returned will have write permissions, otherwise, it will be read only. :param table_id: str (optional) UUID of the table to read or write. - + :returns: :class:`GenerateTemporaryTableCredentialResponse` \ No newline at end of file diff --git a/docs/workspace/catalog/volumes.rst b/docs/workspace/catalog/volumes.rst index 76e7c6c33..700659cc5 100644 --- a/docs/workspace/catalog/volumes.rst +++ b/docs/workspace/catalog/volumes.rst @@ -27,25 +27,29 @@ w = WorkspaceClient() storage_credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), - comment="created via SDK") + comment="created via SDK", + ) - external_location = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=storage_credential.name, - comment="created via SDK", - url="s3://" + os.environ["TEST_BUCKET"] + "/" + - f'sdk-{time.time_ns()}') + external_location = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=storage_credential.name, + comment="created via SDK", + url="s3://" + os.environ["TEST_BUCKET"] + "/" + f"sdk-{time.time_ns()}", + ) - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - created_volume = w.volumes.create(catalog_name=created_catalog.name, - schema_name=created_schema.name, - name=f'sdk-{time.time_ns()}', - storage_location=external_location.url, - volume_type=catalog.VolumeType.EXTERNAL) + created_volume = w.volumes.create( + catalog_name=created_catalog.name, + schema_name=created_schema.name, + name=f"sdk-{time.time_ns()}", + storage_location=external_location.url, + volume_type=catalog.VolumeType.EXTERNAL, + ) # cleanup w.storage_credentials.delete(name=storage_credential.name) @@ -55,23 +59,23 @@ w.volumes.delete(name=created_volume.full_name) Create a Volume. - + Creates a new volume. - + The user could create either an external volume or a managed volume. An external volume will be created in the specified external location, while a managed volume will be located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore. - + For the volume creation to succeed, the user must satisfy following conditions: - The caller must be a metastore admin, or be the owner of the parent catalog and schema, or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - The caller must have **CREATE VOLUME** privilege on the parent schema. - + For an external volume, following conditions also need to satisfy - The caller must have **CREATE EXTERNAL VOLUME** privilege on the external location. - There are no other tables, nor volumes existing in the specified storage location. - The specified storage location is not under the location of other tables, nor volumes, or catalogs or schemas. - + :param catalog_name: str The name of the catalog where the schema and the volume are :param schema_name: str @@ -83,24 +87,24 @@ The comment attached to the volume :param storage_location: str (optional) The storage location on the cloud - + :returns: :class:`VolumeInfo` .. py:method:: delete(name: str) Delete a Volume. - + Deletes a volume from the specified parent catalog and schema. - + The caller must be a metastore admin or an owner of the volume. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param name: str The three-level (fully qualified) name of the volume - - + + .. py:method:: list(catalog_name: str, schema_name: str [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[VolumeInfo] @@ -116,9 +120,9 @@ w = WorkspaceClient() - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) all_volumes = w.volumes.list(catalog_name=created_catalog.name, schema_name=created_schema.name) @@ -127,17 +131,17 @@ w.catalogs.delete(name=created_catalog.name, force=True) List Volumes. - + Gets an array of volumes for the current metastore under the parent catalog and schema. - + The returned volumes are filtered based on the privileges of the calling user. For example, the metastore admin is able to list all the volumes. A regular user needs to be the owner or have the **READ VOLUME** privilege on the volume to recieve the volumes in the response. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + There is no guarantee of a specific ordering of the elements in the array. - + :param catalog_name: str The identifier of the catalog :param schema_name: str @@ -147,20 +151,20 @@ metadata for :param max_results: int (optional) Maximum number of volumes to return (page length). - + If not set, the page length is set to a server configured value (10000, as of 1/29/2024). - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 1/29/2024); - when set to 0, the page length is set to a server configured value (10000, as of 1/29/2024) (recommended); - when set to a value less than 0, an invalid parameter error is returned; - + Note: this parameter controls only the maximum number of volumes to return. The actual number of volumes returned in a page may be smaller than this value, including 0, even if there are more pages. :param page_token: str (optional) Opaque token returned by a previous request. It must be included in the request to retrieve the next page of results (pagination). - + :returns: Iterator over :class:`VolumeInfo` @@ -180,25 +184,29 @@ w = WorkspaceClient() storage_credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), - comment="created via SDK") + comment="created via SDK", + ) - external_location = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=storage_credential.name, - comment="created via SDK", - url="s3://" + os.environ["TEST_BUCKET"] + "/" + - f'sdk-{time.time_ns()}') + external_location = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=storage_credential.name, + comment="created via SDK", + url="s3://" + os.environ["TEST_BUCKET"] + "/" + f"sdk-{time.time_ns()}", + ) - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - created_volume = w.volumes.create(catalog_name=created_catalog.name, - schema_name=created_schema.name, - name=f'sdk-{time.time_ns()}', - storage_location=external_location.url, - volume_type=catalog.VolumeType.EXTERNAL) + created_volume = w.volumes.create( + catalog_name=created_catalog.name, + schema_name=created_schema.name, + name=f"sdk-{time.time_ns()}", + storage_location=external_location.url, + volume_type=catalog.VolumeType.EXTERNAL, + ) loaded_volume = w.volumes.read(name=created_volume.full_name) @@ -210,19 +218,19 @@ w.volumes.delete(name=created_volume.full_name) Get a Volume. - + Gets a volume from the metastore for a specific catalog and schema. - + The caller must be a metastore admin or an owner of (or have the **READ VOLUME** privilege on) the volume. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + :param name: str The three-level (fully qualified) name of the volume :param include_browse: bool (optional) Whether to include volumes in the response for which the principal can only access selective metadata for - + :returns: :class:`VolumeInfo` @@ -242,25 +250,29 @@ w = WorkspaceClient() storage_credential = w.storage_credentials.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]), - comment="created via SDK") + comment="created via SDK", + ) - external_location = w.external_locations.create(name=f'sdk-{time.time_ns()}', - credential_name=storage_credential.name, - comment="created via SDK", - url="s3://" + os.environ["TEST_BUCKET"] + "/" + - f'sdk-{time.time_ns()}') + external_location = w.external_locations.create( + name=f"sdk-{time.time_ns()}", + credential_name=storage_credential.name, + comment="created via SDK", + url="s3://" + os.environ["TEST_BUCKET"] + "/" + f"sdk-{time.time_ns()}", + ) - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) - created_volume = w.volumes.create(catalog_name=created_catalog.name, - schema_name=created_schema.name, - name=f'sdk-{time.time_ns()}', - storage_location=external_location.url, - volume_type=catalog.VolumeType.EXTERNAL) + created_volume = w.volumes.create( + catalog_name=created_catalog.name, + schema_name=created_schema.name, + name=f"sdk-{time.time_ns()}", + storage_location=external_location.url, + volume_type=catalog.VolumeType.EXTERNAL, + ) loaded_volume = w.volumes.read(name=created_volume.full_name) @@ -274,15 +286,15 @@ w.volumes.delete(name=created_volume.full_name) Update a Volume. - + Updates the specified volume under the specified parent catalog and schema. - + The caller must be a metastore admin or an owner of the volume. For the latter case, the caller must also be the owner or have the **USE_CATALOG** privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema. - + Currently only the name, the owner or the comment of the volume could be updated. - + :param name: str The three-level (fully qualified) name of the volume :param comment: str (optional) @@ -291,6 +303,6 @@ New name for the volume. :param owner: str (optional) The identifier of the user who owns the volume - + :returns: :class:`VolumeInfo` \ No newline at end of file diff --git a/docs/workspace/catalog/workspace_bindings.rst b/docs/workspace/catalog/workspace_bindings.rst index 08a74b29e..e469def12 100644 --- a/docs/workspace/catalog/workspace_bindings.rst +++ b/docs/workspace/catalog/workspace_bindings.rst @@ -7,16 +7,16 @@ A securable in Databricks can be configured as __OPEN__ or __ISOLATED__. An __OPEN__ securable can be accessed from any workspace, while an __ISOLATED__ securable can only be accessed from a configured list of workspaces. This API allows you to configure (bind) securables to workspaces. - + NOTE: The __isolation_mode__ is configured for the securable itself (using its Update method) and the workspace bindings are only consulted when the securable's __isolation_mode__ is set to __ISOLATED__. - + A securable's workspace bindings can be configured by a metastore admin or the owner of the securable. - + The original path (/api/2.1/unity-catalog/workspace-bindings/catalogs/{name}) is deprecated. Please use the new path (/api/2.1/unity-catalog/bindings/{securable_type}/{securable_name}) which introduces the ability to bind a securable in READ_ONLY mode (catalogs only). - + Securable types that support binding: - catalog - storage_credential - external_location .. py:method:: get(name: str) -> CurrentWorkspaceBindings @@ -32,7 +32,7 @@ w = WorkspaceClient() - created = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created = w.catalogs.create(name=f"sdk-{time.time_ns()}") bindings = w.workspace_bindings.get(name=created.name) @@ -40,23 +40,23 @@ w.catalogs.delete(name=created.name, force=True) Get catalog workspace bindings. - + Gets workspace bindings of the catalog. The caller must be a metastore admin or an owner of the catalog. - + :param name: str The name of the catalog. - + :returns: :class:`CurrentWorkspaceBindings` .. py:method:: get_bindings(securable_type: GetBindingsSecurableType, securable_name: str [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[WorkspaceBinding] Get securable workspace bindings. - + Gets workspace bindings of the securable. The caller must be a metastore admin or an owner of the securable. - + :param securable_type: :class:`GetBindingsSecurableType` The type of the securable to bind to a workspace. :param securable_name: str @@ -68,7 +68,7 @@ error is returned; - If not set, all the workspace bindings are returned (not recommended). :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`WorkspaceBinding` @@ -88,7 +88,7 @@ this_workspace_id = os.environ["THIS_WORKSPACE_ID"] - created = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created = w.catalogs.create(name=f"sdk-{time.time_ns()}") _ = w.workspace_bindings.update(name=created.name, assign_workspaces=[this_workspace_id]) @@ -96,27 +96,27 @@ w.catalogs.delete(name=created.name, force=True) Update catalog workspace bindings. - + Updates workspace bindings of the catalog. The caller must be a metastore admin or an owner of the catalog. - + :param name: str The name of the catalog. :param assign_workspaces: List[int] (optional) A list of workspace IDs. :param unassign_workspaces: List[int] (optional) A list of workspace IDs. - + :returns: :class:`CurrentWorkspaceBindings` .. py:method:: update_bindings(securable_type: UpdateBindingsSecurableType, securable_name: str [, add: Optional[List[WorkspaceBinding]], remove: Optional[List[WorkspaceBinding]]]) -> WorkspaceBindingsResponse Update securable workspace bindings. - + Updates workspace bindings of the securable. The caller must be a metastore admin or an owner of the securable. - + :param securable_type: :class:`UpdateBindingsSecurableType` The type of the securable to bind to a workspace. :param securable_name: str @@ -125,6 +125,6 @@ List of workspace bindings :param remove: List[:class:`WorkspaceBinding`] (optional) List of workspace bindings - + :returns: :class:`WorkspaceBindingsResponse` \ No newline at end of file diff --git a/docs/workspace/cleanrooms/clean_room_assets.rst b/docs/workspace/cleanrooms/clean_room_assets.rst index fe282543a..1317fa002 100644 --- a/docs/workspace/cleanrooms/clean_room_assets.rst +++ b/docs/workspace/cleanrooms/clean_room_assets.rst @@ -10,71 +10,71 @@ .. py:method:: create(clean_room_name: str [, asset: Optional[CleanRoomAsset]]) -> CleanRoomAsset Create an asset. - + Create a clean room asset —share an asset like a notebook or table into the clean room. For each UC asset that is added through this method, the clean room owner must also have enough privilege on the asset to consume it. The privilege must be maintained indefinitely for the clean room to be able to access the asset. Typically, you should use a group as the clean room owner. - + :param clean_room_name: str Name of the clean room. :param asset: :class:`CleanRoomAsset` (optional) Metadata of the clean room asset - + :returns: :class:`CleanRoomAsset` .. py:method:: delete(clean_room_name: str, asset_type: CleanRoomAssetAssetType, asset_full_name: str) Delete an asset. - + Delete a clean room asset - unshare/remove the asset from the clean room - + :param clean_room_name: str Name of the clean room. :param asset_type: :class:`CleanRoomAssetAssetType` The type of the asset. :param asset_full_name: str The fully qualified name of the asset, it is same as the name field in CleanRoomAsset. - - + + .. py:method:: get(clean_room_name: str, asset_type: CleanRoomAssetAssetType, asset_full_name: str) -> CleanRoomAsset Get an asset. - + Get the details of a clean room asset by its type and full name. - + :param clean_room_name: str Name of the clean room. :param asset_type: :class:`CleanRoomAssetAssetType` The type of the asset. :param asset_full_name: str The fully qualified name of the asset, it is same as the name field in CleanRoomAsset. - + :returns: :class:`CleanRoomAsset` .. py:method:: list(clean_room_name: str [, page_token: Optional[str]]) -> Iterator[CleanRoomAsset] List assets. - + :param clean_room_name: str Name of the clean room. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`CleanRoomAsset` .. py:method:: update(clean_room_name: str, asset_type: CleanRoomAssetAssetType, name: str [, asset: Optional[CleanRoomAsset]]) -> CleanRoomAsset Update an asset. - + Update a clean room asset. For example, updating the content of a notebook; changing the shared partitions of a table; etc. - + :param clean_room_name: str Name of the clean room. :param asset_type: :class:`CleanRoomAssetAssetType` @@ -82,13 +82,13 @@ :param name: str A fully qualified name that uniquely identifies the asset within the clean room. This is also the name displayed in the clean room UI. - + For UC securable assets (tables, volumes, etc.), the format is *shared_catalog*.*shared_schema*.*asset_name* - + For notebooks, the name is the notebook file name. :param asset: :class:`CleanRoomAsset` (optional) Metadata of the clean room asset - + :returns: :class:`CleanRoomAsset` \ No newline at end of file diff --git a/docs/workspace/cleanrooms/clean_room_task_runs.rst b/docs/workspace/cleanrooms/clean_room_task_runs.rst index dcf59037c..b78bf2c2a 100644 --- a/docs/workspace/cleanrooms/clean_room_task_runs.rst +++ b/docs/workspace/cleanrooms/clean_room_task_runs.rst @@ -9,17 +9,17 @@ .. py:method:: list(clean_room_name: str [, notebook_name: Optional[str], page_size: Optional[int], page_token: Optional[str]]) -> Iterator[CleanRoomNotebookTaskRun] List notebook task runs. - + List all the historical notebook task runs in a clean room. - + :param clean_room_name: str Name of the clean room. :param notebook_name: str (optional) Notebook name :param page_size: int (optional) - The maximum number of task runs to return + The maximum number of task runs to return. Currently ignored - all runs will be returned. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`CleanRoomNotebookTaskRun` \ No newline at end of file diff --git a/docs/workspace/cleanrooms/clean_rooms.rst b/docs/workspace/cleanrooms/clean_rooms.rst index 8ef5d8827..1792cd48d 100644 --- a/docs/workspace/cleanrooms/clean_rooms.rst +++ b/docs/workspace/cleanrooms/clean_rooms.rst @@ -11,85 +11,85 @@ .. py:method:: create( [, clean_room: Optional[CleanRoom]]) -> CleanRoom Create a clean room. - + Create a new clean room with the specified collaborators. This method is asynchronous; the returned name field inside the clean_room field can be used to poll the clean room status, using the :method:cleanrooms/get method. When this method returns, the clean room will be in a PROVISIONING state, with only name, owner, comment, created_at and status populated. The clean room will be usable once it enters an ACTIVE state. - + The caller must be a metastore admin or have the **CREATE_CLEAN_ROOM** privilege on the metastore. - + :param clean_room: :class:`CleanRoom` (optional) - + :returns: :class:`CleanRoom` .. py:method:: create_output_catalog(clean_room_name: str [, output_catalog: Optional[CleanRoomOutputCatalog]]) -> CreateCleanRoomOutputCatalogResponse Create an output catalog. - + Create the output catalog of the clean room. - + :param clean_room_name: str Name of the clean room. :param output_catalog: :class:`CleanRoomOutputCatalog` (optional) - + :returns: :class:`CreateCleanRoomOutputCatalogResponse` .. py:method:: delete(name: str) Delete a clean room. - + Delete a clean room. After deletion, the clean room will be removed from the metastore. If the other collaborators have not deleted the clean room, they will still have the clean room in their metastore, but it will be in a DELETED state and no operations other than deletion can be performed on it. - + :param name: str Name of the clean room. - - + + .. py:method:: get(name: str) -> CleanRoom Get a clean room. - + Get the details of a clean room given its name. - + :param name: str - + :returns: :class:`CleanRoom` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[CleanRoom] List clean rooms. - + Get a list of all clean rooms of the metastore. Only clean rooms the caller has access to are returned. - + :param page_size: int (optional) Maximum number of clean rooms to return (i.e., the page length). Defaults to 100. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`CleanRoom` .. py:method:: update(name: str [, clean_room: Optional[CleanRoom]]) -> CleanRoom Update a clean room. - + Update a clean room. The caller must be the owner of the clean room, have **MODIFY_CLEAN_ROOM** privilege, or be metastore admin. - + When the caller is a metastore admin, only the __owner__ field can be updated. - + :param name: str Name of the clean room. :param clean_room: :class:`CleanRoom` (optional) - + :returns: :class:`CleanRoom` \ No newline at end of file diff --git a/docs/workspace/compute/cluster_policies.rst b/docs/workspace/compute/cluster_policies.rst index 65066964c..790315fd9 100644 --- a/docs/workspace/compute/cluster_policies.rst +++ b/docs/workspace/compute/cluster_policies.rst @@ -7,18 +7,18 @@ You can use cluster policies to control users' ability to configure clusters based on a set of rules. These rules specify which attributes or attribute values can be used during cluster creation. Cluster policies have ACLs that limit their use to specific users and groups. - + With cluster policies, you can: - Auto-install cluster libraries on the next restart by listing them in the policy's "libraries" field (Public Preview). - Limit users to creating clusters with the prescribed settings. - Simplify the user interface, enabling more users to create clusters, by fixing and hiding some fields. - Manage costs by setting limits on attributes that impact the hourly rate. - + Cluster policy permissions limit which policies a user can select in the Policy drop-down when the user creates a cluster: - A user who has unrestricted cluster create permission can select the Unrestricted policy and create fully-configurable clusters. - A user who has both unrestricted cluster create permission and access to cluster policies can select the Unrestricted policy and policies they have access to. - A user that has access to only cluster policies, can select the policies they have access to. - + If no policies exist in the workspace, the Policy drop-down doesn't appear. Only admin users can create, edit, and delete policies. Admin users also have access to all policies. @@ -35,25 +35,27 @@ w = WorkspaceClient() - created = w.cluster_policies.create(name=f'sdk-{time.time_ns()}', - definition="""{ + created = w.cluster_policies.create( + name=f"sdk-{time.time_ns()}", + definition="""{ "spark_conf.spark.databricks.delta.preview.enabled": { "type": "fixed", "value": true } } - """) + """, + ) # cleanup w.cluster_policies.delete(policy_id=created.policy_id) Create a new policy. - + Creates a new policy with prescribed settings. - + :param definition: str (optional) Policy definition document expressed in [Databricks Cluster Policy Definition Language]. - + [Databricks Cluster Policy Definition Language]: https://docs.databricks.com/administration-guide/clusters/policy-definition.html :param description: str (optional) Additional human-readable description of the cluster policy. @@ -69,31 +71,31 @@ :param policy_family_definition_overrides: str (optional) Policy definition JSON document expressed in [Databricks Policy Definition Language]. The JSON document must be passed as a string and cannot be embedded in the requests. - + You can use this to customize the policy definition inherited from the policy family. Policy rules specified here are merged into the inherited policy definition. - + [Databricks Policy Definition Language]: https://docs.databricks.com/administration-guide/clusters/policy-definition.html :param policy_family_id: str (optional) ID of the policy family. The cluster policy's policy definition inherits the policy family's policy definition. - + Cannot be used with `definition`. Use `policy_family_definition_overrides` instead to customize the policy definition. - + :returns: :class:`CreatePolicyResponse` .. py:method:: delete(policy_id: str) Delete a cluster policy. - + Delete a policy for a cluster. Clusters governed by this policy can still run, but cannot be edited. - + :param policy_id: str The ID of the policy to delete. - - + + .. py:method:: edit(policy_id: str [, definition: Optional[str], description: Optional[str], libraries: Optional[List[Library]], max_clusters_per_user: Optional[int], name: Optional[str], policy_family_definition_overrides: Optional[str], policy_family_id: Optional[str]]) @@ -109,40 +111,44 @@ w = WorkspaceClient() - created = w.cluster_policies.create(name=f'sdk-{time.time_ns()}', - definition="""{ + created = w.cluster_policies.create( + name=f"sdk-{time.time_ns()}", + definition="""{ "spark_conf.spark.databricks.delta.preview.enabled": { "type": "fixed", "value": true } } - """) + """, + ) policy = w.cluster_policies.get(policy_id=created.policy_id) - w.cluster_policies.edit(policy_id=policy.policy_id, - name=policy.name, - definition="""{ + w.cluster_policies.edit( + policy_id=policy.policy_id, + name=policy.name, + definition="""{ "spark_conf.spark.databricks.delta.preview.enabled": { "type": "fixed", "value": false } } - """) + """, + ) # cleanup w.cluster_policies.delete(policy_id=created.policy_id) Update a cluster policy. - + Update an existing policy for cluster. This operation may make some clusters governed by the previous policy invalid. - + :param policy_id: str The ID of the policy to update. :param definition: str (optional) Policy definition document expressed in [Databricks Cluster Policy Definition Language]. - + [Databricks Cluster Policy Definition Language]: https://docs.databricks.com/administration-guide/clusters/policy-definition.html :param description: str (optional) Additional human-readable description of the cluster policy. @@ -158,19 +164,19 @@ :param policy_family_definition_overrides: str (optional) Policy definition JSON document expressed in [Databricks Policy Definition Language]. The JSON document must be passed as a string and cannot be embedded in the requests. - + You can use this to customize the policy definition inherited from the policy family. Policy rules specified here are merged into the inherited policy definition. - + [Databricks Policy Definition Language]: https://docs.databricks.com/administration-guide/clusters/policy-definition.html :param policy_family_id: str (optional) ID of the policy family. The cluster policy's policy definition inherits the policy family's policy definition. - + Cannot be used with `definition`. Use `policy_family_definition_overrides` instead to customize the policy definition. - - + + .. py:method:: get(policy_id: str) -> Policy @@ -186,14 +192,16 @@ w = WorkspaceClient() - created = w.cluster_policies.create(name=f'sdk-{time.time_ns()}', - definition="""{ + created = w.cluster_policies.create( + name=f"sdk-{time.time_ns()}", + definition="""{ "spark_conf.spark.databricks.delta.preview.enabled": { "type": "fixed", "value": true } } - """) + """, + ) policy = w.cluster_policies.get(policy_id=created.policy_id) @@ -201,37 +209,37 @@ w.cluster_policies.delete(policy_id=created.policy_id) Get a cluster policy. - + Get a cluster policy entity. Creation and editing is available to admins only. - + :param policy_id: str Canonical unique identifier for the Cluster Policy. - + :returns: :class:`Policy` .. py:method:: get_permission_levels(cluster_policy_id: str) -> GetClusterPolicyPermissionLevelsResponse Get cluster policy permission levels. - + Gets the permission levels that a user can have on an object. - + :param cluster_policy_id: str The cluster policy for which to get or manage permissions. - + :returns: :class:`GetClusterPolicyPermissionLevelsResponse` .. py:method:: get_permissions(cluster_policy_id: str) -> ClusterPolicyPermissions Get cluster policy permissions. - + Gets the permissions of a cluster policy. Cluster policies can inherit permissions from their root object. - + :param cluster_policy_id: str The cluster policy for which to get or manage permissions. - + :returns: :class:`ClusterPolicyPermissions` @@ -250,43 +258,43 @@ all = w.cluster_policies.list(compute.ListClusterPoliciesRequest()) List cluster policies. - + Returns a list of policies accessible by the requesting user. - + :param sort_column: :class:`ListSortColumn` (optional) The cluster policy attribute to sort by. * `POLICY_CREATION_TIME` - Sort result list by policy creation time. * `POLICY_NAME` - Sort result list by policy name. :param sort_order: :class:`ListSortOrder` (optional) The order in which the policies get listed. * `DESC` - Sort result list in descending order. * `ASC` - Sort result list in ascending order. - + :returns: Iterator over :class:`Policy` .. py:method:: set_permissions(cluster_policy_id: str [, access_control_list: Optional[List[ClusterPolicyAccessControlRequest]]]) -> ClusterPolicyPermissions Set cluster policy permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param cluster_policy_id: str The cluster policy for which to get or manage permissions. :param access_control_list: List[:class:`ClusterPolicyAccessControlRequest`] (optional) - + :returns: :class:`ClusterPolicyPermissions` .. py:method:: update_permissions(cluster_policy_id: str [, access_control_list: Optional[List[ClusterPolicyAccessControlRequest]]]) -> ClusterPolicyPermissions Update cluster policy permissions. - + Updates the permissions on a cluster policy. Cluster policies can inherit permissions from their root object. - + :param cluster_policy_id: str The cluster policy for which to get or manage permissions. :param access_control_list: List[:class:`ClusterPolicyAccessControlRequest`] (optional) - + :returns: :class:`ClusterPolicyPermissions` \ No newline at end of file diff --git a/docs/workspace/compute/clusters.rst b/docs/workspace/compute/clusters.rst index 4e97857eb..528cff321 100644 --- a/docs/workspace/compute/clusters.rst +++ b/docs/workspace/compute/clusters.rst @@ -5,22 +5,22 @@ .. py:class:: ClustersExt The Clusters API allows you to create, start, edit, list, terminate, and delete clusters. - + Databricks maps cluster node instance types to compute units known as DBUs. See the instance type pricing page for a list of the supported instance types and their corresponding DBUs. - + A Databricks cluster is a set of computation resources and configurations on which you run data engineering, data science, and data analytics workloads, such as production ETL pipelines, streaming analytics, ad-hoc analytics, and machine learning. - + You run these workloads as a set of commands in a notebook or as an automated job. Databricks makes a distinction between all-purpose clusters and job clusters. You use all-purpose clusters to analyze data collaboratively using interactive notebooks. You use job clusters to run fast and robust automated jobs. - + You can create an all-purpose cluster using the UI, CLI, or REST API. You can manually terminate and restart an all-purpose cluster. Multiple users can share such clusters to do collaborative interactive analysis. - + IMPORTANT: Databricks retains cluster configuration information for terminated clusters for 30 days. To keep an all-purpose cluster configuration even after it has been terminated for more than 30 days, an administrator can pin a cluster to the cluster list. @@ -41,15 +41,17 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - other_owner = w.users.create(user_name=f'sdk-{time.time_ns()}@example.com') + other_owner = w.users.create(user_name=f"sdk-{time.time_ns()}@example.com") - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() w.clusters.change_owner(cluster_id=clstr.cluster_id, owner_username=other_owner.user_name) @@ -58,17 +60,17 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Change cluster owner. - + Change the owner of the cluster. You must be an admin and the cluster must be terminated to perform this operation. The service principal application ID can be supplied as an argument to `owner_username`. - + :param cluster_id: str :param owner_username: str New owner of the cluster_id after this RPC. - - + + .. py:method:: create(spark_version: str [, apply_policy_default_values: Optional[bool], autoscale: Optional[AutoScale], autotermination_minutes: Optional[int], aws_attributes: Optional[AwsAttributes], azure_attributes: Optional[AzureAttributes], clone_from: Optional[CloneCluster], cluster_log_conf: Optional[ClusterLogConf], cluster_name: Optional[str], custom_tags: Optional[Dict[str, str]], data_security_mode: Optional[DataSecurityMode], docker_image: Optional[DockerImage], driver_instance_pool_id: Optional[str], driver_node_type_id: Optional[str], enable_elastic_disk: Optional[bool], enable_local_disk_encryption: Optional[bool], gcp_attributes: Optional[GcpAttributes], init_scripts: Optional[List[InitScriptInfo]], instance_pool_id: Optional[str], is_single_node: Optional[bool], kind: Optional[Kind], node_type_id: Optional[str], num_workers: Optional[int], policy_id: Optional[str], runtime_engine: Optional[RuntimeEngine], single_user_name: Optional[str], spark_conf: Optional[Dict[str, str]], spark_env_vars: Optional[Dict[str, str]], ssh_public_keys: Optional[List[str]], use_ml_runtime: Optional[bool], workload_type: Optional[WorkloadType]]) -> Wait[ClusterDetails] @@ -87,31 +89,33 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() # cleanup w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Create new cluster. - + Creates a new Spark cluster. This method will acquire new instances from the cloud provider if necessary. Note: Databricks may not be able to acquire some of the requested nodes, due to cloud provider limitations (account limits, spot price, etc.) or transient network issues. - + If Databricks acquires at least 85% of the requested on-demand nodes, cluster creation will succeed. Otherwise the cluster will terminate with an informative error message. - + Rather than authoring the cluster's JSON definition from scratch, Databricks recommends filling out the [create compute UI] and then copying the generated JSON definition from the UI. - + [create compute UI]: https://docs.databricks.com/compute/configure.html - + :param spark_version: str The Spark version of the cluster, e.g. `3.3.x-scala2.11`. A list of available Spark versions can be retrieved by using the :method:clusters/sparkVersions API call. @@ -145,18 +149,18 @@ :param custom_tags: Dict[str,str] (optional) Additional tags for cluster resources. Databricks will tag all cluster resources (e.g., AWS instances and EBS volumes) with these tags in addition to `default_tags`. Notes: - + - Currently, Databricks allows at most 45 custom tags - + - Clusters can only reuse cloud resources if the resources' tags are a subset of the cluster tags :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * + + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. - + The following modes can be used regardless of `kind`. * `NONE`: No security isolation for multiple users sharing the cluster. Data governance features are not available in this mode. * `SINGLE_USER`: A secure cluster that can only be exclusively used by a single user specified in `single_user_name`. @@ -165,10 +169,10 @@ fully isolated so that they cannot see each other's data and credentials. Most data governance features are supported in this mode. But programming languages and cluster features might be limited. - + The following modes are deprecated starting with Databricks Runtime 15.0 and will be removed for future Databricks Runtime versions: - + * `LEGACY_TABLE_ACL`: This mode is for users migrating from legacy Table ACL clusters. * `LEGACY_PASSTHROUGH`: This mode is for users migrating from legacy Passthrough on high concurrency clusters. * `LEGACY_SINGLE_USER`: This mode is for users migrating from legacy Passthrough on @@ -197,16 +201,24 @@ :param instance_pool_id: str (optional) The optional ID of the instance pool to which the cluster belongs. :param is_single_node: bool (optional) - This field can only be used with `kind`. - + This field can only be used when `kind = CLASSIC_PREVIEW`. + When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers` :param kind: :class:`Kind` (optional) The kind of compute described by this compute specification. - + Depending on `kind`, different validations and default values will be applied. - - The first usage of this value is for the simple cluster form where it sets `kind = CLASSIC_PREVIEW`. + + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute @@ -215,7 +227,7 @@ :param num_workers: int (optional) Number of worker nodes that this cluster should have. A cluster has one Spark Driver and `num_workers` Executors for a total of `num_workers` + 1 Spark nodes. - + Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual current number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas @@ -225,10 +237,10 @@ The ID of the cluster policy used to create the cluster if applicable. :param runtime_engine: :class:`RuntimeEngine` (optional) Determines the cluster's runtime engine, either standard or Photon. - + This field is not compatible with legacy `spark_version` values that contain `-photon-`. Remove `-photon-` from the `spark_version` and set `runtime_engine` to `PHOTON`. - + If left unspecified, the runtime engine defaults to standard unless the spark_version contains -photon-, in which case Photon will be used. :param single_user_name: str (optional) @@ -241,11 +253,11 @@ An object containing a set of optional, user-specified environment variable key-value pairs. Please note that key-value pair of the form (X,Y) will be exported as is (i.e., `export X='Y'`) while launching the driver and workers. - + In order to specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the example below. This ensures that all default databricks managed environmental variables are included as well. - + Example Spark environment variables: `{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"}` or `{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}` @@ -254,12 +266,12 @@ private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified. :param use_ml_runtime: bool (optional) - This field can only be used with `kind`. - + This field can only be used when `kind = CLASSIC_PREVIEW`. + `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not. :param workload_type: :class:`WorkloadType` (optional) - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -284,13 +296,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() _ = w.clusters.delete(cluster_id=clstr.cluster_id).result() @@ -298,14 +312,14 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Terminate cluster. - + Terminates the Spark cluster with the specified ID. The cluster is removed asynchronously. Once the termination has completed, the cluster will be in a `TERMINATED` state. If the cluster is already in a `TERMINATING` or `TERMINATED` state, nothing will happen. - + :param cluster_id: str The cluster to be terminated. - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_terminated for more details. @@ -328,40 +342,44 @@ w = WorkspaceClient() - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() - - _ = w.clusters.edit(cluster_id=clstr.cluster_id, - spark_version=latest, - cluster_name=cluster_name, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=10, - num_workers=2).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() + + _ = w.clusters.edit( + cluster_id=clstr.cluster_id, + spark_version=latest, + cluster_name=cluster_name, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=10, + num_workers=2, + ).result() # cleanup w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Update cluster configuration. - + Updates the configuration of a cluster to match the provided attributes and size. A cluster can be updated if it is in a `RUNNING` or `TERMINATED` state. - + If a cluster is updated while in a `RUNNING` state, it will be restarted so that the new attributes can take effect. - + If a cluster is updated while in a `TERMINATED` state, it will remain `TERMINATED`. The next time it is started using the `clusters/start` API, the new attributes will take effect. Any attempt to update a cluster in any other state will be rejected with an `INVALID_STATE` error code. - + Clusters created by the Databricks Jobs service cannot be edited. - + :param cluster_id: str ID of the cluster :param spark_version: str @@ -395,18 +413,18 @@ :param custom_tags: Dict[str,str] (optional) Additional tags for cluster resources. Databricks will tag all cluster resources (e.g., AWS instances and EBS volumes) with these tags in addition to `default_tags`. Notes: - + - Currently, Databricks allows at most 45 custom tags - + - Clusters can only reuse cloud resources if the resources' tags are a subset of the cluster tags :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - - The following modes can only be used with `kind`. * `DATA_SECURITY_MODE_AUTO`: Databricks will - choose the most appropriate access mode depending on your compute configuration. * + + The following modes can only be used when `kind = CLASSIC_PREVIEW`. * `DATA_SECURITY_MODE_AUTO`: + Databricks will choose the most appropriate access mode depending on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: Alias for `USER_ISOLATION`. * `DATA_SECURITY_MODE_DEDICATED`: Alias for `SINGLE_USER`. - + The following modes can be used regardless of `kind`. * `NONE`: No security isolation for multiple users sharing the cluster. Data governance features are not available in this mode. * `SINGLE_USER`: A secure cluster that can only be exclusively used by a single user specified in `single_user_name`. @@ -415,10 +433,10 @@ fully isolated so that they cannot see each other's data and credentials. Most data governance features are supported in this mode. But programming languages and cluster features might be limited. - + The following modes are deprecated starting with Databricks Runtime 15.0 and will be removed for future Databricks Runtime versions: - + * `LEGACY_TABLE_ACL`: This mode is for users migrating from legacy Table ACL clusters. * `LEGACY_PASSTHROUGH`: This mode is for users migrating from legacy Passthrough on high concurrency clusters. * `LEGACY_SINGLE_USER`: This mode is for users migrating from legacy Passthrough on @@ -447,16 +465,24 @@ :param instance_pool_id: str (optional) The optional ID of the instance pool to which the cluster belongs. :param is_single_node: bool (optional) - This field can only be used with `kind`. - + This field can only be used when `kind = CLASSIC_PREVIEW`. + When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, and `num_workers` :param kind: :class:`Kind` (optional) The kind of compute described by this compute specification. - + Depending on `kind`, different validations and default values will be applied. - - The first usage of this value is for the simple cluster form where it sets `kind = CLASSIC_PREVIEW`. + + Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no + specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * + [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) * + [data_security_mode](/api/workspace/clusters/create#data_security_mode) set to + `DATA_SECURITY_MODE_AUTO`, `DATA_SECURITY_MODE_DEDICATED`, or `DATA_SECURITY_MODE_STANDARD` + + By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + + [simple form]: https://docs.databricks.com/compute/simple-form.html :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute @@ -465,7 +491,7 @@ :param num_workers: int (optional) Number of worker nodes that this cluster should have. A cluster has one Spark Driver and `num_workers` Executors for a total of `num_workers` + 1 Spark nodes. - + Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual current number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas @@ -475,10 +501,10 @@ The ID of the cluster policy used to create the cluster if applicable. :param runtime_engine: :class:`RuntimeEngine` (optional) Determines the cluster's runtime engine, either standard or Photon. - + This field is not compatible with legacy `spark_version` values that contain `-photon-`. Remove `-photon-` from the `spark_version` and set `runtime_engine` to `PHOTON`. - + If left unspecified, the runtime engine defaults to standard unless the spark_version contains -photon-, in which case Photon will be used. :param single_user_name: str (optional) @@ -491,11 +517,11 @@ An object containing a set of optional, user-specified environment variable key-value pairs. Please note that key-value pair of the form (X,Y) will be exported as is (i.e., `export X='Y'`) while launching the driver and workers. - + In order to specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the example below. This ensures that all default databricks managed environmental variables are included as well. - + Example Spark environment variables: `{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"}` or `{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}` @@ -504,12 +530,12 @@ private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified. :param use_ml_runtime: bool (optional) - This field can only be used with `kind`. - + This field can only be used when `kind = CLASSIC_PREVIEW`. + `effective_spark_version` is determined by `spark_version` (DBR release), this field `use_ml_runtime`, and whether `node_type_id` is gpu node or not. :param workload_type: :class:`WorkloadType` (optional) - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -559,13 +585,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() events = w.clusters.events(cluster_id=clstr.cluster_id) @@ -573,11 +601,11 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) List cluster activity events. - + Retrieves a list of events about the activity of a cluster. This API is paginated. If there are more events to read, the response includes all the nparameters necessary to request the next page of events. - + :param cluster_id: str The ID of the cluster to retrieve events about. :param end_time: int (optional) @@ -594,7 +622,7 @@ The order to list events in; either "ASC" or "DESC". Defaults to "DESC". :param start_time: int (optional) The start time in epoch milliseconds. If empty, returns events starting from the beginning of time. - + :returns: Iterator over :class:`ClusterEvent` @@ -614,13 +642,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() by_id = w.clusters.get(cluster_id=clstr.cluster_id) @@ -628,37 +658,37 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Get cluster info. - + Retrieves the information for a cluster given its identifier. Clusters can be described while they are running, or up to 60 days after they are terminated. - + :param cluster_id: str The cluster about which to retrieve information. - + :returns: :class:`ClusterDetails` .. py:method:: get_permission_levels(cluster_id: str) -> GetClusterPermissionLevelsResponse Get cluster permission levels. - + Gets the permission levels that a user can have on an object. - + :param cluster_id: str The cluster for which to get or manage permissions. - + :returns: :class:`GetClusterPermissionLevelsResponse` .. py:method:: get_permissions(cluster_id: str) -> ClusterPermissions Get cluster permissions. - + Gets the permissions of a cluster. Clusters can inherit permissions from their root object. - + :param cluster_id: str The cluster for which to get or manage permissions. - + :returns: :class:`ClusterPermissions` @@ -677,10 +707,10 @@ all = w.clusters.list(compute.ListClustersRequest()) List clusters. - + Return information about all pinned and active clusters, and all clusters terminated within the last 30 days. Clusters terminated prior to this period are not included. - + :param filter_by: :class:`ListClustersFilterBy` (optional) Filters to apply to the list of clusters. :param page_size: int (optional) @@ -691,7 +721,7 @@ previous page of clusters respectively. :param sort_by: :class:`ListClustersSortBy` (optional) Sort the list of clusters by a specific criteria. - + :returns: Iterator over :class:`ClusterDetails` @@ -709,36 +739,36 @@ nodes = w.clusters.list_node_types() List node types. - + Returns a list of supported Spark node types. These node types can be used to launch a cluster. - + :returns: :class:`ListNodeTypesResponse` .. py:method:: list_zones() -> ListAvailableZonesResponse List availability zones. - + Returns a list of availability zones where clusters can be created in (For example, us-west-2a). These zones can be used to launch a cluster. - + :returns: :class:`ListAvailableZonesResponse` .. py:method:: permanent_delete(cluster_id: str) Permanently delete cluster. - + Permanently deletes a Spark cluster. This cluster is terminated and resources are asynchronously removed. - + In addition, users will no longer see permanently deleted clusters in the cluster list, and API users can no longer perform any action on permanently deleted clusters. - + :param cluster_id: str The cluster to be deleted. - - + + .. py:method:: pin(cluster_id: str) @@ -757,13 +787,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() w.clusters.pin(cluster_id=clstr.cluster_id) @@ -771,14 +803,14 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Pin cluster. - + Pinning a cluster ensures that the cluster will always be returned by the ListClusters API. Pinning a cluster that is already pinned will have no effect. This API can only be called by workspace admins. - + :param cluster_id: str - - + + .. py:method:: resize(cluster_id: str [, autoscale: Optional[AutoScale], num_workers: Optional[int]]) -> Wait[ClusterDetails] @@ -797,13 +829,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() by_id = w.clusters.resize(cluster_id=clstr.cluster_id, num_workers=1).result() @@ -811,10 +845,10 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Resize cluster. - + Resizes a cluster to have a desired number of workers. This will fail unless the cluster is in a `RUNNING` state. - + :param cluster_id: str The cluster to be resized. :param autoscale: :class:`AutoScale` (optional) @@ -823,13 +857,13 @@ :param num_workers: int (optional) Number of worker nodes that this cluster should have. A cluster has one Spark Driver and `num_workers` Executors for a total of `num_workers` + 1 Spark nodes. - + Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual current number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in `spark_info` will gradually increase from 5 to 10 as the new nodes are provisioned. - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -854,13 +888,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() _ = w.clusters.restart(cluster_id=clstr.cluster_id).result() @@ -868,15 +904,15 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Restart cluster. - + Restarts a Spark cluster with the supplied ID. If the cluster is not currently in a `RUNNING` state, nothing will happen. - + :param cluster_id: str The cluster to be started. :param restart_user: str (optional) - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -949,23 +985,23 @@ .. py:method:: set_permissions(cluster_id: str [, access_control_list: Optional[List[ClusterAccessControlRequest]]]) -> ClusterPermissions Set cluster permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param cluster_id: str The cluster for which to get or manage permissions. :param access_control_list: List[:class:`ClusterAccessControlRequest`] (optional) - + :returns: :class:`ClusterPermissions` .. py:method:: spark_versions() -> GetSparkVersionsResponse List available Spark versions. - + Returns the list of available Spark versions. These versions can be used to launch a cluster. - + :returns: :class:`GetSparkVersionsResponse` @@ -985,13 +1021,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() _ = w.clusters.start(cluster_id=clstr.cluster_id).result() @@ -999,17 +1037,17 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Start terminated cluster. - + Starts a terminated Spark cluster with the supplied ID. This works similar to `createCluster` except: - + * The previous cluster id and attributes are preserved. * The cluster starts with the last specified cluster size. * If the previous cluster was an autoscaling cluster, the current cluster starts with the minimum number of nodes. * If the cluster is not currently in a `TERMINATED` state, nothing will happen. * Clusters launched to run a job cannot be started. - + :param cluster_id: str The cluster to be started. - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -1034,13 +1072,15 @@ latest = w.clusters.select_spark_version(latest=True, long_term_support=True) - cluster_name = f'sdk-{time.time_ns()}' + cluster_name = f"sdk-{time.time_ns()}" - clstr = w.clusters.create(cluster_name=cluster_name, - spark_version=latest, - instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - autotermination_minutes=15, - num_workers=1).result() + clstr = w.clusters.create( + cluster_name=cluster_name, + spark_version=latest, + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + autotermination_minutes=15, + num_workers=1, + ).result() w.clusters.unpin(cluster_id=clstr.cluster_id) @@ -1048,21 +1088,21 @@ w.clusters.permanent_delete(cluster_id=clstr.cluster_id) Unpin cluster. - + Unpinning a cluster will allow the cluster to eventually be removed from the ListClusters API. Unpinning a cluster that is not pinned will have no effect. This API can only be called by workspace admins. - + :param cluster_id: str - - + + .. py:method:: update(cluster_id: str, update_mask: str [, cluster: Optional[UpdateClusterResource]]) -> Wait[ClusterDetails] Update cluster configuration (partial). - + Updates the configuration of a cluster to match the partial set of attributes and size. Denote which fields to update using the `update_mask` field in the request body. A cluster can be updated if it is in a `RUNNING` or `TERMINATED` state. If a cluster is updated while in a `RUNNING` state, it will be @@ -1071,7 +1111,7 @@ is started using the `clusters/start` API. Attempts to update a cluster in any other state will be rejected with an `INVALID_STATE` error code. Clusters created by the Databricks Jobs service cannot be updated. - + :param cluster_id: str ID of the cluster. :param update_mask: str @@ -1081,7 +1121,7 @@ string but omit it from the `cluster` object. :param cluster: :class:`UpdateClusterResource` (optional) The cluster to be updated. - + :returns: Long-running operation waiter for :class:`ClusterDetails`. See :method:wait_get_cluster_running for more details. @@ -1093,13 +1133,13 @@ .. py:method:: update_permissions(cluster_id: str [, access_control_list: Optional[List[ClusterAccessControlRequest]]]) -> ClusterPermissions Update cluster permissions. - + Updates the permissions on a cluster. Clusters can inherit permissions from their root object. - + :param cluster_id: str The cluster for which to get or manage permissions. :param access_control_list: List[:class:`ClusterAccessControlRequest`] (optional) - + :returns: :class:`ClusterPermissions` diff --git a/docs/workspace/compute/command_execution.rst b/docs/workspace/compute/command_execution.rst index 916a48ba5..c96d044a2 100644 --- a/docs/workspace/compute/command_execution.rst +++ b/docs/workspace/compute/command_execution.rst @@ -10,15 +10,15 @@ .. py:method:: cancel( [, cluster_id: Optional[str], command_id: Optional[str], context_id: Optional[str]]) -> Wait[CommandStatusResponse] Cancel a command. - + Cancels a currently running command within an execution context. - + The command ID is obtained from a prior successful call to __execute__. - + :param cluster_id: str (optional) :param command_id: str (optional) :param context_id: str (optional) - + :returns: Long-running operation waiter for :class:`CommandStatusResponse`. See :method:wait_command_status_command_execution_cancelled for more details. @@ -30,27 +30,27 @@ .. py:method:: command_status(cluster_id: str, context_id: str, command_id: str) -> CommandStatusResponse Get command info. - + Gets the status of and, if available, the results from a currently executing command. - + The command ID is obtained from a prior successful call to __execute__. - + :param cluster_id: str :param context_id: str :param command_id: str - + :returns: :class:`CommandStatusResponse` .. py:method:: context_status(cluster_id: str, context_id: str) -> ContextStatusResponse Get status. - + Gets the status for an execution context. - + :param cluster_id: str :param context_id: str - + :returns: :class:`ContextStatusResponse` @@ -76,15 +76,15 @@ w.command_execution.destroy(cluster_id=cluster_id, context_id=context.id) Create an execution context. - + Creates an execution context for running cluster commands. - + If successful, this method returns the ID of the new execution context. - + :param cluster_id: str (optional) Running cluster id :param language: :class:`Language` (optional) - + :returns: Long-running operation waiter for :class:`ContextStatusResponse`. See :method:wait_context_status_command_execution_running for more details. @@ -96,13 +96,13 @@ .. py:method:: destroy(cluster_id: str, context_id: str) Delete an execution context. - + Deletes an execution context. - + :param cluster_id: str :param context_id: str - - + + .. py:method:: execute( [, cluster_id: Optional[str], command: Optional[str], context_id: Optional[str], language: Optional[Language]]) -> Wait[CommandStatusResponse] @@ -123,20 +123,22 @@ context = w.command_execution.create(cluster_id=cluster_id, language=compute.Language.PYTHON).result() - text_results = w.command_execution.execute(cluster_id=cluster_id, - context_id=context.id, - language=compute.Language.PYTHON, - command="print(1)").result() + text_results = w.command_execution.execute( + cluster_id=cluster_id, + context_id=context.id, + language=compute.Language.PYTHON, + command="print(1)", + ).result() # cleanup w.command_execution.destroy(cluster_id=cluster_id, context_id=context.id) Run a command. - + Runs a cluster command in the given execution context, using the provided language. - + If successful, it returns an ID for tracking the status of the command's execution. - + :param cluster_id: str (optional) Running cluster id :param command: str (optional) @@ -144,7 +146,7 @@ :param context_id: str (optional) Running context id :param language: :class:`Language` (optional) - + :returns: Long-running operation waiter for :class:`CommandStatusResponse`. See :method:wait_command_status_command_execution_finished_or_error for more details. diff --git a/docs/workspace/compute/global_init_scripts.rst b/docs/workspace/compute/global_init_scripts.rst index 9d2372a6d..e2eba7604 100644 --- a/docs/workspace/compute/global_init_scripts.rst +++ b/docs/workspace/compute/global_init_scripts.rst @@ -6,7 +6,7 @@ The Global Init Scripts API enables Workspace administrators to configure global initialization scripts for their workspace. These scripts run on every node in every cluster in the workspace. - + **Important:** Existing clusters must be restarted to pick up any changes made to global init scripts. Global init scripts are run in order. If the init script returns with a bad exit code, the Apache Spark container fails to launch and init scripts with later position are skipped. If enough containers fail, the @@ -26,18 +26,20 @@ w = WorkspaceClient() - created = w.global_init_scripts.create(name=f'sdk-{time.time_ns()}', - script=base64.b64encode(("echo 1").encode()).decode(), - enabled=True, - position=10) + created = w.global_init_scripts.create( + name=f"sdk-{time.time_ns()}", + script=base64.b64encode(("echo 1").encode()).decode(), + enabled=True, + position=10, + ) # cleanup w.global_init_scripts.delete(script_id=created.script_id) Create init script. - + Creates a new global init script in this workspace. - + :param name: str The name of the script :param script: str @@ -47,27 +49,27 @@ :param position: int (optional) The position of a global init script, where 0 represents the first script to run, 1 is the second script to run, in ascending order. - + If you omit the numeric position for a new global init script, it defaults to last position. It will run after all current scripts. Setting any value greater than the position of the last script is equivalent to the last position. Example: Take three existing scripts with positions 0, 1, and 2. Any position of (3) or greater puts the script in the last position. If an explicit position value conflicts with an existing script value, your request succeeds, but the original script at that position and all later scripts have their positions incremented by 1. - + :returns: :class:`CreateResponse` .. py:method:: delete(script_id: str) Delete init script. - + Deletes a global init script. - + :param script_id: str The ID of the global init script. - - + + .. py:method:: get(script_id: str) -> GlobalInitScriptDetailsWithContent @@ -84,10 +86,12 @@ w = WorkspaceClient() - created = w.global_init_scripts.create(name=f'sdk-{time.time_ns()}', - script=base64.b64encode(("echo 1").encode()).decode(), - enabled=True, - position=10) + created = w.global_init_scripts.create( + name=f"sdk-{time.time_ns()}", + script=base64.b64encode(("echo 1").encode()).decode(), + enabled=True, + position=10, + ) by_id = w.global_init_scripts.get(script_id=created.script_id) @@ -95,12 +99,12 @@ w.global_init_scripts.delete(script_id=created.script_id) Get an init script. - + Gets all the details of a script, including its Base64-encoded contents. - + :param script_id: str The ID of the global init script. - + :returns: :class:`GlobalInitScriptDetailsWithContent` @@ -118,11 +122,11 @@ all = w.global_init_scripts.list() Get init scripts. - + Get a list of all global init scripts for this workspace. This returns all properties for each script but **not** the script contents. To retrieve the contents of a script, use the [get a global init script](:method:globalinitscripts/get) operation. - + :returns: Iterator over :class:`GlobalInitScriptDetails` @@ -140,23 +144,27 @@ w = WorkspaceClient() - created = w.global_init_scripts.create(name=f'sdk-{time.time_ns()}', - script=base64.b64encode(("echo 1").encode()).decode(), - enabled=True, - position=10) + created = w.global_init_scripts.create( + name=f"sdk-{time.time_ns()}", + script=base64.b64encode(("echo 1").encode()).decode(), + enabled=True, + position=10, + ) - w.global_init_scripts.update(script_id=created.script_id, - name=f'sdk-{time.time_ns()}', - script=base64.b64encode(("echo 2").encode()).decode()) + w.global_init_scripts.update( + script_id=created.script_id, + name=f"sdk-{time.time_ns()}", + script=base64.b64encode(("echo 2").encode()).decode(), + ) # cleanup w.global_init_scripts.delete(script_id=created.script_id) Update init script. - + Updates a global init script, specifying only the fields to change. All fields are optional. Unspecified fields retain their current value. - + :param script_id: str The ID of the global init script. :param name: str @@ -168,13 +176,13 @@ :param position: int (optional) The position of a script, where 0 represents the first script to run, 1 is the second script to run, in ascending order. To move the script to run first, set its position to 0. - + To move the script to the end, set its position to any value greater or equal to the position of the last script. Example, three existing scripts with positions 0, 1, and 2. Any position value of 2 or greater puts the script in the last position (2). - + If an explicit position value conflicts with an existing script, your request succeeds, but the original script at that position and all later scripts have their positions incremented by 1. - - + + \ No newline at end of file diff --git a/docs/workspace/compute/instance_pools.rst b/docs/workspace/compute/instance_pools.rst index 333c44938..0614f2101 100644 --- a/docs/workspace/compute/instance_pools.rst +++ b/docs/workspace/compute/instance_pools.rst @@ -6,16 +6,16 @@ Instance Pools API are used to create, edit, delete and list instance pools by using ready-to-use cloud instances which reduces a cluster start and auto-scaling times. - + Databricks pools reduce cluster start and auto-scaling times by maintaining a set of idle, ready-to-use instances. When a cluster is attached to a pool, cluster nodes are created using the pool’s idle instances. If the pool has no idle instances, the pool expands by allocating a new instance from the instance provider in order to accommodate the cluster’s request. When a cluster releases an instance, it returns to the pool and is free for another cluster to use. Only clusters attached to a pool can use that pool’s idle instances. - + You can specify a different pool for the driver node and worker nodes, or use the same pool for both. - + Databricks does not charge DBUs while instances are idle in the pool. Instance provider billing does apply. See pricing. @@ -34,15 +34,15 @@ smallest = w.clusters.select_node_type(local_disk=True) - created = w.instance_pools.create(instance_pool_name=f'sdk-{time.time_ns()}', node_type_id=smallest) + created = w.instance_pools.create(instance_pool_name=f"sdk-{time.time_ns()}", node_type_id=smallest) # cleanup w.instance_pools.delete(instance_pool_id=created.instance_pool_id) Create a new instance pool. - + Creates a new instance pool using idle and ready-to-use cloud instances. - + :param instance_pool_name: str Pool name requested by the user. Pool name must be unique. Length must be between 1 and 100 characters. @@ -60,7 +60,7 @@ :param custom_tags: Dict[str,str] (optional) Additional tags for pool resources. Databricks will tag all pool resources (e.g., AWS instances and EBS volumes) with these tags in addition to `default_tags`. Notes: - + - Currently, Databricks allows at most 45 custom tags :param disk_spec: :class:`DiskSpec` (optional) Defines the specification of the disks that will be attached to all spark containers. @@ -89,20 +89,20 @@ A list containing at most one preloaded Spark image version for the pool. Pool-backed clusters started with the preloaded Spark version will start faster. A list of available Spark versions can be retrieved by using the :method:clusters/sparkVersions API call. - + :returns: :class:`CreateInstancePoolResponse` .. py:method:: delete(instance_pool_id: str) Delete an instance pool. - + Deletes the instance pool permanently. The idle instances in the pool are terminated asynchronously. - + :param instance_pool_id: str The instance pool to be terminated. - - + + .. py:method:: edit(instance_pool_id: str, instance_pool_name: str, node_type_id: str [, custom_tags: Optional[Dict[str, str]], idle_instance_autotermination_minutes: Optional[int], max_capacity: Optional[int], min_idle_instances: Optional[int]]) @@ -120,19 +120,21 @@ smallest = w.clusters.select_node_type(local_disk=True) - created = w.instance_pools.create(instance_pool_name=f'sdk-{time.time_ns()}', node_type_id=smallest) + created = w.instance_pools.create(instance_pool_name=f"sdk-{time.time_ns()}", node_type_id=smallest) - w.instance_pools.edit(instance_pool_id=created.instance_pool_id, - instance_pool_name=f'sdk-{time.time_ns()}', - node_type_id=smallest) + w.instance_pools.edit( + instance_pool_id=created.instance_pool_id, + instance_pool_name=f"sdk-{time.time_ns()}", + node_type_id=smallest, + ) # cleanup w.instance_pools.delete(instance_pool_id=created.instance_pool_id) Edit an existing instance pool. - + Modifies the configuration of an existing instance pool. - + :param instance_pool_id: str Instance pool ID :param instance_pool_name: str @@ -146,7 +148,7 @@ :param custom_tags: Dict[str,str] (optional) Additional tags for pool resources. Databricks will tag all pool resources (e.g., AWS instances and EBS volumes) with these tags in addition to `default_tags`. Notes: - + - Currently, Databricks allows at most 45 custom tags :param idle_instance_autotermination_minutes: int (optional) Automatically terminates the extra instances in the pool cache after they are inactive for this time @@ -160,8 +162,8 @@ upsize requests. :param min_idle_instances: int (optional) Minimum number of idle instances to keep in the instance pool - - + + .. py:method:: get(instance_pool_id: str) -> GetInstancePool @@ -179,7 +181,7 @@ smallest = w.clusters.select_node_type(local_disk=True) - created = w.instance_pools.create(instance_pool_name=f'sdk-{time.time_ns()}', node_type_id=smallest) + created = w.instance_pools.create(instance_pool_name=f"sdk-{time.time_ns()}", node_type_id=smallest) by_id = w.instance_pools.get(instance_pool_id=created.instance_pool_id) @@ -187,37 +189,37 @@ w.instance_pools.delete(instance_pool_id=created.instance_pool_id) Get instance pool information. - + Retrieve the information for an instance pool based on its identifier. - + :param instance_pool_id: str The canonical unique identifier for the instance pool. - + :returns: :class:`GetInstancePool` .. py:method:: get_permission_levels(instance_pool_id: str) -> GetInstancePoolPermissionLevelsResponse Get instance pool permission levels. - + Gets the permission levels that a user can have on an object. - + :param instance_pool_id: str The instance pool for which to get or manage permissions. - + :returns: :class:`GetInstancePoolPermissionLevelsResponse` .. py:method:: get_permissions(instance_pool_id: str) -> InstancePoolPermissions Get instance pool permissions. - + Gets the permissions of an instance pool. Instance pools can inherit permissions from their root object. - + :param instance_pool_id: str The instance pool for which to get or manage permissions. - + :returns: :class:`InstancePoolPermissions` @@ -235,36 +237,36 @@ all = w.instance_pools.list() List instance pool info. - + Gets a list of instance pools with their statistics. - + :returns: Iterator over :class:`InstancePoolAndStats` .. py:method:: set_permissions(instance_pool_id: str [, access_control_list: Optional[List[InstancePoolAccessControlRequest]]]) -> InstancePoolPermissions Set instance pool permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param instance_pool_id: str The instance pool for which to get or manage permissions. :param access_control_list: List[:class:`InstancePoolAccessControlRequest`] (optional) - + :returns: :class:`InstancePoolPermissions` .. py:method:: update_permissions(instance_pool_id: str [, access_control_list: Optional[List[InstancePoolAccessControlRequest]]]) -> InstancePoolPermissions Update instance pool permissions. - + Updates the permissions on an instance pool. Instance pools can inherit permissions from their root object. - + :param instance_pool_id: str The instance pool for which to get or manage permissions. :param access_control_list: List[:class:`InstancePoolAccessControlRequest`] (optional) - + :returns: :class:`InstancePoolPermissions` \ No newline at end of file diff --git a/docs/workspace/compute/instance_profiles.rst b/docs/workspace/compute/instance_profiles.rst index a7a25f869..6b7c1ca05 100644 --- a/docs/workspace/compute/instance_profiles.rst +++ b/docs/workspace/compute/instance_profiles.rst @@ -7,8 +7,9 @@ The Instance Profiles API allows admins to add, list, and remove instance profiles that users can launch clusters with. Regular users can list the instance profiles available to them. See [Secure access to S3 buckets] using instance profiles for more information. - + [Secure access to S3 buckets]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/instance-profiles.html + .. py:method:: add(instance_profile_arn: str [, iam_role_arn: Optional[str], is_meta_instance_profile: Optional[bool], skip_validation: Optional[bool]]) @@ -23,24 +24,26 @@ arn = "arn:aws:iam::000000000000:instance-profile/abc" - w.instance_profiles.add(instance_profile_arn=arn, - skip_validation=True, - iam_role_arn="arn:aws:iam::000000000000:role/bcd") + w.instance_profiles.add( + instance_profile_arn=arn, + skip_validation=True, + iam_role_arn="arn:aws:iam::000000000000:role/bcd", + ) Register an instance profile. - + In the UI, you can select the instance profile when launching clusters. This API is only available to admin users. - + :param instance_profile_arn: str The AWS ARN of the instance profile to register with Databricks. This field is required. :param iam_role_arn: str (optional) The AWS IAM role ARN of the role associated with the instance profile. This field is required if your role name and instance profile name do not match and you want to use the instance profile with [Databricks SQL Serverless]. - + Otherwise, this field is optional. - + [Databricks SQL Serverless]: https://docs.databricks.com/sql/admin/serverless.html :param is_meta_instance_profile: bool (optional) Boolean flag indicating whether the instance profile should only be used in credential passthrough @@ -53,8 +56,8 @@ fails with an error message that does not indicate an IAM related permission issue, (e.g. “Your requested instance type is not supported in your requested availability zone”), you can pass this flag to skip the validation and forcibly add the instance profile. - - + + .. py:method:: edit(instance_profile_arn: str [, iam_role_arn: Optional[str], is_meta_instance_profile: Optional[bool]]) @@ -70,40 +73,43 @@ arn = "arn:aws:iam::000000000000:instance-profile/abc" - w.instance_profiles.edit(instance_profile_arn=arn, iam_role_arn="arn:aws:iam::000000000000:role/bcdf") + w.instance_profiles.edit( + instance_profile_arn=arn, + iam_role_arn="arn:aws:iam::000000000000:role/bcdf", + ) Edit an instance profile. - + The only supported field to change is the optional IAM role ARN associated with the instance profile. It is required to specify the IAM role ARN if both of the following are true: - + * Your role name and instance profile name do not match. The name is the part after the last slash in each ARN. * You want to use the instance profile with [Databricks SQL Serverless]. - + To understand where these fields are in the AWS console, see [Enable serverless SQL warehouses]. - + This API is only available to admin users. - + [Databricks SQL Serverless]: https://docs.databricks.com/sql/admin/serverless.html [Enable serverless SQL warehouses]: https://docs.databricks.com/sql/admin/serverless.html - + :param instance_profile_arn: str The AWS ARN of the instance profile to register with Databricks. This field is required. :param iam_role_arn: str (optional) The AWS IAM role ARN of the role associated with the instance profile. This field is required if your role name and instance profile name do not match and you want to use the instance profile with [Databricks SQL Serverless]. - + Otherwise, this field is optional. - + [Databricks SQL Serverless]: https://docs.databricks.com/sql/admin/serverless.html :param is_meta_instance_profile: bool (optional) Boolean flag indicating whether the instance profile should only be used in credential passthrough scenarios. If true, it means the instance profile contains an meta IAM role which could assume a wide range of roles. Therefore it should always be used with authorization. This field is optional, the default value is `false`. - - + + .. py:method:: list() -> Iterator[InstanceProfile] @@ -120,25 +126,25 @@ all = w.instance_profiles.list() List available instance profiles. - + List the instance profiles that the calling user can use to launch a cluster. - + This API is available to all users. - + :returns: Iterator over :class:`InstanceProfile` .. py:method:: remove(instance_profile_arn: str) Remove the instance profile. - + Remove the instance profile with the provided ARN. Existing clusters with this instance profile will continue to function. - + This API is only accessible to admin users. - + :param instance_profile_arn: str The ARN of the instance profile to remove. This field is required. - - + + \ No newline at end of file diff --git a/docs/workspace/compute/libraries.rst b/docs/workspace/compute/libraries.rst index 64f688fdc..339f54de2 100644 --- a/docs/workspace/compute/libraries.rst +++ b/docs/workspace/compute/libraries.rst @@ -6,70 +6,70 @@ The Libraries API allows you to install and uninstall libraries and get the status of libraries on a cluster. - + To make third-party or custom code available to notebooks and jobs running on your clusters, you can install a library. Libraries can be written in Python, Java, Scala, and R. You can upload Python, Java, Scala and R libraries and point to external packages in PyPI, Maven, and CRAN repositories. - + Cluster libraries can be used by all notebooks running on a cluster. You can install a cluster library directly from a public repository such as PyPI or Maven, using a previously installed workspace library, or using an init script. - + When you uninstall a library from a cluster, the library is removed only when you restart the cluster. Until you restart the cluster, the status of the uninstalled library appears as Uninstall pending restart. .. py:method:: all_cluster_statuses() -> Iterator[ClusterLibraryStatuses] Get all statuses. - + Get the status of all libraries on all clusters. A status is returned for all libraries installed on this cluster via the API or the libraries UI. - + :returns: Iterator over :class:`ClusterLibraryStatuses` .. py:method:: cluster_status(cluster_id: str) -> Iterator[LibraryFullStatus] Get status. - + Get the status of libraries on a cluster. A status is returned for all libraries installed on this cluster via the API or the libraries UI. The order of returned libraries is as follows: 1. Libraries set to be installed on this cluster, in the order that the libraries were added to the cluster, are returned first. 2. Libraries that were previously requested to be installed on this cluster or, but are now marked for removal, in no particular order, are returned last. - + :param cluster_id: str Unique identifier of the cluster whose status should be retrieved. - + :returns: Iterator over :class:`LibraryFullStatus` .. py:method:: install(cluster_id: str, libraries: List[Library]) Add a library. - + Add libraries to install on a cluster. The installation is asynchronous; it happens in the background after the completion of this request. - + :param cluster_id: str Unique identifier for the cluster on which to install these libraries. :param libraries: List[:class:`Library`] The libraries to install. - - + + .. py:method:: uninstall(cluster_id: str, libraries: List[Library]) Uninstall libraries. - + Set libraries to uninstall from a cluster. The libraries won't be uninstalled until the cluster is restarted. A request to uninstall a library that is not currently installed is ignored. - + :param cluster_id: str Unique identifier for the cluster on which to uninstall these libraries. :param libraries: List[:class:`Library`] The libraries to uninstall. - - + + \ No newline at end of file diff --git a/docs/workspace/compute/policy_compliance_for_clusters.rst b/docs/workspace/compute/policy_compliance_for_clusters.rst index 90c3aeb98..fea7a08f9 100644 --- a/docs/workspace/compute/policy_compliance_for_clusters.rst +++ b/docs/workspace/compute/policy_compliance_for_clusters.rst @@ -6,58 +6,58 @@ The policy compliance APIs allow you to view and manage the policy compliance status of clusters in your workspace. - + A cluster is compliant with its policy if its configuration satisfies all its policy rules. Clusters could be out of compliance if their policy was updated after the cluster was last edited. - + The get and list compliance APIs allow you to view the policy compliance status of a cluster. The enforce compliance API allows you to update a cluster to be compliant with the current version of its policy. .. py:method:: enforce_compliance(cluster_id: str [, validate_only: Optional[bool]]) -> EnforceClusterComplianceResponse Enforce cluster policy compliance. - + Updates a cluster to be compliant with the current version of its policy. A cluster can be updated if it is in a `RUNNING` or `TERMINATED` state. - + If a cluster is updated while in a `RUNNING` state, it will be restarted so that the new attributes can take effect. - + If a cluster is updated while in a `TERMINATED` state, it will remain `TERMINATED`. The next time the cluster is started, the new attributes will take effect. - + Clusters created by the Databricks Jobs, DLT, or Models services cannot be enforced by this API. Instead, use the "Enforce job policy compliance" API to enforce policy compliance on jobs. - + :param cluster_id: str The ID of the cluster you want to enforce policy compliance on. :param validate_only: bool (optional) If set, previews the changes that would be made to a cluster to enforce compliance but does not update the cluster. - + :returns: :class:`EnforceClusterComplianceResponse` .. py:method:: get_compliance(cluster_id: str) -> GetClusterComplianceResponse Get cluster policy compliance. - + Returns the policy compliance status of a cluster. Clusters could be out of compliance if their policy was updated after the cluster was last edited. - + :param cluster_id: str The ID of the cluster to get the compliance status - + :returns: :class:`GetClusterComplianceResponse` .. py:method:: list_compliance(policy_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ClusterCompliance] List cluster policy compliance. - + Returns the policy compliance status of all clusters that use a given policy. Clusters could be out of compliance if their policy was updated after the cluster was last edited. - + :param policy_id: str Canonical unique identifier for the cluster policy. :param page_size: int (optional) @@ -66,6 +66,6 @@ :param page_token: str (optional) A page token that can be used to navigate to the next page or previous page as returned by `next_page_token` or `prev_page_token`. - + :returns: Iterator over :class:`ClusterCompliance` \ No newline at end of file diff --git a/docs/workspace/compute/policy_families.rst b/docs/workspace/compute/policy_families.rst index 56e4f4275..8bbcd039f 100644 --- a/docs/workspace/compute/policy_families.rst +++ b/docs/workspace/compute/policy_families.rst @@ -6,10 +6,10 @@ View available policy families. A policy family contains a policy definition providing best practices for configuring clusters for a particular use case. - + Databricks manages and provides policy families for several common cluster use cases. You cannot create, edit, or delete policy families. - + Policy families cannot be used directly to create clusters. Instead, you create cluster policies using a policy family. Cluster policies created using a policy family inherit the policy family's policy definition. @@ -31,14 +31,14 @@ first_family = w.policy_families.get(policy_family_id=all[0].policy_family_id) Get policy family information. - + Retrieve the information for an policy family based on its identifier and version - + :param policy_family_id: str The family ID about which to retrieve information. :param version: int (optional) The version number for the family to fetch. Defaults to the latest version. - + :returns: :class:`PolicyFamily` @@ -57,14 +57,14 @@ all = w.policy_families.list(compute.ListPolicyFamiliesRequest()) List policy families. - + Returns the list of policy definition types available to use at their latest version. This API is paginated. - + :param max_results: int (optional) Maximum number of policy families to return. :param page_token: str (optional) A token that can be used to get the next page of results. - + :returns: Iterator over :class:`PolicyFamily` \ No newline at end of file diff --git a/docs/workspace/dashboards/genie.rst b/docs/workspace/dashboards/genie.rst index 3908c6472..6c0e91751 100644 --- a/docs/workspace/dashboards/genie.rst +++ b/docs/workspace/dashboards/genie.rst @@ -12,17 +12,17 @@ .. py:method:: create_message(space_id: str, conversation_id: str, content: str) -> Wait[GenieMessage] Create conversation message. - - Create new message in [conversation](:method:genie/startconversation). The AI response uses all + + Create new message in a [conversation](:method:genie/startconversation). The AI response uses all previously created messages in the conversation to respond. - + :param space_id: str The ID associated with the Genie space where the conversation is started. :param conversation_id: str The ID associated with the conversation. :param content: str User message content. - + :returns: Long-running operation waiter for :class:`GenieMessage`. See :method:wait_get_message_genie_completed for more details. @@ -31,62 +31,99 @@ .. py:method:: create_message_and_wait(space_id: str, conversation_id: str, content: str, timeout: datetime.timedelta = 0:20:00) -> GenieMessage + .. py:method:: execute_message_attachment_query(space_id: str, conversation_id: str, message_id: str, attachment_id: str) -> GenieGetMessageQueryResultResponse + + Execute message attachment SQL query. + + Execute the SQL for a message query attachment. + + :param space_id: str + Genie space ID + :param conversation_id: str + Conversation ID + :param message_id: str + Message ID + :param attachment_id: str + Attachment ID + + :returns: :class:`GenieGetMessageQueryResultResponse` + + .. py:method:: execute_message_query(space_id: str, conversation_id: str, message_id: str) -> GenieGetMessageQueryResultResponse Execute SQL query in a conversation message. - + Execute the SQL query in the message. - + :param space_id: str Genie space ID :param conversation_id: str Conversation ID :param message_id: str Message ID - + :returns: :class:`GenieGetMessageQueryResultResponse` .. py:method:: get_message(space_id: str, conversation_id: str, message_id: str) -> GenieMessage Get conversation message. - + Get message from conversation. - + :param space_id: str The ID associated with the Genie space where the target conversation is located. :param conversation_id: str The ID associated with the target conversation. :param message_id: str The ID associated with the target message from the identified conversation. - + :returns: :class:`GenieMessage` - .. py:method:: get_message_query_result(space_id: str, conversation_id: str, message_id: str) -> GenieGetMessageQueryResultResponse + .. py:method:: get_message_attachment_query_result(space_id: str, conversation_id: str, message_id: str, attachment_id: str) -> GenieGetMessageQueryResultResponse - Get conversation message SQL query result. + Get message attachment SQL query result. + + Get the result of SQL query if the message has a query attachment. This is only available if a message + has a query attachment and the message status is `EXECUTING_QUERY` OR `COMPLETED`. + + :param space_id: str + Genie space ID + :param conversation_id: str + Conversation ID + :param message_id: str + Message ID + :param attachment_id: str + Attachment ID + + :returns: :class:`GenieGetMessageQueryResultResponse` + + .. py:method:: get_message_query_result(space_id: str, conversation_id: str, message_id: str) -> GenieGetMessageQueryResultResponse + + [Deprecated] Get conversation message SQL query result. + Get the result of SQL query if the message has a query attachment. This is only available if a message has a query attachment and the message status is `EXECUTING_QUERY`. - + :param space_id: str Genie space ID :param conversation_id: str Conversation ID :param message_id: str Message ID - + :returns: :class:`GenieGetMessageQueryResultResponse` .. py:method:: get_message_query_result_by_attachment(space_id: str, conversation_id: str, message_id: str, attachment_id: str) -> GenieGetMessageQueryResultResponse - Get conversation message SQL query result by attachment id. - - Get the result of SQL query by attachment id This is only available if a message has a query - attachment and the message status is `EXECUTING_QUERY`. - + [deprecated] Get conversation message SQL query result. + + Get the result of SQL query if the message has a query attachment. This is only available if a message + has a query attachment and the message status is `EXECUTING_QUERY` OR `COMPLETED`. + :param space_id: str Genie space ID :param conversation_id: str @@ -95,21 +132,33 @@ Message ID :param attachment_id: str Attachment ID - + :returns: :class:`GenieGetMessageQueryResultResponse` + .. py:method:: get_space(space_id: str) -> GenieSpace + + Get details of a Genie Space. + + Get a Genie Space. + + :param space_id: str + The ID associated with the Genie space + + :returns: :class:`GenieSpace` + + .. py:method:: start_conversation(space_id: str, content: str) -> Wait[GenieMessage] Start conversation. - + Start a new conversation. - + :param space_id: str The ID associated with the Genie space where you want to start a conversation. :param content: str The text of the message that starts the conversation. - + :returns: Long-running operation waiter for :class:`GenieMessage`. See :method:wait_get_message_genie_completed for more details. diff --git a/docs/workspace/dashboards/lakeview.rst b/docs/workspace/dashboards/lakeview.rst index c37479dcb..d9cdc1742 100644 --- a/docs/workspace/dashboards/lakeview.rst +++ b/docs/workspace/dashboards/lakeview.rst @@ -10,42 +10,42 @@ .. py:method:: create( [, dashboard: Optional[Dashboard]]) -> Dashboard Create dashboard. - + Create a draft dashboard. - + :param dashboard: :class:`Dashboard` (optional) - + :returns: :class:`Dashboard` .. py:method:: create_schedule(dashboard_id: str [, schedule: Optional[Schedule]]) -> Schedule Create dashboard schedule. - + :param dashboard_id: str UUID identifying the dashboard to which the schedule belongs. :param schedule: :class:`Schedule` (optional) - + :returns: :class:`Schedule` .. py:method:: create_subscription(dashboard_id: str, schedule_id: str [, subscription: Optional[Subscription]]) -> Subscription Create schedule subscription. - + :param dashboard_id: str UUID identifying the dashboard to which the subscription belongs. :param schedule_id: str UUID identifying the schedule to which the subscription belongs. :param subscription: :class:`Subscription` (optional) - + :returns: :class:`Subscription` .. py:method:: delete_schedule(dashboard_id: str, schedule_id: str [, etag: Optional[str]]) Delete dashboard schedule. - + :param dashboard_id: str UUID identifying the dashboard to which the schedule belongs. :param schedule_id: str @@ -53,14 +53,14 @@ :param etag: str (optional) The etag for the schedule. Optionally, it can be provided to verify that the schedule has not been modified from its last retrieval. - - + + .. py:method:: delete_subscription(dashboard_id: str, schedule_id: str, subscription_id: str [, etag: Optional[str]]) Delete schedule subscription. - + :param dashboard_id: str UUID identifying the dashboard which the subscription belongs. :param schedule_id: str @@ -70,64 +70,64 @@ :param etag: str (optional) The etag for the subscription. Can be optionally provided to ensure that the subscription has not been modified since the last read. - - + + .. py:method:: get(dashboard_id: str) -> Dashboard Get dashboard. - + Get a draft dashboard. - + :param dashboard_id: str UUID identifying the dashboard. - + :returns: :class:`Dashboard` .. py:method:: get_published(dashboard_id: str) -> PublishedDashboard Get published dashboard. - + Get the current published dashboard. - + :param dashboard_id: str UUID identifying the published dashboard. - + :returns: :class:`PublishedDashboard` .. py:method:: get_schedule(dashboard_id: str, schedule_id: str) -> Schedule Get dashboard schedule. - + :param dashboard_id: str UUID identifying the dashboard to which the schedule belongs. :param schedule_id: str UUID identifying the schedule. - + :returns: :class:`Schedule` .. py:method:: get_subscription(dashboard_id: str, schedule_id: str, subscription_id: str) -> Subscription Get schedule subscription. - + :param dashboard_id: str UUID identifying the dashboard which the subscription belongs. :param schedule_id: str UUID identifying the schedule which the subscription belongs. :param subscription_id: str UUID identifying the subscription. - + :returns: :class:`Subscription` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str], show_trashed: Optional[bool], view: Optional[DashboardView]]) -> Iterator[Dashboard] List dashboards. - + :param page_size: int (optional) The number of dashboards to return per page. :param page_token: str (optional) @@ -138,14 +138,14 @@ returned. :param view: :class:`DashboardView` (optional) `DASHBOARD_VIEW_BASIC`only includes summary metadata from the dashboard. - + :returns: Iterator over :class:`Dashboard` .. py:method:: list_schedules(dashboard_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[Schedule] List dashboard schedules. - + :param dashboard_id: str UUID identifying the dashboard to which the schedules belongs. :param page_size: int (optional) @@ -153,14 +153,14 @@ :param page_token: str (optional) A page token, received from a previous `ListSchedules` call. Use this to retrieve the subsequent page. - + :returns: Iterator over :class:`Schedule` .. py:method:: list_subscriptions(dashboard_id: str, schedule_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[Subscription] List schedule subscriptions. - + :param dashboard_id: str UUID identifying the dashboard which the subscriptions belongs. :param schedule_id: str @@ -170,16 +170,16 @@ :param page_token: str (optional) A page token, received from a previous `ListSubscriptions` call. Use this to retrieve the subsequent page. - + :returns: Iterator over :class:`Subscription` .. py:method:: migrate(source_dashboard_id: str [, display_name: Optional[str], parent_path: Optional[str], update_parameter_syntax: Optional[bool]]) -> Dashboard Migrate dashboard. - + Migrates a classic SQL dashboard to Lakeview. - + :param source_dashboard_id: str UUID of the dashboard to be migrated. :param display_name: str (optional) @@ -189,16 +189,16 @@ :param update_parameter_syntax: bool (optional) Flag to indicate if mustache parameter syntax ({{ param }}) should be auto-updated to named syntax (:param) when converting datasets in the dashboard. - + :returns: :class:`Dashboard` .. py:method:: publish(dashboard_id: str [, embed_credentials: Optional[bool], warehouse_id: Optional[str]]) -> PublishedDashboard Publish dashboard. - + Publish the current draft dashboard. - + :param dashboard_id: str UUID identifying the dashboard to be published. :param embed_credentials: bool (optional) @@ -206,56 +206,56 @@ embedded credentials will be used to execute the published dashboard's queries. :param warehouse_id: str (optional) The ID of the warehouse that can be used to override the warehouse which was set in the draft. - + :returns: :class:`PublishedDashboard` .. py:method:: trash(dashboard_id: str) Trash dashboard. - + Trash a dashboard. - + :param dashboard_id: str UUID identifying the dashboard. - - + + .. py:method:: unpublish(dashboard_id: str) Unpublish dashboard. - + Unpublish the dashboard. - + :param dashboard_id: str UUID identifying the published dashboard. - - + + .. py:method:: update(dashboard_id: str [, dashboard: Optional[Dashboard]]) -> Dashboard Update dashboard. - + Update a draft dashboard. - + :param dashboard_id: str UUID identifying the dashboard. :param dashboard: :class:`Dashboard` (optional) - + :returns: :class:`Dashboard` .. py:method:: update_schedule(dashboard_id: str, schedule_id: str [, schedule: Optional[Schedule]]) -> Schedule Update dashboard schedule. - + :param dashboard_id: str UUID identifying the dashboard to which the schedule belongs. :param schedule_id: str UUID identifying the schedule. :param schedule: :class:`Schedule` (optional) - + :returns: :class:`Schedule` \ No newline at end of file diff --git a/docs/workspace/dashboards/lakeview_embedded.rst b/docs/workspace/dashboards/lakeview_embedded.rst index 4c06031f5..c97b5d692 100644 --- a/docs/workspace/dashboards/lakeview_embedded.rst +++ b/docs/workspace/dashboards/lakeview_embedded.rst @@ -9,11 +9,11 @@ .. py:method:: get_published_dashboard_embedded(dashboard_id: str) Read a published dashboard in an embedded ui. - + Get the current published dashboard within an embedded context. - + :param dashboard_id: str UUID identifying the published dashboard. - - + + \ No newline at end of file diff --git a/docs/workspace/dashboards/query_execution.rst b/docs/workspace/dashboards/query_execution.rst index 5672183d9..f57d874ac 100644 --- a/docs/workspace/dashboards/query_execution.rst +++ b/docs/workspace/dashboards/query_execution.rst @@ -9,19 +9,19 @@ .. py:method:: cancel_published_query_execution(dashboard_name: str, dashboard_revision_id: str [, tokens: Optional[List[str]]]) -> CancelQueryExecutionResponse Cancel the results for the a query for a published, embedded dashboard. - + :param dashboard_name: str :param dashboard_revision_id: str :param tokens: List[str] (optional) Example: EC0A..ChAB7WCEn_4Qo4vkLqEbXsxxEgh3Y2pbWw45WhoQXgZSQo9aS5q2ZvFcbvbx9CgA-PAEAQ - + :returns: :class:`CancelQueryExecutionResponse` .. py:method:: execute_published_dashboard_query(dashboard_name: str, dashboard_revision_id: str [, override_warehouse_id: Optional[str]]) Execute a query for a published dashboard. - + :param dashboard_name: str Dashboard name and revision_id is required to retrieve PublishedDatasetDataModel which contains the list of datasets, warehouse_id, and embedded_credentials @@ -29,18 +29,18 @@ :param override_warehouse_id: str (optional) A dashboard schedule can override the warehouse used as compute for processing the published dashboard queries - - + + .. py:method:: poll_published_query_status(dashboard_name: str, dashboard_revision_id: str [, tokens: Optional[List[str]]]) -> PollQueryStatusResponse Poll the results for the a query for a published, embedded dashboard. - + :param dashboard_name: str :param dashboard_revision_id: str :param tokens: List[str] (optional) Example: EC0A..ChAB7WCEn_4Qo4vkLqEbXsxxEgh3Y2pbWw45WhoQXgZSQo9aS5q2ZvFcbvbx9CgA-PAEAQ - + :returns: :class:`PollQueryStatusResponse` \ No newline at end of file diff --git a/docs/workspace/files/dbfs.rst b/docs/workspace/files/dbfs.rst index c52d11bc8..3f214908d 100644 --- a/docs/workspace/files/dbfs.rst +++ b/docs/workspace/files/dbfs.rst @@ -10,31 +10,31 @@ .. py:method:: add_block(handle: int, data: str) Append data block. - + Appends a block of data to the stream specified by the input handle. If the handle does not exist, this call will throw an exception with ``RESOURCE_DOES_NOT_EXIST``. - + If the block of data exceeds 1 MB, this call will throw an exception with ``MAX_BLOCK_SIZE_EXCEEDED``. - + :param handle: int The handle on an open stream. :param data: str The base64-encoded data to append to the stream. This has a limit of 1 MB. - - + + .. py:method:: close(handle: int) Close the stream. - + Closes the stream specified by the input handle. If the handle does not exist, this call throws an exception with ``RESOURCE_DOES_NOT_EXIST``. - + :param handle: int The handle on an open stream. - - + + .. py:method:: copy(src: str, dst: str [, recursive: bool = False, overwrite: bool = False]) @@ -44,21 +44,21 @@ .. py:method:: create(path: str [, overwrite: Optional[bool]]) -> CreateResponse Open a stream. - + Opens a stream to write to a file and returns a handle to this stream. There is a 10 minute idle timeout on this handle. If a file or directory already exists on the given path and __overwrite__ is set to false, this call will throw an exception with ``RESOURCE_ALREADY_EXISTS``. - + A typical workflow for file upload would be: - + 1. Issue a ``create`` call and get a handle. 2. Issue one or more ``add-block`` calls with the handle you have. 3. Issue a ``close`` call with the handle you have. - + :param path: str The path of the new file. The path should be the absolute DBFS path. :param overwrite: bool (optional) The flag that specifies whether to overwrite existing file/files. - + :returns: :class:`CreateResponse` @@ -81,12 +81,12 @@ w = WorkspaceClient() - root = pathlib.Path(f'/tmp/{time.time_ns()}') + root = pathlib.Path(f"/tmp/{time.time_ns()}") f = io.BytesIO(b"some text data") - w.dbfs.upload(f'{root}/01', f) + w.dbfs.upload(f"{root}/01", f) - with w.dbfs.download(f'{root}/01') as f: + with w.dbfs.download(f"{root}/01") as f: assert f.read() == b"some text data" Download file from DBFS @@ -98,13 +98,13 @@ .. py:method:: get_status(path: str) -> FileInfo Get the information of a file or directory. - + Gets the file information for a file or directory. If the file or directory does not exist, this call throws an exception with `RESOURCE_DOES_NOT_EXIST`. - + :param path: str The path of the file or directory. The path should be the absolute DBFS path. - + :returns: :class:`FileInfo` @@ -130,18 +130,18 @@ .. py:method:: move(source_path: str, destination_path: str) Move a file. - + Moves a file from one location to another location within DBFS. If the source file does not exist, this call throws an exception with `RESOURCE_DOES_NOT_EXIST`. If a file already exists in the destination path, this call throws an exception with `RESOURCE_ALREADY_EXISTS`. If the given source path is a directory, this call always recursively moves all files. - + :param source_path: str The source path of the file or directory. The path should be the absolute DBFS path. :param destination_path: str The destination path of the file or directory. The path should be the absolute DBFS path. - - + + .. py:method:: move_(src: str, dst: str [, recursive: bool = False, overwrite: bool = False]) @@ -154,40 +154,40 @@ .. py:method:: put(path: str [, contents: Optional[str], overwrite: Optional[bool]]) Upload a file. - + Uploads a file through the use of multipart form post. It is mainly used for streaming uploads, but can also be used as a convenient single call for data upload. - + Alternatively you can pass contents as base64 string. - + The amount of data that can be passed (when not streaming) using the __contents__ parameter is limited to 1 MB. `MAX_BLOCK_SIZE_EXCEEDED` will be thrown if this limit is exceeded. - + If you want to upload large files, use the streaming upload. For details, see :method:dbfs/create, :method:dbfs/addBlock, :method:dbfs/close. - + :param path: str The path of the new file. The path should be the absolute DBFS path. :param contents: str (optional) This parameter might be absent, and instead a posted file will be used. :param overwrite: bool (optional) The flag that specifies whether to overwrite existing file/files. - - + + .. py:method:: read(path: str [, length: Optional[int], offset: Optional[int]]) -> ReadResponse Get the contents of a file. - + Returns the contents of a file. If the file does not exist, this call throws an exception with `RESOURCE_DOES_NOT_EXIST`. If the path is a directory, the read length is negative, or if the offset is negative, this call throws an exception with `INVALID_PARAMETER_VALUE`. If the read length exceeds 1 MB, this call throws an exception with `MAX_READ_SIZE_EXCEEDED`. - + If `offset + length` exceeds the number of bytes in a file, it reads the contents until the end of file. - + :param path: str The path of the file to read. The path should be the absolute DBFS path. :param length: int (optional) @@ -195,7 +195,7 @@ of 0.5 MB. :param offset: int (optional) The offset to read from in bytes. - + :returns: :class:`ReadResponse` diff --git a/docs/workspace/files/files.rst b/docs/workspace/files/files.rst index 0151fcce2..661396ad1 100644 --- a/docs/workspace/files/files.rst +++ b/docs/workspace/files/files.rst @@ -7,122 +7,122 @@ The Files API is a standard HTTP API that allows you to read, write, list, and delete files and directories by referring to their URI. The API makes working with file content as raw bytes easier and more efficient. - + The API supports [Unity Catalog volumes], where files and directories to operate on are specified using their volume URI path, which follows the format /Volumes/<catalog_name>/<schema_name>/<volume_name>/<path_to_file>. - + The Files API has two distinct endpoints, one for working with files (`/fs/files`) and another one for working with directories (`/fs/directories`). Both endpoints use the standard HTTP methods GET, HEAD, PUT, and DELETE to manage files and directories specified using their URI path. The path is always absolute. - + Some Files API client features are currently experimental. To enable them, set `enable_experimental_files_api_client = True` in your configuration profile or use the environment variable `DATABRICKS_ENABLE_EXPERIMENTAL_FILES_API_CLIENT=True`. - + [Unity Catalog volumes]: https://docs.databricks.com/en/connect/unity-catalog/volumes.html .. py:method:: create_directory(directory_path: str) Create a directory. - + Creates an empty directory. If necessary, also creates any parent directories of the new, empty directory (like the shell command `mkdir -p`). If called on an existing directory, returns a success response; this method is idempotent (it will succeed if the directory already exists). - + :param directory_path: str The absolute path of a directory. - - + + .. py:method:: delete(file_path: str) Delete a file. - + Deletes a file. If the request is successful, there is no response body. - + :param file_path: str The absolute path of the file. - - + + .. py:method:: delete_directory(directory_path: str) Delete a directory. - + Deletes an empty directory. - + To delete a non-empty directory, first delete all of its contents. This can be done by listing the directory contents and deleting each file and subdirectory recursively. - + :param directory_path: str The absolute path of a directory. - - + + .. py:method:: download(file_path: str) -> DownloadResponse Download a file. - + Downloads a file. The file contents are the response body. This is a standard HTTP file download, not a JSON RPC. It supports the Range and If-Unmodified-Since HTTP headers. - + :param file_path: str The absolute path of the file. - + :returns: :class:`DownloadResponse` .. py:method:: get_directory_metadata(directory_path: str) Get directory metadata. - + Get the metadata of a directory. The response HTTP headers contain the metadata. There is no response body. - + This method is useful to check if a directory exists and the caller has access to it. - + If you wish to ensure the directory exists, you can instead use `PUT`, which will create the directory if it does not exist, and is idempotent (it will succeed if the directory already exists). - + :param directory_path: str The absolute path of a directory. - - + + .. py:method:: get_metadata(file_path: str) -> GetMetadataResponse Get file metadata. - + Get the metadata of a file. The response HTTP headers contain the metadata. There is no response body. - + :param file_path: str The absolute path of the file. - + :returns: :class:`GetMetadataResponse` .. py:method:: list_directory_contents(directory_path: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[DirectoryEntry] List directory contents. - + Returns the contents of a directory. If there is no directory at the specified path, the API returns a HTTP 404 error. - + :param directory_path: str The absolute path of a directory. :param page_size: int (optional) The maximum number of directory entries to return. The response may contain fewer entries. If the response contains a `next_page_token`, there may be more entries, even if fewer than `page_size` entries are in the response. - + We recommend not to set this value unless you are intentionally listing less than the complete directory contents. - + If unspecified, at most 1000 directory entries will be returned. The maximum value is 1000. Values above 1000 will be coerced to 1000. :param page_token: str (optional) @@ -132,24 +132,24 @@ request. To list all of the entries in a directory, it is necessary to continue requesting pages of entries until the response contains no `next_page_token`. Note that the number of entries returned must not be used to determine when the listing is complete. - + :returns: Iterator over :class:`DirectoryEntry` .. py:method:: upload(file_path: str, contents: BinaryIO [, overwrite: Optional[bool]]) Upload a file. - + Uploads a file of up to 5 GiB. The file contents should be sent as the request body as raw bytes (an octet stream); do not encode or otherwise modify the bytes before sending. The contents of the resulting file will be exactly the bytes sent in the request body. If the request is successful, there is no response body. - + :param file_path: str The absolute path of the file. :param contents: BinaryIO :param overwrite: bool (optional) If true, an existing file will be overwritten. - - + + \ No newline at end of file diff --git a/docs/workspace/iam/access_control.rst b/docs/workspace/iam/access_control.rst index a5f1feeda..930af105a 100644 --- a/docs/workspace/iam/access_control.rst +++ b/docs/workspace/iam/access_control.rst @@ -9,7 +9,7 @@ .. py:method:: check_policy(actor: Actor, permission: str, resource: str, consistency_token: ConsistencyToken, authz_identity: RequestAuthzIdentity [, resource_info: Optional[ResourceInfo]]) -> CheckPolicyResponse Check access policy to a resource. - + :param actor: :class:`Actor` :param permission: str :param resource: str @@ -18,6 +18,6 @@ :param consistency_token: :class:`ConsistencyToken` :param authz_identity: :class:`RequestAuthzIdentity` :param resource_info: :class:`ResourceInfo` (optional) - + :returns: :class:`CheckPolicyResponse` \ No newline at end of file diff --git a/docs/workspace/iam/account_access_control_proxy.rst b/docs/workspace/iam/account_access_control_proxy.rst index 3265b29cc..3338671bb 100644 --- a/docs/workspace/iam/account_access_control_proxy.rst +++ b/docs/workspace/iam/account_access_control_proxy.rst @@ -11,23 +11,23 @@ .. py:method:: get_assignable_roles_for_resource(resource: str) -> GetAssignableRolesForResourceResponse Get assignable roles for a resource. - + Gets all the roles that can be granted on an account-level resource. A role is grantable if the rule set on the resource can contain an access rule of the role. - + :param resource: str The resource name for which assignable roles will be listed. - + :returns: :class:`GetAssignableRolesForResourceResponse` .. py:method:: get_rule_set(name: str, etag: str) -> RuleSetResponse Get a rule set. - + Get a rule set by its name. A rule set is always attached to a resource and contains a list of access rules on the said resource. Currently only a default rule set for each resource is supported. - + :param name: str The ruleset name associated with the request. :param etag: str @@ -37,20 +37,20 @@ modify -> write pattern to perform rule set updates in order to avoid race conditions that is get an etag from a GET rule set request, and pass it with the PUT update request to identify the rule set version you are updating. - + :returns: :class:`RuleSetResponse` .. py:method:: update_rule_set(name: str, rule_set: RuleSetUpdateRequest) -> RuleSetResponse Update a rule set. - + Replace the rules of a rule set. First, use a GET rule set request to read the current version of the rule set before modifying it. This pattern helps prevent conflicts between concurrent updates. - + :param name: str Name of the rule set. :param rule_set: :class:`RuleSetUpdateRequest` - + :returns: :class:`RuleSetResponse` \ No newline at end of file diff --git a/docs/workspace/iam/current_user.rst b/docs/workspace/iam/current_user.rst index 47ef1eff3..1df3adf9f 100644 --- a/docs/workspace/iam/current_user.rst +++ b/docs/workspace/iam/current_user.rst @@ -20,8 +20,8 @@ me2 = w.current_user.me() Get current user info. - + Get details about the current method caller's identity. - + :returns: :class:`User` \ No newline at end of file diff --git a/docs/workspace/iam/groups.rst b/docs/workspace/iam/groups.rst index ef32112c8..8eb4ccbe2 100644 --- a/docs/workspace/iam/groups.rst +++ b/docs/workspace/iam/groups.rst @@ -6,7 +6,7 @@ Groups simplify identity management, making it easier to assign access to Databricks workspace, data, and other securable objects. - + It is best practice to assign access to workspaces and access-control policies in Unity Catalog to groups, instead of to users individually. All Databricks workspace identities can be assigned as members of groups, and members inherit permissions that are assigned to their group. @@ -24,21 +24,21 @@ w = WorkspaceClient() - group = w.groups.create(display_name=f'sdk-{time.time_ns()}') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}") # cleanup w.groups.delete(id=group.id) Create a new group. - + Creates a group in the Databricks workspace with a unique name, using the supplied group details. - + :param display_name: str (optional) String that represents a human-readable group name :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the group. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -51,7 +51,7 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`GroupSchema`] (optional) The schema of the group. - + :returns: :class:`Group` @@ -68,18 +68,18 @@ w = WorkspaceClient() - group = w.groups.create(display_name=f'sdk-{time.time_ns()}') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}") w.groups.delete(id=group.id) Delete a group. - + Deletes a group from the Databricks workspace. - + :param id: str Unique ID for a group in the Databricks workspace. - - + + .. py:method:: get(id: str) -> Group @@ -95,7 +95,7 @@ w = WorkspaceClient() - group = w.groups.create(display_name=f'sdk-{time.time_ns()}') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}") fetch = w.groups.get(id=group.id) @@ -103,21 +103,21 @@ w.groups.delete(id=group.id) Get group details. - + Gets the information for a specific group in the Databricks workspace. - + :param id: str Unique ID for a group in the Databricks workspace. - + :returns: :class:`Group` .. py:method:: list( [, attributes: Optional[str], count: Optional[int], excluded_attributes: Optional[str], filter: Optional[str], sort_by: Optional[str], sort_order: Optional[ListSortOrder], start_index: Optional[int]]) -> Iterator[Group] List group details. - + Gets all details of the groups associated with the Databricks workspace. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -129,7 +129,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. @@ -137,7 +137,7 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`Group` @@ -149,23 +149,32 @@ .. code-block:: import time + from databricks.sdk import WorkspaceClient from databricks.sdk.service import iam w = WorkspaceClient() - group = w.groups.create(display_name=f'sdk-{time.time_ns()}-group') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}-group") user = w.users.create( - display_name=f'sdk-{time.time_ns()}-user', user_name=f'sdk-{time.time_ns()}@example.com') + display_name=f"sdk-{time.time_ns()}-user", + user_name=f"sdk-{time.time_ns()}@example.com", + ) w.groups.patch( id=group.id, - operations=[iam.Patch( - op=iam.PatchOp.ADD, - value={"members": [{ - "value": user.id, - }]}, - )], + operations=[ + iam.Patch( + op=iam.PatchOp.ADD, + value={ + "members": [ + { + "value": user.id, + } + ] + }, + ) + ], schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], ) @@ -174,24 +183,24 @@ w.groups.delete(id=group.id) Update group details. - + Partially updates the details of a group. - + :param id: str Unique ID for a group in the Databricks workspace. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: update(id: str [, display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], members: Optional[List[ComplexValue]], meta: Optional[ResourceMeta], roles: Optional[List[ComplexValue]], schemas: Optional[List[GroupSchema]]]) Replace a group. - + Updates the details of a group by replacing the entire group entity. - + :param id: str Databricks group ID :param display_name: str (optional) @@ -199,7 +208,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the group. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -210,6 +219,6 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`GroupSchema`] (optional) The schema of the group. - - + + \ No newline at end of file diff --git a/docs/workspace/iam/permission_migration.rst b/docs/workspace/iam/permission_migration.rst index 8eef6e0e1..248b1b80d 100644 --- a/docs/workspace/iam/permission_migration.rst +++ b/docs/workspace/iam/permission_migration.rst @@ -9,7 +9,7 @@ .. py:method:: migrate_permissions(workspace_id: int, from_workspace_group_name: str, to_account_group_name: str [, size: Optional[int]]) -> MigratePermissionsResponse Migrate Permissions. - + :param workspace_id: int WorkspaceId of the associated workspace where the permission migration will occur. :param from_workspace_group_name: str @@ -18,6 +18,6 @@ The name of the account group that permissions will be migrated to. :param size: int (optional) The maximum number of permissions that will be migrated. - + :returns: :class:`MigratePermissionsResponse` \ No newline at end of file diff --git a/docs/workspace/iam/permissions.rst b/docs/workspace/iam/permissions.rst index bf8f8e77f..8d504eb37 100644 --- a/docs/workspace/iam/permissions.rst +++ b/docs/workspace/iam/permissions.rst @@ -6,52 +6,52 @@ Permissions API are used to create read, write, edit, update and manage access for various users on different objects and endpoints. - + * **[Apps permissions](:service:apps)** — Manage which users can manage or use apps. - + * **[Cluster permissions](:service:clusters)** — Manage which users can manage, restart, or attach to clusters. - + * **[Cluster policy permissions](:service:clusterpolicies)** — Manage which users can use cluster policies. - + * **[Delta Live Tables pipeline permissions](:service:pipelines)** — Manage which users can view, manage, run, cancel, or own a Delta Live Tables pipeline. - + * **[Job permissions](:service:jobs)** — Manage which users can view, manage, trigger, cancel, or own a job. - + * **[MLflow experiment permissions](:service:experiments)** — Manage which users can read, edit, or manage MLflow experiments. - + * **[MLflow registered model permissions](:service:modelregistry)** — Manage which users can read, edit, or manage MLflow registered models. - + * **[Password permissions](:service:users)** — Manage which users can use password login when SSO is enabled. - + * **[Instance Pool permissions](:service:instancepools)** — Manage which users can manage or attach to pools. - + * **[Repo permissions](repos)** — Manage which users can read, run, edit, or manage a repo. - + * **[Serving endpoint permissions](:service:servingendpoints)** — Manage which users can view, query, or manage a serving endpoint. - + * **[SQL warehouse permissions](:service:warehouses)** — Manage which users can use or manage SQL warehouses. - + * **[Token permissions](:service:tokenmanagement)** — Manage which users can create or use tokens. - + * **[Workspace object permissions](:service:workspace)** — Manage which users can read, run, edit, or manage alerts, dbsql-dashboards, directories, files, notebooks and queries. - + For the mapping of the required permissions for specific actions or abilities and other important information, see [Access Control]. - + Note that to manage access control on service principals, use **[Account Access Control Proxy](:service:accountaccesscontrolproxy)**. - + [Access Control]: https://docs.databricks.com/security/auth-authz/access-control/index.html .. py:method:: get(request_object_type: str, request_object_id: str) -> ObjectPermissions @@ -67,25 +67,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" obj = w.workspace.get_status(path=notebook_path) - levels = w.permissions.get_permission_levels(request_object_type="notebooks", - request_object_id="%d" % (obj.object_id)) + levels = w.permissions.get_permission_levels(request_object_type="notebooks", request_object_id="%d" % (obj.object_id)) Get object permissions. - + Gets the permissions of an object. Objects can inherit permissions from their parent objects or root object. - + :param request_object_type: str The type of the request object. Can be one of the following: alerts, authorization, clusters, cluster-policies, dashboards, dbsql-dashboards, directories, experiments, files, instance-pools, jobs, notebooks, pipelines, queries, registered-models, repos, serving-endpoints, or warehouses. :param request_object_id: str The id of the request object. - + :returns: :class:`ObjectPermissions` @@ -102,22 +101,21 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" obj = w.workspace.get_status(path=notebook_path) - levels = w.permissions.get_permission_levels(request_object_type="notebooks", - request_object_id="%d" % (obj.object_id)) + levels = w.permissions.get_permission_levels(request_object_type="notebooks", request_object_id="%d" % (obj.object_id)) Get object permission levels. - + Gets the permission levels that a user can have on an object. - + :param request_object_type: str :param request_object_id: str - + :returns: :class:`GetPermissionLevelsResponse` @@ -135,28 +133,32 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - group = w.groups.create(display_name=f'sdk-{time.time_ns()}') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}") obj = w.workspace.get_status(path=notebook_path) - _ = w.permissions.set(request_object_type="notebooks", - request_object_id="%d" % (obj.object_id), - access_control_list=[ - iam.AccessControlRequest(group_name=group.display_name, - permission_level=iam.PermissionLevel.CAN_RUN) - ]) + _ = w.permissions.set( + request_object_type="notebooks", + request_object_id="%d" % (obj.object_id), + access_control_list=[ + iam.AccessControlRequest( + group_name=group.display_name, + permission_level=iam.PermissionLevel.CAN_RUN, + ) + ], + ) # cleanup w.groups.delete(id=group.id) Set object permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their parent objects or root object. - + :param request_object_type: str The type of the request object. Can be one of the following: alerts, authorization, clusters, cluster-policies, dashboards, dbsql-dashboards, directories, experiments, files, instance-pools, @@ -164,17 +166,17 @@ :param request_object_id: str The id of the request object. :param access_control_list: List[:class:`AccessControlRequest`] (optional) - + :returns: :class:`ObjectPermissions` .. py:method:: update(request_object_type: str, request_object_id: str [, access_control_list: Optional[List[AccessControlRequest]]]) -> ObjectPermissions Update object permissions. - + Updates the permissions on an object. Objects can inherit permissions from their parent objects or root object. - + :param request_object_type: str The type of the request object. Can be one of the following: alerts, authorization, clusters, cluster-policies, dashboards, dbsql-dashboards, directories, experiments, files, instance-pools, @@ -182,6 +184,6 @@ :param request_object_id: str The id of the request object. :param access_control_list: List[:class:`AccessControlRequest`] (optional) - + :returns: :class:`ObjectPermissions` \ No newline at end of file diff --git a/docs/workspace/iam/service_principals.rst b/docs/workspace/iam/service_principals.rst index 0fb8ca643..ec893c807 100644 --- a/docs/workspace/iam/service_principals.rst +++ b/docs/workspace/iam/service_principals.rst @@ -26,16 +26,18 @@ groups = w.groups.group_display_name_to_id_map(iam.ListGroupsRequest()) - spn = w.service_principals.create(display_name=f'sdk-{time.time_ns()}', - groups=[iam.ComplexValue(value=groups["admins"])]) + spn = w.service_principals.create( + display_name=f"sdk-{time.time_ns()}", + groups=[iam.ComplexValue(value=groups["admins"])], + ) # cleanup w.service_principals.delete(id=spn.id) Create a service principal. - + Creates a new service principal in the Databricks workspace. - + :param active: bool (optional) If this user is active :param application_id: str (optional) @@ -45,7 +47,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the service principal. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -55,20 +57,20 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`ServicePrincipalSchema`] (optional) The schema of the List response. - + :returns: :class:`ServicePrincipal` .. py:method:: delete(id: str) Delete a service principal. - + Delete a single service principal in the Databricks workspace. - + :param id: str Unique ID for a service principal in the Databricks workspace. - - + + .. py:method:: get(id: str) -> ServicePrincipal @@ -84,7 +86,7 @@ w = WorkspaceClient() - created = w.service_principals.create(display_name=f'sdk-{time.time_ns()}') + created = w.service_principals.create(display_name=f"sdk-{time.time_ns()}") by_id = w.service_principals.get(id=created.id) @@ -92,12 +94,12 @@ w.service_principals.delete(id=created.id) Get service principal details. - + Gets the details for a single service principal define in the Databricks workspace. - + :param id: str Unique ID for a service principal in the Databricks workspace. - + :returns: :class:`ServicePrincipal` @@ -116,9 +118,9 @@ all = w.service_principals.list(iam.ListServicePrincipalsRequest()) List service principals. - + Gets the set of service principals associated with a Databricks workspace. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -130,7 +132,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. @@ -138,7 +140,7 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`ServicePrincipal` @@ -156,28 +158,30 @@ w = WorkspaceClient() - created = w.service_principals.create(display_name=f'sdk-{time.time_ns()}') + created = w.service_principals.create(display_name=f"sdk-{time.time_ns()}") by_id = w.service_principals.get(id=created.id) - w.service_principals.patch(id=by_id.id, - operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], - schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP]) + w.service_principals.patch( + id=by_id.id, + operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], + schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], + ) # cleanup w.service_principals.delete(id=created.id) Update service principal details. - + Partially updates the details of a single service principal in the Databricks workspace. - + :param id: str Unique ID for a service principal in the Databricks workspace. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: update(id: str [, active: Optional[bool], application_id: Optional[str], display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], roles: Optional[List[ComplexValue]], schemas: Optional[List[ServicePrincipalSchema]]]) @@ -194,21 +198,23 @@ w = WorkspaceClient() - created = w.service_principals.create(display_name=f'sdk-{time.time_ns()}') + created = w.service_principals.create(display_name=f"sdk-{time.time_ns()}") - w.service_principals.update(id=created.id, - display_name=f'sdk-{time.time_ns()}', - roles=[iam.ComplexValue(value="xyz")]) + w.service_principals.update( + id=created.id, + display_name=f"sdk-{time.time_ns()}", + roles=[iam.ComplexValue(value="xyz")], + ) # cleanup w.service_principals.delete(id=created.id) Replace service principal. - + Updates the details of a single service principal. - + This action replaces the existing service principal with the same name. - + :param id: str Databricks service principal ID. :param active: bool (optional) @@ -220,7 +226,7 @@ :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the service principal. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) @@ -228,6 +234,6 @@ Corresponds to AWS instance profile/arn role. :param schemas: List[:class:`ServicePrincipalSchema`] (optional) The schema of the List response. - - + + \ No newline at end of file diff --git a/docs/workspace/iam/users.rst b/docs/workspace/iam/users.rst index 616ef7b86..5edacca5f 100644 --- a/docs/workspace/iam/users.rst +++ b/docs/workspace/iam/users.rst @@ -5,7 +5,7 @@ .. py:class:: UsersAPI User identities recognized by Databricks and represented by email addresses. - + Databricks recommends using SCIM provisioning to sync users and groups automatically from your identity provider to your Databricks workspace. SCIM streamlines onboarding a new employee or team by using your identity provider to create users and groups in Databricks workspace and give them the proper level of @@ -27,26 +27,29 @@ w = WorkspaceClient() - user = w.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = w.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) Create a new user. - + Creates a new user in the Databricks workspace. This new user will also be added to the Databricks account. - + :param active: bool (optional) If this user is active :param display_name: str (optional) String that represents a concatenation of given and family names. For example `John Smith`. This field cannot be updated through the Workspace SCIM APIs when [identity federation is enabled]. Use Account SCIM APIs to update `displayName`. - + [identity federation is enabled]: https://docs.databricks.com/administration-guide/users-groups/best-practices.html#enable-identity-federation :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the user. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. @@ -61,7 +64,7 @@ The schema of the user. :param user_name: str (optional) Email address of the Databricks user. - + :returns: :class:`User` @@ -78,19 +81,19 @@ w = WorkspaceClient() - other_owner = w.users.create(user_name=f'sdk-{time.time_ns()}@example.com') + other_owner = w.users.create(user_name=f"sdk-{time.time_ns()}@example.com") w.users.delete(id=other_owner.id) Delete a user. - + Deletes a user. Deleting a user from a Databricks workspace also removes objects associated with the user. - + :param id: str Unique ID for a user in the Databricks workspace. - - + + .. py:method:: get(id: str [, attributes: Optional[str], count: Optional[int], excluded_attributes: Optional[str], filter: Optional[str], sort_by: Optional[str], sort_order: Optional[GetSortOrder], start_index: Optional[int]]) -> User @@ -106,14 +109,17 @@ w = WorkspaceClient() - user = w.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = w.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) fetch = w.users.get(id=user.id) Get user details. - + Gets information for a specific user in Databricks workspace. - + :param id: str Unique ID for a user in the Databricks workspace. :param attributes: str (optional) @@ -127,7 +133,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. Multi-part paths are supported. For example, `userName`, @@ -136,25 +142,25 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: :class:`User` .. py:method:: get_permission_levels() -> GetPasswordPermissionLevelsResponse Get password permission levels. - + Gets the permission levels that a user can have on an object. - + :returns: :class:`GetPasswordPermissionLevelsResponse` .. py:method:: get_permissions() -> PasswordPermissions Get password permissions. - + Gets the permissions of all passwords. Passwords can inherit permissions from their root object. - + :returns: :class:`PasswordPermissions` @@ -170,14 +176,16 @@ w = WorkspaceClient() - all_users = w.users.list(attributes="id,userName", - sort_by="userName", - sort_order=iam.ListSortOrder.DESCENDING) + all_users = w.users.list( + attributes="id,userName", + sort_by="userName", + sort_order=iam.ListSortOrder.DESCENDING, + ) List users. - + Gets details for all the users associated with a Databricks workspace. - + :param attributes: str (optional) Comma-separated list of attributes to return in response. :param count: int (optional) @@ -189,7 +197,7 @@ contains(`co`), starts with(`sw`) and not equals(`ne`). Additionally, simple expressions can be formed using logical operators - `and` and `or`. The [SCIM RFC] has more details but we currently only support simple expressions. - + [SCIM RFC]: https://tools.ietf.org/html/rfc7644#section-3.4.2.2 :param sort_by: str (optional) Attribute to sort the results. Multi-part paths are supported. For example, `userName`, @@ -198,7 +206,7 @@ The order to sort the results. :param start_index: int (optional) Specifies the index of the first result. First item is number 1. - + :returns: Iterator over :class:`User` @@ -216,34 +224,39 @@ w = WorkspaceClient() - user = w.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = w.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) - w.users.patch(id=user.id, - operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], - schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP]) + w.users.patch( + id=user.id, + operations=[iam.Patch(op=iam.PatchOp.REPLACE, path="active", value="false")], + schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP], + ) Update user details. - + Partially updates a user resource by applying the supplied operations on specific user attributes. - + :param id: str Unique ID for a user in the Databricks workspace. :param operations: List[:class:`Patch`] (optional) :param schemas: List[:class:`PatchSchema`] (optional) The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]. - - + + .. py:method:: set_permissions( [, access_control_list: Optional[List[PasswordAccessControlRequest]]]) -> PasswordPermissions Set password permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param access_control_list: List[:class:`PasswordAccessControlRequest`] (optional) - + :returns: :class:`PasswordPermissions` @@ -260,14 +273,17 @@ w = WorkspaceClient() - user = w.users.create(display_name=f'sdk-{time.time_ns()}', user_name=f'sdk-{time.time_ns()}@example.com') + user = w.users.create( + display_name=f"sdk-{time.time_ns()}", + user_name=f"sdk-{time.time_ns()}@example.com", + ) w.users.update(id=user.id, user_name=user.user_name, active=True) Replace a user. - + Replaces a user's information with the data supplied in request. - + :param id: str Databricks user ID. This is automatically set by Databricks. Any value provided by the client will be ignored. @@ -277,13 +293,13 @@ String that represents a concatenation of given and family names. For example `John Smith`. This field cannot be updated through the Workspace SCIM APIs when [identity federation is enabled]. Use Account SCIM APIs to update `displayName`. - + [identity federation is enabled]: https://docs.databricks.com/administration-guide/users-groups/best-practices.html#enable-identity-federation :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param entitlements: List[:class:`ComplexValue`] (optional) Entitlements assigned to the user. See [assigning entitlements] for a full list of supported values. - + [assigning entitlements]: https://docs.databricks.com/administration-guide/users-groups/index.html#assigning-entitlements :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. @@ -295,17 +311,17 @@ The schema of the user. :param user_name: str (optional) Email address of the Databricks user. - - + + .. py:method:: update_permissions( [, access_control_list: Optional[List[PasswordAccessControlRequest]]]) -> PasswordPermissions Update password permissions. - + Updates the permissions on all passwords. Passwords can inherit permissions from their root object. - + :param access_control_list: List[:class:`PasswordAccessControlRequest`] (optional) - + :returns: :class:`PasswordPermissions` \ No newline at end of file diff --git a/docs/workspace/jobs/jobs.rst b/docs/workspace/jobs/jobs.rst index 36f7d7d39..923b05901 100644 --- a/docs/workspace/jobs/jobs.rst +++ b/docs/workspace/jobs/jobs.rst @@ -1,21 +1,21 @@ -``w.jobs``: Jobs (2.2) -====================== +``w.jobs``: Jobs +================ .. currentmodule:: databricks.sdk.service.jobs .. py:class:: JobsExt The Jobs API allows you to create, edit, and delete jobs. - + You can use a Databricks job to run a data processing or data analysis task in a Databricks cluster with scalable resources. Your job can consist of a single task or can be a large, multi-task workflow with complex dependencies. Databricks manages the task orchestration, cluster management, monitoring, and error reporting for all of your jobs. You can run your jobs immediately or periodically through an easy-to-use scheduling system. You can implement job tasks using notebooks, JARS, Delta Live Tables pipelines, or Python, Scala, Spark submit, and Java applications. - + You should never hard code secrets or store them in plain text. Use the [Secrets CLI] to manage secrets in the [Databricks CLI]. Use the [Secrets utility] to reference secrets in notebooks and jobs. - + [Databricks CLI]: https://docs.databricks.com/dev-tools/cli/index.html [Secrets CLI]: https://docs.databricks.com/dev-tools/cli/secrets-cli.html [Secrets utility]: https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-secrets @@ -35,19 +35,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) w.jobs.cancel_all_runs(job_id=created_job.job_id) @@ -55,17 +60,17 @@ w.jobs.delete(job_id=created_job.job_id) Cancel all runs of a job. - + Cancels all active runs of a job. The runs are canceled asynchronously, so it doesn't prevent new runs from being started. - + :param all_queued_runs: bool (optional) Optional boolean parameter to cancel all queued runs. If no job_id is provided, all queued runs in the workspace are canceled. :param job_id: int (optional) The canonical identifier of the job to cancel all runs of. - - + + .. py:method:: cancel_run(run_id: int) -> Wait[Run] @@ -83,19 +88,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_now_response = w.jobs.run_now(job_id=created_job.job_id) @@ -105,13 +115,13 @@ w.jobs.delete(job_id=created_job.job_id) Cancel a run. - + Cancels a job run or a task run. The run is canceled asynchronously, so it may still be running when this request completes. - + :param run_id: int This field is required. - + :returns: Long-running operation waiter for :class:`Run`. See :method:wait_get_run_job_terminated_or_skipped for more details. @@ -135,27 +145,32 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) # cleanup w.jobs.delete(job_id=created_job.job_id) Create a new job. - + Create a new job. - + :param access_control_list: List[:class:`JobAccessControlRequest`] (optional) List of permissions to set on the job. :param budget_policy_id: str (optional) @@ -171,7 +186,7 @@ An optional description for the job. The maximum length is 27700 characters in UTF-8 encoding. :param edit_mode: :class:`JobEditMode` (optional) Edit mode of the job. - + * `UI_LOCKED`: The job is in a locked UI state and cannot be modified. * `EDITABLE`: The job is in an editable state and can be modified. :param email_notifications: :class:`JobEmailNotifications` (optional) @@ -188,10 +203,10 @@ :param git_source: :class:`GitSource` (optional) An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - + If `git_source` is set, these tasks retrieve the file from the remote repository by default. However, this behavior can be overridden by setting `source` to `WORKSPACE` on the task. - + Note: dbt and SQL File tasks support only version-controlled sources. If dbt or SQL File tasks are used, `git_source` must be defined on the job. :param health: :class:`JobsHealthRules` (optional) @@ -224,7 +239,7 @@ :param run_as: :class:`JobRunAs` (optional) Write-only setting. Specifies the user or service principal that the job runs as. If not specified, the job runs as the user who created the job. - + Either `user_name` or `service_principal_name` should be specified. If not, an error is thrown. :param schedule: :class:`CronSchedule` (optional) An optional periodic schedule for this job. The default behavior is that the job only runs when @@ -245,32 +260,32 @@ `runNow`. :param webhook_notifications: :class:`WebhookNotifications` (optional) A collection of system notification IDs to notify when runs of this job begin or complete. - + :returns: :class:`CreateResponse` .. py:method:: delete(job_id: int) Delete a job. - + Deletes a job. - + :param job_id: int The canonical identifier of the job to delete. This field is required. - - + + .. py:method:: delete_run(run_id: int) Delete a job run. - + Deletes a non-active run. Returns an error if the run is active. - + :param run_id: int ID of the run to delete. - - + + .. py:method:: export_run(run_id: int [, views_to_export: Optional[ViewsToExport]]) -> ExportRunOutput @@ -288,19 +303,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_by_id = w.jobs.run_now(job_id=created_job.job_id).result() @@ -310,18 +330,18 @@ w.jobs.delete(job_id=created_job.job_id) Export and retrieve a job run. - + Export and retrieve the job run task. - + :param run_id: int The canonical identifier for the run. This field is required. :param views_to_export: :class:`ViewsToExport` (optional) Which views to export (CODE, DASHBOARDS, or ALL). Defaults to CODE. - + :returns: :class:`ExportRunOutput` - .. py:method:: get(job_id: int [, page_token: Optional[str]]) -> Job + .. py:method:: get(job_id: int [, page_token: str]) -> Job Usage: @@ -336,17 +356,22 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - run = w.jobs.submit(run_name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.SubmitTask(existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key=f'sdk-{time.time_ns()}') - ]).result() + run = w.jobs.submit( + run_name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.SubmitTask( + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key=f"sdk-{time.time_ns()}", + ) + ], + ).result() output = w.jobs.get_run_output(run_id=run.tasks[0].run_id) @@ -354,44 +379,40 @@ w.jobs.delete_run(run_id=run.run_id) Get a single job. - - Retrieves the details for a single job. - - In Jobs API 2.2, requests for a single job support pagination of `tasks` and `job_clusters` when - either exceeds 100 elements. Use the `next_page_token` field to check for more results and pass its - value as the `page_token` in subsequent requests. Arrays with fewer than 100 elements in a page will - be empty on later pages. - + + Retrieves the details for a single job. If the job has multiple pages of tasks, job_clusters, parameters or environments, + it will paginate through all pages and aggregate the results. + :param job_id: int The canonical identifier of the job to retrieve information about. This field is required. :param page_token: str (optional) Use `next_page_token` returned from the previous GetJob to request the next page of the job's sub-resources. - + :returns: :class:`Job` .. py:method:: get_permission_levels(job_id: str) -> GetJobPermissionLevelsResponse Get job permission levels. - + Gets the permission levels that a user can have on an object. - + :param job_id: str The job for which to get or manage permissions. - + :returns: :class:`GetJobPermissionLevelsResponse` .. py:method:: get_permissions(job_id: str) -> JobPermissions Get job permissions. - + Gets the permissions of a job. Jobs can inherit permissions from their root object. - + :param job_id: str The job for which to get or manage permissions. - + :returns: :class:`JobPermissions` @@ -410,17 +431,22 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - run = w.jobs.submit(run_name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.SubmitTask(existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key=f'sdk-{time.time_ns()}') - ]).result() + run = w.jobs.submit( + run_name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.SubmitTask( + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key=f"sdk-{time.time_ns()}", + ) + ], + ).result() output = w.jobs.get_run_output(run_id=run.tasks[0].run_id) @@ -459,17 +485,22 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - run = w.jobs.submit(run_name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.SubmitTask(existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key=f'sdk-{time.time_ns()}') - ]).result() + run = w.jobs.submit( + run_name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.SubmitTask( + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key=f"sdk-{time.time_ns()}", + ) + ], + ).result() output = w.jobs.get_run_output(run_id=run.tasks[0].run_id) @@ -477,23 +508,23 @@ w.jobs.delete_run(run_id=run.run_id) Get the output for a single run. - + Retrieve the output and metadata of a single task run. When a notebook task returns a value through the `dbutils.notebook.exit()` call, you can use this endpoint to retrieve that value. Databricks restricts this API to returning the first 5 MB of the output. To return a larger result, you can store job results in a cloud storage service. - + This endpoint validates that the __run_id__ parameter is valid and returns an HTTP status code 400 if the __run_id__ parameter is invalid. Runs are automatically removed after 60 days. If you to want to reference them beyond 60 days, you must save old run results before they expire. - + :param run_id: int The canonical identifier for the run. - + :returns: :class:`RunOutput` - .. py:method:: list( [, expand_tasks: Optional[bool], limit: Optional[int], name: Optional[str], offset: Optional[int], page_token: Optional[str]]) -> Iterator[BaseJob] + .. py:method:: list( [, expand_tasks: bool, limit: int, name: str, offset: int, page_token: str]) -> BaseJob Usage: @@ -508,19 +539,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_list = w.jobs.list_runs(job_id=created_job.job_id) @@ -528,9 +564,10 @@ w.jobs.delete(job_id=created_job.job_id) List jobs. - - Retrieves a list of jobs. - + + Retrieves a list of jobs. If the job has multiple pages of tasks, job_clusters, parameters or environments, + it will paginate through all pages and aggregate the results. + :param expand_tasks: bool (optional) Whether to include task and cluster details in the response. Note that in API 2.2, only the first 100 elements will be shown. Use :method:jobs/get to paginate through all tasks and clusters. @@ -545,11 +582,11 @@ :param page_token: str (optional) Use `next_page_token` or `prev_page_token` returned from the previous request to list the next or previous page of jobs respectively. - + :returns: Iterator over :class:`BaseJob` - .. py:method:: list_runs( [, active_only: Optional[bool], completed_only: Optional[bool], expand_tasks: Optional[bool], job_id: Optional[int], limit: Optional[int], offset: Optional[int], page_token: Optional[str], run_type: Optional[RunType], start_time_from: Optional[int], start_time_to: Optional[int]]) -> Iterator[BaseRun] + .. py:method:: list_runs( [, active_only: bool, completed_only: bool, expand_tasks: bool, job_id: int, limit: int, offset: int, page_token: str, run_type: RunType, start_time_from: int, start_time_to: int]) -> BaseRun Usage: @@ -564,19 +601,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_list = w.jobs.list_runs(job_id=created_job.job_id) @@ -584,9 +626,10 @@ w.jobs.delete(job_id=created_job.job_id) List job runs. - - List runs in descending order by start time. - + + List runs in descending order by start time. If the job has multiple pages of tasks, job_clusters, parameters or repair history, + it will paginate through all pages and aggregate the results. + :param active_only: bool (optional) If active_only is `true`, only active runs are included in the results; otherwise, lists both active and completed runs. An active run is a run in the `QUEUED`, `PENDING`, `RUNNING`, or `TERMINATING`. @@ -616,7 +659,7 @@ :param start_time_to: int (optional) Show runs that started _at or before_ this value. The value must be a UTC timestamp in milliseconds. Can be combined with _start_time_from_ to filter by a time range. - + :returns: Iterator over :class:`BaseRun` @@ -635,35 +678,42 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_now_response = w.jobs.run_now(job_id=created_job.job_id) cancelled_run = w.jobs.cancel_run(run_id=run_now_response.response.run_id).result() - repaired_run = w.jobs.repair_run(rerun_tasks=[cancelled_run.tasks[0].task_key], - run_id=run_now_response.response.run_id).result() + repaired_run = w.jobs.repair_run( + rerun_tasks=[cancelled_run.tasks[0].task_key], + run_id=run_now_response.response.run_id, + ).result() # cleanup w.jobs.delete(job_id=created_job.job_id) Repair a job run. - + Re-run one or more tasks. Tasks are re-run as part of the original job run. They use the current job and task settings, and can be viewed in the history for the original job run. - + :param run_id: int The job run ID of the run to repair. The run must not be in progress. :param dbt_commands: List[str] (optional) @@ -675,9 +725,9 @@ task. If not specified upon `run-now`, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example `{"jar_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param job_parameters: Dict[str,str] (optional) Job-level parameters used in the run. for example `"param": "overriding_val"` @@ -688,16 +738,16 @@ A map from keys to values for jobs with notebook task, for example `"notebook_params": {"name": "john doe", "age": "35"}`. The map is passed to the notebook and is accessible through the [dbutils.widgets.get] function. - + If not specified upon `run-now`, the triggered run uses the job’s base parameters. - + notebook_params cannot be specified in conjunction with jar_params. - + Use [Task parameter variables] to set parameters containing information about job runs. - + The JSON representation of this field (for example `{"notebook_params":{"name":"john doe","age":"35"}}`) cannot exceed 10,000 bytes. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html :param pipeline_params: :class:`PipelineParams` (optional) @@ -708,15 +758,15 @@ The parameters are passed to Python file as command-line parameters. If specified upon `run-now`, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example `{"python_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs. - + Important - + These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param rerun_all_failed_tasks: bool (optional) If true, repair all failed tasks. Only one of `rerun_tasks` or `rerun_all_failed_tasks` can be used. @@ -731,20 +781,20 @@ as command-line parameters. If specified upon `run-now`, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example `{"python_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs - + Important - + These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param sql_params: Dict[str,str] (optional) A map from keys to values for jobs with SQL task, for example `"sql_params": {"name": "john doe", "age": "35"}`. The SQL alert task does not support custom parameters. - + :returns: Long-running operation waiter for :class:`Run`. See :method:wait_get_run_job_terminated_or_skipped for more details. @@ -768,43 +818,51 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) - new_name = f'sdk-{time.time_ns()}' + new_name = f"sdk-{time.time_ns()}" by_id = w.jobs.get(job_id=created_job.job_id) - w.jobs.reset(job_id=by_id.job_id, new_settings=jobs.JobSettings(name=new_name, tasks=by_id.settings.tasks)) + w.jobs.reset( + job_id=by_id.job_id, + new_settings=jobs.JobSettings(name=new_name, tasks=by_id.settings.tasks), + ) # cleanup w.jobs.delete(job_id=created_job.job_id) Update all job settings (reset). - + Overwrite all settings for the given job. Use the [_Update_ endpoint](:method:jobs/update) to update job settings partially. - + :param job_id: int The canonical identifier of the job to reset. This field is required. :param new_settings: :class:`JobSettings` The new settings of the job. These settings completely replace the old settings. - + Changes to the field `JobBaseSettings.timeout_seconds` are applied to active runs. Changes to other fields are applied to future runs only. - - + + .. py:method:: run_now(job_id: int [, dbt_commands: Optional[List[str]], idempotency_token: Optional[str], jar_params: Optional[List[str]], job_parameters: Optional[Dict[str, str]], notebook_params: Optional[Dict[str, str]], only: Optional[List[str]], performance_target: Optional[PerformanceTarget], pipeline_params: Optional[PipelineParams], python_named_params: Optional[Dict[str, str]], python_params: Optional[List[str]], queue: Optional[QueueSettings], spark_submit_params: Optional[List[str]], sql_params: Optional[Dict[str, str]]]) -> Wait[Run] @@ -822,19 +880,24 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' - - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] - - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" + + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) + + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) run_by_id = w.jobs.run_now(job_id=created_job.job_id).result() @@ -842,9 +905,9 @@ w.jobs.delete(job_id=created_job.job_id) Trigger a new job run. - + Run a job and return the `run_id` of the triggered run. - + :param job_id: int The ID of the job to be executed :param dbt_commands: List[str] (optional) @@ -854,14 +917,14 @@ An optional token to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned. - + If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. - + This token must have at most 64 characters. - + For more information, see [How to ensure idempotency for jobs]. - + [How to ensure idempotency for jobs]: https://kb.databricks.com/jobs/jobs-idempotency.html :param jar_params: List[str] (optional) A list of parameters for jobs with Spark JAR tasks, for example `"jar_params": ["john doe", "35"]`. @@ -869,9 +932,9 @@ task. If not specified upon `run-now`, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example `{"jar_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param job_parameters: Dict[str,str] (optional) Job-level parameters used in the run. for example `"param": "overriding_val"` @@ -879,16 +942,16 @@ A map from keys to values for jobs with notebook task, for example `"notebook_params": {"name": "john doe", "age": "35"}`. The map is passed to the notebook and is accessible through the [dbutils.widgets.get] function. - + If not specified upon `run-now`, the triggered run uses the job’s base parameters. - + notebook_params cannot be specified in conjunction with jar_params. - + Use [Task parameter variables] to set parameters containing information about job runs. - + The JSON representation of this field (for example `{"notebook_params":{"name":"john doe","age":"35"}}`) cannot exceed 10,000 bytes. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html :param only: List[str] (optional) @@ -896,8 +959,8 @@ will be run. :param performance_target: :class:`PerformanceTarget` (optional) PerformanceTarget defines how performant or cost efficient the execution of run on serverless - compute should be. For RunNow request, the run will execute with this settings instead of ones - defined in job. + compute should be. For RunNow, this performance target will override the target defined on the + job-level. :param pipeline_params: :class:`PipelineParams` (optional) Controls whether the pipeline should perform a full refresh :param python_named_params: Dict[str,str] (optional) @@ -906,15 +969,15 @@ The parameters are passed to Python file as command-line parameters. If specified upon `run-now`, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example `{"python_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs. - + Important - + These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param queue: :class:`QueueSettings` (optional) The queue settings of the run. @@ -924,20 +987,20 @@ as command-line parameters. If specified upon `run-now`, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example `{"python_params":["john doe","35"]}`) cannot exceed 10,000 bytes. - + Use [Task parameter variables] to set parameters containing information about job runs - + Important - + These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis. - + [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables :param sql_params: Dict[str,str] (optional) A map from keys to values for jobs with SQL task, for example `"sql_params": {"name": "john doe", "age": "35"}`. The SQL alert task does not support custom parameters. - + :returns: Long-running operation waiter for :class:`Run`. See :method:wait_get_run_job_terminated_or_skipped for more details. @@ -949,14 +1012,14 @@ .. py:method:: set_permissions(job_id: str [, access_control_list: Optional[List[JobAccessControlRequest]]]) -> JobPermissions Set job permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param job_id: str The job for which to get or manage permissions. :param access_control_list: List[:class:`JobAccessControlRequest`] (optional) - + :returns: :class:`JobPermissions` @@ -975,27 +1038,32 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - run = w.jobs.submit(run_name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.SubmitTask(existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key=f'sdk-{time.time_ns()}') - ]).result() + run = w.jobs.submit( + run_name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.SubmitTask( + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key=f"sdk-{time.time_ns()}", + ) + ], + ).result() # cleanup w.jobs.delete_run(run_id=run.run_id) Create and trigger a one-time run. - + Submit a one-time run. This endpoint allows you to submit a workload directly without creating a job. Runs submitted using this endpoint don’t display in the UI. Use the `jobs/runs/get` API to check the run state after the job is submitted. - + :param access_control_list: List[:class:`JobAccessControlRequest`] (optional) List of permissions to set on the job. :param budget_policy_id: str (optional) @@ -1008,10 +1076,10 @@ :param git_source: :class:`GitSource` (optional) An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - + If `git_source` is set, these tasks retrieve the file from the remote repository by default. However, this behavior can be overridden by setting `source` to `WORKSPACE` on the task. - + Note: dbt and SQL File tasks support only version-controlled sources. If dbt or SQL File tasks are used, `git_source` must be defined on the job. :param health: :class:`JobsHealthRules` (optional) @@ -1020,14 +1088,14 @@ An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned. - + If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. - + This token must have at most 64 characters. - + For more information, see [How to ensure idempotency for jobs]. - + [How to ensure idempotency for jobs]: https://kb.databricks.com/jobs/jobs-idempotency.html :param notification_settings: :class:`JobNotificationSettings` (optional) Optional notification settings that are used when sending notifications to each of the @@ -1044,7 +1112,7 @@ An optional timeout applied to each run of this job. A value of `0` means no timeout. :param webhook_notifications: :class:`WebhookNotifications` (optional) A collection of system notification IDs to notify when the run begins or completes. - + :returns: Long-running operation waiter for :class:`Run`. See :method:wait_get_run_job_terminated_or_skipped for more details. @@ -1068,32 +1136,40 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - cluster_id = w.clusters.ensure_cluster_is_running( - os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + cluster_id = ( + w.clusters.ensure_cluster_is_running(os.environ["DATABRICKS_CLUSTER_ID"]) and os.environ["DATABRICKS_CLUSTER_ID"] + ) - new_name = f'sdk-{time.time_ns()}' + new_name = f"sdk-{time.time_ns()}" - created_job = w.jobs.create(name=f'sdk-{time.time_ns()}', - tasks=[ - jobs.Task(description="test", - existing_cluster_id=cluster_id, - notebook_task=jobs.NotebookTask(notebook_path=notebook_path), - task_key="test", - timeout_seconds=0) - ]) + created_job = w.jobs.create( + name=f"sdk-{time.time_ns()}", + tasks=[ + jobs.Task( + description="test", + existing_cluster_id=cluster_id, + notebook_task=jobs.NotebookTask(notebook_path=notebook_path), + task_key="test", + timeout_seconds=0, + ) + ], + ) - w.jobs.update(job_id=created_job.job_id, new_settings=jobs.JobSettings(name=new_name, max_concurrent_runs=5)) + w.jobs.update( + job_id=created_job.job_id, + new_settings=jobs.JobSettings(name=new_name, max_concurrent_runs=5), + ) # cleanup w.jobs.delete(job_id=created_job.job_id) Update job settings partially. - + Add, update, or remove specific settings of an existing job. Use the [_Reset_ endpoint](:method:jobs/reset) to overwrite all job settings. - + :param job_id: int The canonical identifier of the job to update. This field is required. :param fields_to_remove: List[str] (optional) @@ -1101,29 +1177,29 @@ tasks and job clusters (`tasks/task_1`). This field is optional. :param new_settings: :class:`JobSettings` (optional) The new settings for the job. - + Top-level fields specified in `new_settings` are completely replaced, except for arrays which are merged. That is, new and existing entries are completely replaced based on the respective key fields, i.e. `task_key` or `job_cluster_key`, while previous entries are kept. - + Partially updating nested fields is not supported. - + Changes to the field `JobSettings.timeout_seconds` are applied to active runs. Changes to other fields are applied to future runs only. - - + + .. py:method:: update_permissions(job_id: str [, access_control_list: Optional[List[JobAccessControlRequest]]]) -> JobPermissions Update job permissions. - + Updates the permissions on a job. Jobs can inherit permissions from their root object. - + :param job_id: str The job for which to get or manage permissions. :param access_control_list: List[:class:`JobAccessControlRequest`] (optional) - + :returns: :class:`JobPermissions` diff --git a/docs/workspace/jobs/policy_compliance_for_jobs.rst b/docs/workspace/jobs/policy_compliance_for_jobs.rst index 69f211552..b75a73eab 100644 --- a/docs/workspace/jobs/policy_compliance_for_jobs.rst +++ b/docs/workspace/jobs/policy_compliance_for_jobs.rst @@ -6,53 +6,53 @@ The compliance APIs allow you to view and manage the policy compliance status of jobs in your workspace. This API currently only supports compliance controls for cluster policies. - + A job is in compliance if its cluster configurations satisfy the rules of all their respective cluster policies. A job could be out of compliance if a cluster policy it uses was updated after the job was last edited. The job is considered out of compliance if any of its clusters no longer comply with their updated policies. - + The get and list compliance APIs allow you to view the policy compliance status of a job. The enforce compliance API allows you to update a job so that it becomes compliant with all of its policies. .. py:method:: enforce_compliance(job_id: int [, validate_only: Optional[bool]]) -> EnforcePolicyComplianceResponse Enforce job policy compliance. - + Updates a job so the job clusters that are created when running the job (specified in `new_cluster`) are compliant with the current versions of their respective cluster policies. All-purpose clusters used in the job will not be updated. - + :param job_id: int The ID of the job you want to enforce policy compliance on. :param validate_only: bool (optional) If set, previews changes made to the job to comply with its policy, but does not update the job. - + :returns: :class:`EnforcePolicyComplianceResponse` .. py:method:: get_compliance(job_id: int) -> GetPolicyComplianceResponse Get job policy compliance. - + Returns the policy compliance status of a job. Jobs could be out of compliance if a cluster policy they use was updated after the job was last edited and some of its job clusters no longer comply with their updated policies. - + :param job_id: int The ID of the job whose compliance status you are requesting. - + :returns: :class:`GetPolicyComplianceResponse` .. py:method:: list_compliance(policy_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[JobCompliance] List job policy compliance. - + Returns the policy compliance status of all jobs that use a given policy. Jobs could be out of compliance if a cluster policy they use was updated after the job was last edited and its job clusters no longer comply with the updated policy. - + :param policy_id: str Canonical unique identifier for the cluster policy. :param page_size: int (optional) @@ -61,6 +61,6 @@ :param page_token: str (optional) A page token that can be used to navigate to the next page or previous page as returned by `next_page_token` or `prev_page_token`. - + :returns: Iterator over :class:`JobCompliance` \ No newline at end of file diff --git a/docs/workspace/marketplace/consumer_fulfillments.rst b/docs/workspace/marketplace/consumer_fulfillments.rst index 4ea7a9c29..149ec6451 100644 --- a/docs/workspace/marketplace/consumer_fulfillments.rst +++ b/docs/workspace/marketplace/consumer_fulfillments.rst @@ -9,28 +9,28 @@ .. py:method:: get(listing_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[SharedDataObject] Get listing content metadata. - + Get a high level preview of the metadata of listing installable content. - + :param listing_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`SharedDataObject` .. py:method:: list(listing_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ListingFulfillment] List all listing fulfillments. - + Get all listings fulfillments associated with a listing. A _fulfillment_ is a potential installation. Standard installations contain metadata about the attached share or git repo. Only one of these fields will be present. Personalized installations contain metadata about the attached share or git repo, as well as the Delta Sharing recipient type. - + :param listing_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ListingFulfillment` \ No newline at end of file diff --git a/docs/workspace/marketplace/consumer_installations.rst b/docs/workspace/marketplace/consumer_installations.rst index 3cdb00a5a..a9539ad1f 100644 --- a/docs/workspace/marketplace/consumer_installations.rst +++ b/docs/workspace/marketplace/consumer_installations.rst @@ -9,9 +9,9 @@ .. py:method:: create(listing_id: str [, accepted_consumer_terms: Optional[ConsumerTerms], catalog_name: Optional[str], recipient_type: Optional[DeltaSharingRecipientType], repo_detail: Optional[RepoInstallation], share_name: Optional[str]]) -> Installation Install from a listing. - + Install payload associated with a Databricks Marketplace listing. - + :param listing_id: str :param accepted_consumer_terms: :class:`ConsumerTerms` (optional) :param catalog_name: str (optional) @@ -19,60 +19,60 @@ :param repo_detail: :class:`RepoInstallation` (optional) for git repo installations :param share_name: str (optional) - + :returns: :class:`Installation` .. py:method:: delete(listing_id: str, installation_id: str) Uninstall from a listing. - + Uninstall an installation associated with a Databricks Marketplace listing. - + :param listing_id: str :param installation_id: str - - + + .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[InstallationDetail] List all installations. - + List all installations across all listings. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`InstallationDetail` .. py:method:: list_listing_installations(listing_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[InstallationDetail] List installations for a listing. - + List all installations for a particular listing. - + :param listing_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`InstallationDetail` .. py:method:: update(listing_id: str, installation_id: str, installation: InstallationDetail [, rotate_token: Optional[bool]]) -> UpdateInstallationResponse Update an installation. - + This is a update API that will update the part of the fields defined in the installation table as well as interact with external services according to the fields not included in the installation table 1. the token will be rotate if the rotateToken flag is true 2. the token will be forcibly rotate if the rotateToken flag is true and the tokenInfo field is empty - + :param listing_id: str :param installation_id: str :param installation: :class:`InstallationDetail` :param rotate_token: bool (optional) - + :returns: :class:`UpdateInstallationResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/consumer_listings.rst b/docs/workspace/marketplace/consumer_listings.rst index 242a8fce7..15ec3790e 100644 --- a/docs/workspace/marketplace/consumer_listings.rst +++ b/docs/workspace/marketplace/consumer_listings.rst @@ -10,31 +10,31 @@ .. py:method:: batch_get( [, ids: Optional[List[str]]]) -> BatchGetListingsResponse Get one batch of listings. One may specify up to 50 IDs per request. - + Batch get a published listing in the Databricks Marketplace that the consumer has access to. - + :param ids: List[str] (optional) - + :returns: :class:`BatchGetListingsResponse` .. py:method:: get(id: str) -> GetListingResponse Get listing. - + Get a published listing in the Databricks Marketplace that the consumer has access to. - + :param id: str - + :returns: :class:`GetListingResponse` .. py:method:: list( [, assets: Optional[List[AssetType]], categories: Optional[List[Category]], is_free: Optional[bool], is_private_exchange: Optional[bool], is_staff_pick: Optional[bool], page_size: Optional[int], page_token: Optional[str], provider_ids: Optional[List[str]], tags: Optional[List[ListingTag]]]) -> Iterator[Listing] List listings. - + List all published listings in the Databricks Marketplace that the consumer has access to. - + :param assets: List[:class:`AssetType`] (optional) Matches any of the following asset types :param categories: List[:class:`Category`] (optional) @@ -51,17 +51,17 @@ Matches any of the following provider ids :param tags: List[:class:`ListingTag`] (optional) Matches any of the following tags - + :returns: Iterator over :class:`Listing` .. py:method:: search(query: str [, assets: Optional[List[AssetType]], categories: Optional[List[Category]], is_free: Optional[bool], is_private_exchange: Optional[bool], page_size: Optional[int], page_token: Optional[str], provider_ids: Optional[List[str]]]) -> Iterator[Listing] Search listings. - + Search published listings in the Databricks Marketplace that the consumer has access to. This query supports a variety of different search parameters and performs fuzzy matching. - + :param query: str Fuzzy matches query :param assets: List[:class:`AssetType`] (optional) @@ -74,6 +74,6 @@ :param page_token: str (optional) :param provider_ids: List[str] (optional) Matches any of the following provider ids - + :returns: Iterator over :class:`Listing` \ No newline at end of file diff --git a/docs/workspace/marketplace/consumer_personalization_requests.rst b/docs/workspace/marketplace/consumer_personalization_requests.rst index 63ead75d3..8624871ca 100644 --- a/docs/workspace/marketplace/consumer_personalization_requests.rst +++ b/docs/workspace/marketplace/consumer_personalization_requests.rst @@ -9,9 +9,9 @@ .. py:method:: create(listing_id: str, intended_use: str, accepted_consumer_terms: ConsumerTerms [, comment: Optional[str], company: Optional[str], first_name: Optional[str], is_from_lighthouse: Optional[bool], last_name: Optional[str], recipient_type: Optional[DeltaSharingRecipientType]]) -> CreatePersonalizationRequestResponse Create a personalization request. - + Create a personalization request for a listing. - + :param listing_id: str :param intended_use: str :param accepted_consumer_terms: :class:`ConsumerTerms` @@ -21,30 +21,30 @@ :param is_from_lighthouse: bool (optional) :param last_name: str (optional) :param recipient_type: :class:`DeltaSharingRecipientType` (optional) - + :returns: :class:`CreatePersonalizationRequestResponse` .. py:method:: get(listing_id: str) -> GetPersonalizationRequestResponse Get the personalization request for a listing. - + Get the personalization request for a listing. Each consumer can make at *most* one personalization request for a listing. - + :param listing_id: str - + :returns: :class:`GetPersonalizationRequestResponse` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[PersonalizationRequest] List all personalization requests. - + List personalization requests for a consumer across all listings. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`PersonalizationRequest` \ No newline at end of file diff --git a/docs/workspace/marketplace/consumer_providers.rst b/docs/workspace/marketplace/consumer_providers.rst index 13cca357e..615bf0752 100644 --- a/docs/workspace/marketplace/consumer_providers.rst +++ b/docs/workspace/marketplace/consumer_providers.rst @@ -9,34 +9,34 @@ .. py:method:: batch_get( [, ids: Optional[List[str]]]) -> BatchGetProvidersResponse Get one batch of providers. One may specify up to 50 IDs per request. - + Batch get a provider in the Databricks Marketplace with at least one visible listing. - + :param ids: List[str] (optional) - + :returns: :class:`BatchGetProvidersResponse` .. py:method:: get(id: str) -> GetProviderResponse Get a provider. - + Get a provider in the Databricks Marketplace with at least one visible listing. - + :param id: str - + :returns: :class:`GetProviderResponse` .. py:method:: list( [, is_featured: Optional[bool], page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ProviderInfo] List providers. - + List all providers in the Databricks Marketplace with at least one visible listing. - + :param is_featured: bool (optional) :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ProviderInfo` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_exchange_filters.rst b/docs/workspace/marketplace/provider_exchange_filters.rst index ceca51e63..6c2254acd 100644 --- a/docs/workspace/marketplace/provider_exchange_filters.rst +++ b/docs/workspace/marketplace/provider_exchange_filters.rst @@ -9,46 +9,46 @@ .. py:method:: create(filter: ExchangeFilter) -> CreateExchangeFilterResponse Create a new exchange filter. - + Add an exchange filter. - + :param filter: :class:`ExchangeFilter` - + :returns: :class:`CreateExchangeFilterResponse` .. py:method:: delete(id: str) Delete an exchange filter. - + Delete an exchange filter - + :param id: str - - + + .. py:method:: list(exchange_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ExchangeFilter] List exchange filters. - + List exchange filter - + :param exchange_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ExchangeFilter` .. py:method:: update(id: str, filter: ExchangeFilter) -> UpdateExchangeFilterResponse Update exchange filter. - + Update an exchange filter. - + :param id: str :param filter: :class:`ExchangeFilter` - + :returns: :class:`UpdateExchangeFilterResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_exchanges.rst b/docs/workspace/marketplace/provider_exchanges.rst index d53fd823d..edaae76e1 100644 --- a/docs/workspace/marketplace/provider_exchanges.rst +++ b/docs/workspace/marketplace/provider_exchanges.rst @@ -9,105 +9,105 @@ .. py:method:: add_listing_to_exchange(listing_id: str, exchange_id: str) -> AddExchangeForListingResponse Add an exchange for listing. - + Associate an exchange with a listing - + :param listing_id: str :param exchange_id: str - + :returns: :class:`AddExchangeForListingResponse` .. py:method:: create(exchange: Exchange) -> CreateExchangeResponse Create an exchange. - + Create an exchange - + :param exchange: :class:`Exchange` - + :returns: :class:`CreateExchangeResponse` .. py:method:: delete(id: str) Delete an exchange. - + This removes a listing from marketplace. - + :param id: str - - + + .. py:method:: delete_listing_from_exchange(id: str) Remove an exchange for listing. - + Disassociate an exchange with a listing - + :param id: str - - + + .. py:method:: get(id: str) -> GetExchangeResponse Get an exchange. - + Get an exchange. - + :param id: str - + :returns: :class:`GetExchangeResponse` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[Exchange] List exchanges. - + List exchanges visible to provider - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`Exchange` .. py:method:: list_exchanges_for_listing(listing_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ExchangeListing] List exchanges for listing. - + List exchanges associated with a listing - + :param listing_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ExchangeListing` .. py:method:: list_listings_for_exchange(exchange_id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ExchangeListing] List listings for exchange. - + List listings associated with an exchange - + :param exchange_id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ExchangeListing` .. py:method:: update(id: str, exchange: Exchange) -> UpdateExchangeResponse Update exchange. - + Update an exchange - + :param id: str :param exchange: :class:`Exchange` - + :returns: :class:`UpdateExchangeResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_files.rst b/docs/workspace/marketplace/provider_files.rst index f719ca65f..413936020 100644 --- a/docs/workspace/marketplace/provider_files.rst +++ b/docs/workspace/marketplace/provider_files.rst @@ -9,48 +9,48 @@ .. py:method:: create(file_parent: FileParent, marketplace_file_type: MarketplaceFileType, mime_type: str [, display_name: Optional[str]]) -> CreateFileResponse Create a file. - + Create a file. Currently, only provider icons and attached notebooks are supported. - + :param file_parent: :class:`FileParent` :param marketplace_file_type: :class:`MarketplaceFileType` :param mime_type: str :param display_name: str (optional) - + :returns: :class:`CreateFileResponse` .. py:method:: delete(file_id: str) Delete a file. - + Delete a file - + :param file_id: str - - + + .. py:method:: get(file_id: str) -> GetFileResponse Get a file. - + Get a file - + :param file_id: str - + :returns: :class:`GetFileResponse` .. py:method:: list(file_parent: FileParent [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[FileInfo] List files. - + List files attached to a parent entity. - + :param file_parent: :class:`FileParent` :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`FileInfo` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_listings.rst b/docs/workspace/marketplace/provider_listings.rst index d26c5293e..dcfd45dd8 100644 --- a/docs/workspace/marketplace/provider_listings.rst +++ b/docs/workspace/marketplace/provider_listings.rst @@ -10,56 +10,56 @@ .. py:method:: create(listing: Listing) -> CreateListingResponse Create a listing. - + Create a new listing - + :param listing: :class:`Listing` - + :returns: :class:`CreateListingResponse` .. py:method:: delete(id: str) Delete a listing. - + Delete a listing - + :param id: str - - + + .. py:method:: get(id: str) -> GetListingResponse Get a listing. - + Get a listing - + :param id: str - + :returns: :class:`GetListingResponse` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[Listing] List listings. - + List listings owned by this provider - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`Listing` .. py:method:: update(id: str, listing: Listing) -> UpdateListingResponse Update listing. - + Update a listing - + :param id: str :param listing: :class:`Listing` - + :returns: :class:`UpdateListingResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_personalization_requests.rst b/docs/workspace/marketplace/provider_personalization_requests.rst index 32cdbdbb3..b9b5a0174 100644 --- a/docs/workspace/marketplace/provider_personalization_requests.rst +++ b/docs/workspace/marketplace/provider_personalization_requests.rst @@ -10,27 +10,27 @@ .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[PersonalizationRequest] All personalization requests across all listings. - + List personalization requests to this provider. This will return all personalization requests, regardless of which listing they are for. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`PersonalizationRequest` .. py:method:: update(listing_id: str, request_id: str, status: PersonalizationRequestStatus [, reason: Optional[str], share: Optional[ShareInfo]]) -> UpdatePersonalizationRequestResponse Update personalization request status. - + Update personalization request. This method only permits updating the status of the request. - + :param listing_id: str :param request_id: str :param status: :class:`PersonalizationRequestStatus` :param reason: str (optional) :param share: :class:`ShareInfo` (optional) - + :returns: :class:`UpdatePersonalizationRequestResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst b/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst index cc29e089f..f77b9d436 100644 --- a/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst +++ b/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst @@ -9,42 +9,42 @@ .. py:method:: create() -> ProviderAnalyticsDashboard Create provider analytics dashboard. - + Create provider analytics dashboard. Returns Marketplace specific `id`. Not to be confused with the Lakeview dashboard id. - + :returns: :class:`ProviderAnalyticsDashboard` .. py:method:: get() -> ListProviderAnalyticsDashboardResponse Get provider analytics dashboard. - + Get provider analytics dashboard. - + :returns: :class:`ListProviderAnalyticsDashboardResponse` .. py:method:: get_latest_version() -> GetLatestVersionProviderAnalyticsDashboardResponse Get latest version of provider analytics dashboard. - + Get latest version of provider analytics dashboard. - + :returns: :class:`GetLatestVersionProviderAnalyticsDashboardResponse` .. py:method:: update(id: str [, version: Optional[int]]) -> UpdateProviderAnalyticsDashboardResponse Update provider analytics dashboard. - + Update provider analytics dashboard. - + :param id: str id is immutable property and can't be updated. :param version: int (optional) this is the version of the dashboard template we want to update our user to current expectation is that it should be equal to latest version of the dashboard template - + :returns: :class:`UpdateProviderAnalyticsDashboardResponse` \ No newline at end of file diff --git a/docs/workspace/marketplace/provider_providers.rst b/docs/workspace/marketplace/provider_providers.rst index 610c9602e..ac8a4fdc3 100644 --- a/docs/workspace/marketplace/provider_providers.rst +++ b/docs/workspace/marketplace/provider_providers.rst @@ -9,56 +9,56 @@ .. py:method:: create(provider: ProviderInfo) -> CreateProviderResponse Create a provider. - + Create a provider - + :param provider: :class:`ProviderInfo` - + :returns: :class:`CreateProviderResponse` .. py:method:: delete(id: str) Delete provider. - + Delete provider - + :param id: str - - + + .. py:method:: get(id: str) -> GetProviderResponse Get provider. - + Get provider profile - + :param id: str - + :returns: :class:`GetProviderResponse` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ProviderInfo] List providers. - + List provider profiles for account. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ProviderInfo` .. py:method:: update(id: str, provider: ProviderInfo) -> UpdateProviderResponse Update provider. - + Update provider profile - + :param id: str :param provider: :class:`ProviderInfo` - + :returns: :class:`UpdateProviderResponse` \ No newline at end of file diff --git a/docs/workspace/ml/experiments.rst b/docs/workspace/ml/experiments.rst index 44ceeef8c..a8863edcd 100644 --- a/docs/workspace/ml/experiments.rst +++ b/docs/workspace/ml/experiments.rst @@ -7,7 +7,7 @@ Experiments are the primary unit of organization in MLflow; all MLflow runs belong to an experiment. Each experiment lets you visualize, search, and compare runs, as well as download run artifacts or metadata for analysis in other tools. Experiments are maintained in a Databricks hosted MLflow tracking server. - + Experiments are located in the workspace file tree. You manage experiments using the same tools you use to manage other workspace objects such as folders, notebooks, and libraries. @@ -24,19 +24,19 @@ w = WorkspaceClient() - experiment = w.experiments.create_experiment(name=f'sdk-{time.time_ns()}') + experiment = w.experiments.create_experiment(name=f"sdk-{time.time_ns()}") # cleanup w.experiments.delete_experiment(experiment_id=experiment.experiment_id) Create experiment. - + Creates an experiment with a name. Returns the ID of the newly created experiment. Validates that another experiment with the same name does not already exist and fails if another experiment with the same name already exists. - - Throws `RESOURCE_ALREADY_EXISTS` if a experiment with the given name exists. - + + Throws `RESOURCE_ALREADY_EXISTS` if an experiment with the given name exists. + :param name: str Experiment name. :param artifact_location: str (optional) @@ -47,11 +47,11 @@ depends on the storage backend. All storage backends are guaranteed to support tag keys up to 250 bytes in size and tag values up to 5000 bytes in size. All storage backends are also guaranteed to support up to 20 tags per request. - + :returns: :class:`CreateExperimentResponse` - .. py:method:: create_run( [, experiment_id: Optional[str], start_time: Optional[int], tags: Optional[List[RunTag]], user_id: Optional[str]]) -> CreateRunResponse + .. py:method:: create_run( [, experiment_id: Optional[str], run_name: Optional[str], start_time: Optional[int], tags: Optional[List[RunTag]], user_id: Optional[str]]) -> CreateRunResponse Usage: @@ -65,23 +65,27 @@ w = WorkspaceClient() - experiment = w.experiments.create_experiment(name=f'sdk-{time.time_ns()}') + experiment = w.experiments.create_experiment(name=f"sdk-{time.time_ns()}") - created = w.experiments.create_run(experiment_id=experiment.experiment_id, - tags=[ml.RunTag(key="foo", value="bar")]) + created = w.experiments.create_run( + experiment_id=experiment.experiment_id, + tags=[ml.RunTag(key="foo", value="bar")], + ) # cleanup w.experiments.delete_experiment(experiment_id=experiment.experiment_id) w.experiments.delete_run(run_id=created.run.info.run_id) Create a run. - + Creates a new run within an experiment. A run is usually a single execution of a machine learning or - data ETL pipeline. MLflow uses runs to track the `mlflowParam`, `mlflowMetric` and `mlflowRunTag` + data ETL pipeline. MLflow uses runs to track the `mlflowParam`, `mlflowMetric`, and `mlflowRunTag` associated with a single execution. - + :param experiment_id: str (optional) ID of the associated experiment. + :param run_name: str (optional) + The name of the run. :param start_time: int (optional) Unix timestamp in milliseconds of when the run started. :param tags: List[:class:`RunTag`] (optional) @@ -89,43 +93,43 @@ :param user_id: str (optional) ID of the user executing the run. This field is deprecated as of MLflow 1.0, and will be removed in a future MLflow release. Use 'mlflow.user' tag instead. - + :returns: :class:`CreateRunResponse` .. py:method:: delete_experiment(experiment_id: str) Delete an experiment. - + Marks an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the - experiment uses FileStore, artifacts associated with experiment are also deleted. - + experiment uses FileStore, artifacts associated with the experiment are also deleted. + :param experiment_id: str ID of the associated experiment. - - + + .. py:method:: delete_run(run_id: str) Delete a run. - + Marks a run for deletion. - + :param run_id: str ID of the run to delete. - - + + .. py:method:: delete_runs(experiment_id: str, max_timestamp_millis: int [, max_runs: Optional[int]]) -> DeleteRunsResponse Delete runs by creation time. - + Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the - client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-delete. - + client code snippet on + :param experiment_id: str The ID of the experiment containing the runs to delete. :param max_timestamp_millis: int @@ -134,41 +138,41 @@ :param max_runs: int (optional) An optional positive integer indicating the maximum number of runs to delete. The maximum allowed value for max_runs is 10000. - + :returns: :class:`DeleteRunsResponse` .. py:method:: delete_tag(run_id: str, key: str) - Delete a tag. - + Delete a tag on a run. + Deletes a tag on a run. Tags are run metadata that can be updated during a run and after a run completes. - + :param run_id: str ID of the run that the tag was logged under. Must be provided. :param key: str Name of the tag. Maximum size is 255 bytes. Must be provided. - - - - .. py:method:: get_by_name(experiment_name: str) -> GetExperimentResponse - Get metadata. + + .. py:method:: get_by_name(experiment_name: str) -> GetExperimentByNameResponse + + Get an experiment by name. + Gets metadata for an experiment. - + This endpoint will return deleted experiments, but prefers the active experiment if an active and deleted experiment share the same name. If multiple deleted experiments share the same name, the API will return one of them. - + Throws `RESOURCE_DOES_NOT_EXIST` if no experiment with the specified name exists. - + :param experiment_name: str Name of the associated experiment. - - :returns: :class:`GetExperimentResponse` + + :returns: :class:`GetExperimentByNameResponse` .. py:method:: get_experiment(experiment_id: str) -> GetExperimentResponse @@ -184,7 +188,7 @@ w = WorkspaceClient() - experiment = w.experiments.create_experiment(name=f'sdk-{time.time_ns()}') + experiment = w.experiments.create_experiment(name=f"sdk-{time.time_ns()}") _ = w.experiments.get_experiment(experiment_id=experiment.experiment_id) @@ -192,21 +196,21 @@ w.experiments.delete_experiment(experiment_id=experiment.experiment_id) Get an experiment. - + Gets metadata for an experiment. This method works on deleted experiments. - + :param experiment_id: str ID of the associated experiment. - + :returns: :class:`GetExperimentResponse` .. py:method:: get_history(metric_key: str [, max_results: Optional[int], page_token: Optional[str], run_id: Optional[str], run_uuid: Optional[str]]) -> Iterator[Metric] - Get history of a given metric within a run. - + Get metric history for a run. + Gets a list of all values for the specified metric for a given run. - + :param metric_key: str Name of the metric. :param max_results: int (optional) @@ -217,64 +221,64 @@ :param run_id: str (optional) ID of the run from which to fetch metric values. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run from which to fetch metric values. This field will be - removed in a future MLflow version. - + [Deprecated, use `run_id` instead] ID of the run from which to fetch metric values. This field will + be removed in a future MLflow version. + :returns: Iterator over :class:`Metric` .. py:method:: get_permission_levels(experiment_id: str) -> GetExperimentPermissionLevelsResponse Get experiment permission levels. - + Gets the permission levels that a user can have on an object. - + :param experiment_id: str The experiment for which to get or manage permissions. - + :returns: :class:`GetExperimentPermissionLevelsResponse` .. py:method:: get_permissions(experiment_id: str) -> ExperimentPermissions Get experiment permissions. - + Gets the permissions of an experiment. Experiments can inherit permissions from their root object. - + :param experiment_id: str The experiment for which to get or manage permissions. - + :returns: :class:`ExperimentPermissions` .. py:method:: get_run(run_id: str [, run_uuid: Optional[str]]) -> GetRunResponse Get a run. - + Gets the metadata, metrics, params, and tags for a run. In the case where multiple metrics with the same key are logged for a run, return only the value with the latest timestamp. - + If there are multiple values with the latest timestamp, return the maximum of these values. - + :param run_id: str ID of the run to fetch. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run to fetch. This field will be removed in a future + [Deprecated, use `run_id` instead] ID of the run to fetch. This field will be removed in a future MLflow version. - + :returns: :class:`GetRunResponse` .. py:method:: list_artifacts( [, page_token: Optional[str], path: Optional[str], run_id: Optional[str], run_uuid: Optional[str]]) -> Iterator[FileInfo] - Get all artifacts. - - List artifacts for a run. Takes an optional `artifact_path` prefix. If it is specified, the response - contains only artifacts with the specified prefix. This API does not support pagination when listing - artifacts in UC Volumes. A maximum of 1000 artifacts will be retrieved for UC Volumes. Please call - `/api/2.0/fs/directories{directory_path}` for listing artifacts in UC Volumes, which supports - pagination. See [List directory contents | Files API](/api/workspace/files/listdirectorycontents). - + List artifacts. + + List artifacts for a run. Takes an optional `artifact_path` prefix which if specified, the response + contains only artifacts with the specified prefix. A maximum of 1000 artifacts will be retrieved for + UC Volumes. Please call `/api/2.0/fs/directories{directory_path}` for listing artifacts in UC Volumes, + which supports pagination. See [List directory contents | Files + API](/api/workspace/files/listdirectorycontents). + :param page_token: str (optional) Token indicating the page of artifact results to fetch. `page_token` is not supported when listing artifacts in UC Volumes. A maximum of 1000 artifacts will be retrieved for UC Volumes. Please call @@ -285,13 +289,13 @@ :param run_id: str (optional) ID of the run whose artifacts to list. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run whose artifacts to list. This field will be removed + [Deprecated, use `run_id` instead] ID of the run whose artifacts to list. This field will be removed in a future MLflow version. - + :returns: Iterator over :class:`FileInfo` - .. py:method:: list_experiments( [, max_results: Optional[int], page_token: Optional[str], view_type: Optional[str]]) -> Iterator[Experiment] + .. py:method:: list_experiments( [, max_results: Optional[int], page_token: Optional[str], view_type: Optional[ViewType]]) -> Iterator[Experiment] Usage: @@ -306,60 +310,66 @@ all = w.experiments.list_experiments(ml.ListExperimentsRequest()) List experiments. - + Gets a list of all experiments. - + :param max_results: int (optional) Maximum number of experiments desired. If `max_results` is unspecified, return all experiments. If `max_results` is too large, it'll be automatically capped at 1000. Callers of this endpoint are encouraged to pass max_results explicitly and leverage page_token to iterate through experiments. :param page_token: str (optional) Token indicating the page of experiments to fetch - :param view_type: str (optional) + :param view_type: :class:`ViewType` (optional) Qualifier for type of experiments to be returned. If unspecified, return only active experiments. - + :returns: Iterator over :class:`Experiment` .. py:method:: log_batch( [, metrics: Optional[List[Metric]], params: Optional[List[Param]], run_id: Optional[str], tags: Optional[List[RunTag]]]) - Log a batch. - + Log a batch of metrics/params/tags for a run. + Logs a batch of metrics, params, and tags for a run. If any data failed to be persisted, the server will respond with an error (non-200 status code). - + In case of error (due to internal server error or an invalid request), partial data may be written. - + You can write metrics, params, and tags in interleaving fashion, but within a given entity type are guaranteed to follow the order specified in the request body. - + The overwrite behavior for metrics, params, and tags is as follows: - + * Metrics: metric values are never overwritten. Logging a metric (key, value, timestamp) appends to the set of values for the metric with the provided key. - + * Tags: tag values can be overwritten by successive writes to the same tag key. That is, if multiple tag values with the same key are provided in the same API request, the last-provided tag value is written. Logging the same tag (key, value) is permitted. Specifically, logging a tag is idempotent. - + * Parameters: once written, param values cannot be changed (attempting to overwrite a param value will result in an error). However, logging the same param (key, value) is permitted. Specifically, logging a param is idempotent. - + Request Limits ------------------------------- A single JSON-serialized API request may be up to 1 MB in size and contain: - - * No more than 1000 metrics, params, and tags in total * Up to 1000 metrics * Up to 100 params * Up to - 100 tags - + + * No more than 1000 metrics, params, and tags in total + + * Up to 1000 metrics + + * Up to 100 params + + * Up to 100 tags + For example, a valid request might contain 900 metrics, 50 params, and 50 tags, but logging 900 metrics, 50 params, and 51 tags is invalid. - + The following limits also apply to metric, param, and tag keys and values: - - * Metric keys, param keys, and tag keys can be up to 250 characters in length * Parameter and tag - values can be up to 250 characters in length - + + * Metric keys, param keys, and tag keys can be up to 250 characters in length + + * Parameter and tag values can be up to 250 characters in length + :param metrics: List[:class:`Metric`] (optional) Metrics to log. A single request can contain up to 1000 metrics, and up to 1000 metrics, params, and tags in total. @@ -371,32 +381,34 @@ :param tags: List[:class:`RunTag`] (optional) Tags to log. A single request can contain up to 100 tags, and up to 1000 metrics, params, and tags in total. - - + + - .. py:method:: log_inputs( [, datasets: Optional[List[DatasetInput]], run_id: Optional[str]]) + .. py:method:: log_inputs(run_id: str [, datasets: Optional[List[DatasetInput]]]) Log inputs to a run. - + **NOTE:** Experimental: This API may change or be removed in a future release without warning. - + + Logs inputs, such as datasets and models, to an MLflow Run. + + :param run_id: str + ID of the run to log under :param datasets: List[:class:`DatasetInput`] (optional) Dataset inputs - :param run_id: str (optional) - ID of the run to log under - - + + .. py:method:: log_metric(key: str, value: float, timestamp: int [, run_id: Optional[str], run_uuid: Optional[str], step: Optional[int]]) - Log a metric. - - Logs a metric for a run. A metric is a key-value pair (string key, float value) with an associated + Log a metric for a run. + + Log a metric for a run. A metric is a key-value pair (string key, float value) with an associated timestamp. Examples include the various metrics that represent ML model accuracy. A metric can be logged multiple times. - + :param key: str Name of the metric. :param value: float @@ -406,36 +418,36 @@ :param run_id: str (optional) ID of the run under which to log the metric. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the metric. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the metric. This field will be removed in a future MLflow version. :param step: int (optional) Step at which to log the metric - - + + .. py:method:: log_model( [, model_json: Optional[str], run_id: Optional[str]]) Log a model. - + **NOTE:** Experimental: This API may change or be removed in a future release without warning. - + :param model_json: str (optional) MLmodel file in json format. :param run_id: str (optional) ID of the run to log under - - + + .. py:method:: log_param(key: str, value: str [, run_id: Optional[str], run_uuid: Optional[str]]) - Log a param. - + Log a param for a run. + Logs a param used for a run. A param is a key-value pair (string key, string value). Examples include hyperparameters used for ML model training and constant dates and values used in an ETL pipeline. A param can be logged only once for a run. - + :param key: str Name of the param. Maximum size is 255 bytes. :param value: str @@ -443,48 +455,50 @@ :param run_id: str (optional) ID of the run under which to log the param. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the param. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the param. This field will be removed in a future MLflow version. - - + + .. py:method:: restore_experiment(experiment_id: str) - Restores an experiment. - + Restore an experiment. + Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics, params, and tags. If experiment uses FileStore, underlying artifacts associated with experiment are also restored. - + Throws `RESOURCE_DOES_NOT_EXIST` if experiment was never created or was permanently deleted. - + :param experiment_id: str ID of the associated experiment. - - + + .. py:method:: restore_run(run_id: str) Restore a run. - - Restores a deleted run. - + + Restores a deleted run. This also restores associated metadata, runs, metrics, params, and tags. + + Throws `RESOURCE_DOES_NOT_EXIST` if the run was never created or was permanently deleted. + :param run_id: str ID of the run to restore. - - + + .. py:method:: restore_runs(experiment_id: str, min_timestamp_millis: int [, max_runs: Optional[int]]) -> RestoreRunsResponse Restore runs by deletion time. - + Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the - client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-restore. - + client code snippet on + :param experiment_id: str The ID of the experiment containing the runs to restore. :param min_timestamp_millis: int @@ -493,16 +507,16 @@ :param max_runs: int (optional) An optional positive integer indicating the maximum number of runs to restore. The maximum allowed value for max_runs is 10000. - + :returns: :class:`RestoreRunsResponse` - .. py:method:: search_experiments( [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str], view_type: Optional[SearchExperimentsViewType]]) -> Iterator[Experiment] + .. py:method:: search_experiments( [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str], view_type: Optional[ViewType]]) -> Iterator[Experiment] Search experiments. - + Searches for experiments that satisfy specified search criteria. - + :param filter: str (optional) String representing a SQL filter condition (e.g. "name ILIKE 'my-experiment%'") :param max_results: int (optional) @@ -513,100 +527,96 @@ done by experiment id DESC. :param page_token: str (optional) Token indicating the page of experiments to fetch - :param view_type: :class:`SearchExperimentsViewType` (optional) + :param view_type: :class:`ViewType` (optional) Qualifier for type of experiments to be returned. If unspecified, return only active experiments. - + :returns: Iterator over :class:`Experiment` - .. py:method:: search_runs( [, experiment_ids: Optional[List[str]], filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str], run_view_type: Optional[SearchRunsRunViewType]]) -> Iterator[Run] + .. py:method:: search_runs( [, experiment_ids: Optional[List[str]], filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str], run_view_type: Optional[ViewType]]) -> Iterator[Run] Search for runs. - + Searches for runs that satisfy expressions. - - Search expressions can use `mlflowMetric` and `mlflowParam` keys.", - + + Search expressions can use `mlflowMetric` and `mlflowParam` keys. + :param experiment_ids: List[str] (optional) List of experiment IDs to search over. :param filter: str (optional) A filter expression over params, metrics, and tags, that allows returning a subset of runs. The syntax is a subset of SQL that supports ANDing together binary operations between a param, metric, or tag and a constant. - + Example: `metrics.rmse < 1 and params.model_class = 'LogisticRegression'` - + You can select columns with special characters (hyphen, space, period, etc.) by using double quotes: `metrics."model class" = 'LinearRegression' and tags."user-name" = 'Tomas'` - + Supported operators are `=`, `!=`, `>`, `>=`, `<`, and `<=`. :param max_results: int (optional) Maximum number of runs desired. Max threshold is 50000 :param order_by: List[str] (optional) List of columns to be ordered by, including attributes, params, metrics, and tags with an optional - "DESC" or "ASC" annotation, where "ASC" is the default. Example: ["params.input DESC", - "metrics.alpha ASC", "metrics.rmse"] Tiebreaks are done by start_time DESC followed by run_id for - runs with the same start time (and this is the default ordering criterion if order_by is not + `"DESC"` or `"ASC"` annotation, where `"ASC"` is the default. Example: `["params.input DESC", + "metrics.alpha ASC", "metrics.rmse"]`. Tiebreaks are done by start_time `DESC` followed by `run_id` + for runs with the same start time (and this is the default ordering criterion if order_by is not provided). :param page_token: str (optional) Token for the current page of runs. - :param run_view_type: :class:`SearchRunsRunViewType` (optional) + :param run_view_type: :class:`ViewType` (optional) Whether to display only active, only deleted, or all runs. Defaults to only active runs. - + :returns: Iterator over :class:`Run` .. py:method:: set_experiment_tag(experiment_id: str, key: str, value: str) - Set a tag. - + Set a tag for an experiment. + Sets a tag on an experiment. Experiment tags are metadata that can be updated. - + :param experiment_id: str ID of the experiment under which to log the tag. Must be provided. :param key: str - Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size. + Name of the tag. Keys up to 250 bytes in size are supported. :param value: str - String value of the tag being logged. Maximum size depends on storage backend. All storage backends - are guaranteed to support key values up to 5000 bytes in size. - - + String value of the tag being logged. Values up to 64KB in size are supported. + + .. py:method:: set_permissions(experiment_id: str [, access_control_list: Optional[List[ExperimentAccessControlRequest]]]) -> ExperimentPermissions Set experiment permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param experiment_id: str The experiment for which to get or manage permissions. :param access_control_list: List[:class:`ExperimentAccessControlRequest`] (optional) - + :returns: :class:`ExperimentPermissions` .. py:method:: set_tag(key: str, value: str [, run_id: Optional[str], run_uuid: Optional[str]]) - Set a tag. - + Set a tag for a run. + Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes. - + :param key: str - Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to - support key values up to 250 bytes in size. + Name of the tag. Keys up to 250 bytes in size are supported. :param value: str - String value of the tag being logged. Maximum size depends on storage backend. All storage backends - are guaranteed to support key values up to 5000 bytes in size. + String value of the tag being logged. Values up to 64KB in size are supported. :param run_id: str (optional) ID of the run under which to log the tag. Must be provided. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run under which to log the tag. This field will be + [Deprecated, use `run_id` instead] ID of the run under which to log the tag. This field will be removed in a future MLflow version. - - + + .. py:method:: update_experiment(experiment_id: str [, new_name: Optional[str]]) @@ -622,39 +632,39 @@ w = WorkspaceClient() - experiment = w.experiments.create_experiment(name=f'sdk-{time.time_ns()}') + experiment = w.experiments.create_experiment(name=f"sdk-{time.time_ns()}") - w.experiments.update_experiment(new_name=f'sdk-{time.time_ns()}', experiment_id=experiment.experiment_id) + w.experiments.update_experiment(new_name=f"sdk-{time.time_ns()}", experiment_id=experiment.experiment_id) # cleanup w.experiments.delete_experiment(experiment_id=experiment.experiment_id) Update an experiment. - + Updates experiment metadata. - + :param experiment_id: str ID of the associated experiment. :param new_name: str (optional) If provided, the experiment's name is changed to the new name. The new name must be unique. - - + + .. py:method:: update_permissions(experiment_id: str [, access_control_list: Optional[List[ExperimentAccessControlRequest]]]) -> ExperimentPermissions Update experiment permissions. - + Updates the permissions on an experiment. Experiments can inherit permissions from their root object. - + :param experiment_id: str The experiment for which to get or manage permissions. :param access_control_list: List[:class:`ExperimentAccessControlRequest`] (optional) - + :returns: :class:`ExperimentPermissions` - .. py:method:: update_run( [, end_time: Optional[int], run_id: Optional[str], run_uuid: Optional[str], status: Optional[UpdateRunStatus]]) -> UpdateRunResponse + .. py:method:: update_run( [, end_time: Optional[int], run_id: Optional[str], run_name: Optional[str], run_uuid: Optional[str], status: Optional[UpdateRunStatus]]) -> UpdateRunResponse Usage: @@ -668,10 +678,12 @@ w = WorkspaceClient() - experiment = w.experiments.create_experiment(name=f'sdk-{time.time_ns()}') + experiment = w.experiments.create_experiment(name=f"sdk-{time.time_ns()}") - created = w.experiments.create_run(experiment_id=experiment.experiment_id, - tags=[ml.RunTag(key="foo", value="bar")]) + created = w.experiments.create_run( + experiment_id=experiment.experiment_id, + tags=[ml.RunTag(key="foo", value="bar")], + ) _ = w.experiments.update_run(run_id=created.run.info.run_id, status=ml.UpdateRunStatus.KILLED) @@ -680,18 +692,20 @@ w.experiments.delete_run(run_id=created.run.info.run_id) Update a run. - + Updates run metadata. - + :param end_time: int (optional) Unix timestamp in milliseconds of when the run ended. :param run_id: str (optional) ID of the run to update. Must be provided. + :param run_name: str (optional) + Updated name of the run. :param run_uuid: str (optional) - [Deprecated, use run_id instead] ID of the run to update.. This field will be removed in a future + [Deprecated, use `run_id` instead] ID of the run to update. This field will be removed in a future MLflow version. :param status: :class:`UpdateRunStatus` (optional) Updated status of the run. - + :returns: :class:`UpdateRunResponse` \ No newline at end of file diff --git a/docs/workspace/ml/model_registry.rst b/docs/workspace/ml/model_registry.rst index d08a85415..0f6b49ac8 100644 --- a/docs/workspace/ml/model_registry.rst +++ b/docs/workspace/ml/model_registry.rst @@ -8,35 +8,35 @@ [Models in Unity Catalog](/api/workspace/registeredmodels) instead. Models in Unity Catalog provides centralized model governance, cross-workspace access, lineage, and deployment. Workspace Model Registry will be deprecated in the future. - + The Workspace Model Registry is a centralized model repository and a UI and set of APIs that enable you to manage the full lifecycle of MLflow Models. .. py:method:: approve_transition_request(name: str, version: str, stage: Stage, archive_existing_versions: bool [, comment: Optional[str]]) -> ApproveTransitionRequestResponse Approve transition request. - + Approves a model version stage transition request. - + :param name: str Name of the model. :param version: str Version of the model. :param stage: :class:`Stage` Target stage of the transition. Valid values are: - + * `None`: The initial stage of a model version. - + * `Staging`: Staging or pre-production stage. - + * `Production`: Production stage. - + * `Archived`: Archived stage. :param archive_existing_versions: bool Specifies whether to archive all current model versions in the target stage. :param comment: str (optional) User-provided comment on the action. - + :returns: :class:`ApproveTransitionRequestResponse` @@ -53,29 +53,31 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") mv = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp") - created = w.model_registry.create_comment(comment=f'sdk-{time.time_ns()}', - name=mv.model_version.name, - version=mv.model_version.version) + created = w.model_registry.create_comment( + comment=f"sdk-{time.time_ns()}", + name=mv.model_version.name, + version=mv.model_version.version, + ) # cleanup w.model_registry.delete_comment(id=created.comment.id) Post a comment. - + Posts a comment on a model version. A comment can be submitted either by a user or programmatically to display relevant information about the model. For example, test results or deployment errors. - + :param name: str Name of the model. :param version: str Version of the model. :param comment: str User-provided comment on the action. - + :returns: :class:`CreateCommentResponse` @@ -92,21 +94,21 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") Create a model. - + Creates a new registered model with the name specified in the request body. - + Throws `RESOURCE_ALREADY_EXISTS` if a registered model with the given name exists. - + :param name: str Register models under this name :param description: str (optional) Optional description for registered model. :param tags: List[:class:`ModelTag`] (optional) Additional metadata for registered model. - + :returns: :class:`CreateModelResponse` @@ -123,14 +125,14 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") mv = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp") Create a model version. - + Creates a model version. - + :param name: str Register model under this name :param source: str @@ -145,33 +147,33 @@ hosted at another instance of MLflow. :param tags: List[:class:`ModelVersionTag`] (optional) Additional metadata for model version. - + :returns: :class:`CreateModelVersionResponse` .. py:method:: create_transition_request(name: str, version: str, stage: Stage [, comment: Optional[str]]) -> CreateTransitionRequestResponse Make a transition request. - + Creates a model version stage transition request. - + :param name: str Name of the model. :param version: str Version of the model. :param stage: :class:`Stage` Target stage of the transition. Valid values are: - + * `None`: The initial stage of a model version. - + * `Staging`: Staging or pre-production stage. - + * `Production`: Production stage. - + * `Archived`: Archived stage. :param comment: str (optional) User-provided comment on the action. - + :returns: :class:`CreateTransitionRequestResponse` @@ -189,47 +191,49 @@ w = WorkspaceClient() - created = w.model_registry.create_webhook(description=f'sdk-{time.time_ns()}', - events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED], - http_url_spec=ml.HttpUrlSpec(url=w.config.host)) + created = w.model_registry.create_webhook( + description=f"sdk-{time.time_ns()}", + events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED], + http_url_spec=ml.HttpUrlSpec(url=w.config.host), + ) # cleanup w.model_registry.delete_webhook(id=created.webhook.id) Create a webhook. - + **NOTE**: This endpoint is in Public Preview. - + Creates a registry webhook. - + :param events: List[:class:`RegistryWebhookEvent`] Events that can trigger a registry webhook: * `MODEL_VERSION_CREATED`: A new model version was created for the associated model. - + * `MODEL_VERSION_TRANSITIONED_STAGE`: A model version’s stage was changed. - + * `TRANSITION_REQUEST_CREATED`: A user requested a model version’s stage be transitioned. - + * `COMMENT_CREATED`: A user wrote a comment on a registered model. - + * `REGISTERED_MODEL_CREATED`: A new registered model was created. This event type can only be specified for a registry-wide webhook, which can be created by not specifying a model name in the create request. - + * `MODEL_VERSION_TAG_SET`: A user set a tag on the model version. - + * `MODEL_VERSION_TRANSITIONED_TO_STAGING`: A model version was transitioned to staging. - + * `MODEL_VERSION_TRANSITIONED_TO_PRODUCTION`: A model version was transitioned to production. - + * `MODEL_VERSION_TRANSITIONED_TO_ARCHIVED`: A model version was archived. - + * `TRANSITION_REQUEST_TO_STAGING_CREATED`: A user requested a model version be transitioned to staging. - + * `TRANSITION_REQUEST_TO_PRODUCTION_CREATED`: A user requested a model version be transitioned to production. - + * `TRANSITION_REQUEST_TO_ARCHIVED_CREATED`: A user requested a model version be archived. :param description: str (optional) User-specified description for the webhook. @@ -240,73 +244,73 @@ :param status: :class:`RegistryWebhookStatus` (optional) Enable or disable triggering the webhook, or put the webhook into test mode. The default is `ACTIVE`: * `ACTIVE`: Webhook is triggered when an associated event happens. - + * `DISABLED`: Webhook is not triggered. - + * `TEST_MODE`: Webhook can be triggered through the test endpoint, but is not triggered on a real event. - + :returns: :class:`CreateWebhookResponse` .. py:method:: delete_comment(id: str) Delete a comment. - + Deletes a comment on a model version. - + :param id: str - - + + .. py:method:: delete_model(name: str) Delete a model. - + Deletes a registered model. - + :param name: str Registered model unique name identifier. - - + + .. py:method:: delete_model_tag(name: str, key: str) Delete a model tag. - + Deletes the tag for a registered model. - + :param name: str Name of the registered model that the tag was logged under. :param key: str Name of the tag. The name must be an exact match; wild-card deletion is not supported. Maximum size is 250 bytes. - - + + .. py:method:: delete_model_version(name: str, version: str) Delete a model version. - + Deletes a model version. - + :param name: str Name of the registered model :param version: str Model version number - - + + .. py:method:: delete_model_version_tag(name: str, version: str, key: str) Delete a model version tag. - + Deletes a model version tag. - + :param name: str Name of the registered model that the tag was logged under. :param version: str @@ -314,64 +318,64 @@ :param key: str Name of the tag. The name must be an exact match; wild-card deletion is not supported. Maximum size is 250 bytes. - - + + .. py:method:: delete_transition_request(name: str, version: str, stage: DeleteTransitionRequestStage, creator: str [, comment: Optional[str]]) Delete a transition request. - + Cancels a model version stage transition request. - + :param name: str Name of the model. :param version: str Version of the model. :param stage: :class:`DeleteTransitionRequestStage` Target stage of the transition request. Valid values are: - + * `None`: The initial stage of a model version. - + * `Staging`: Staging or pre-production stage. - + * `Production`: Production stage. - + * `Archived`: Archived stage. :param creator: str Username of the user who created this request. Of the transition requests matching the specified details, only the one transition created by this user will be deleted. :param comment: str (optional) User-provided comment on the action. - - + + .. py:method:: delete_webhook( [, id: Optional[str]]) Delete a webhook. - + **NOTE:** This endpoint is in Public Preview. - + Deletes a registry webhook. - + :param id: str (optional) Webhook ID required to delete a registry webhook. - - + + .. py:method:: get_latest_versions(name: str [, stages: Optional[List[str]]]) -> Iterator[ModelVersion] Get the latest version. - + Gets the latest version of a registered model. - + :param name: str Registered model unique name identifier. :param stages: List[str] (optional) List of stages. - + :returns: Iterator over :class:`ModelVersion` @@ -388,74 +392,74 @@ w = WorkspaceClient() - created = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + created = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") model = w.model_registry.get_model(name=created.registered_model.name) Get model. - + Get the details of a model. This is a Databricks workspace version of the [MLflow endpoint] that also returns the model's Databricks workspace ID and the permission level of the requesting user on the model. - + [MLflow endpoint]: https://www.mlflow.org/docs/latest/rest-api.html#get-registeredmodel - + :param name: str Registered model unique name identifier. - + :returns: :class:`GetModelResponse` .. py:method:: get_model_version(name: str, version: str) -> GetModelVersionResponse Get a model version. - + Get a model version. - + :param name: str Name of the registered model :param version: str Model version number - + :returns: :class:`GetModelVersionResponse` .. py:method:: get_model_version_download_uri(name: str, version: str) -> GetModelVersionDownloadUriResponse Get a model version URI. - + Gets a URI to download the model version. - + :param name: str Name of the registered model :param version: str Model version number - + :returns: :class:`GetModelVersionDownloadUriResponse` .. py:method:: get_permission_levels(registered_model_id: str) -> GetRegisteredModelPermissionLevelsResponse Get registered model permission levels. - + Gets the permission levels that a user can have on an object. - + :param registered_model_id: str The registered model for which to get or manage permissions. - + :returns: :class:`GetRegisteredModelPermissionLevelsResponse` .. py:method:: get_permissions(registered_model_id: str) -> RegisteredModelPermissions Get registered model permissions. - + Gets the permissions of a registered model. Registered models can inherit permissions from their root object. - + :param registered_model_id: str The registered model for which to get or manage permissions. - + :returns: :class:`RegisteredModelPermissions` @@ -474,28 +478,28 @@ all = w.model_registry.list_models(ml.ListModelsRequest()) List models. - + Lists all available registered models, up to the limit specified in __max_results__. - + :param max_results: int (optional) Maximum number of registered models desired. Max threshold is 1000. :param page_token: str (optional) Pagination token to go to the next page based on a previous query. - + :returns: Iterator over :class:`Model` .. py:method:: list_transition_requests(name: str, version: str) -> Iterator[Activity] List transition requests. - + Gets a list of all open stage transition requests for the model version. - + :param name: str Name of the model. :param version: str Version of the model. - + :returns: Iterator over :class:`Activity` @@ -514,11 +518,11 @@ all = w.model_registry.list_webhooks(ml.ListWebhooksRequest()) List registry webhooks. - + **NOTE:** This endpoint is in Public Preview. - + Lists all registry webhooks. - + :param events: List[:class:`RegistryWebhookEvent`] (optional) If `events` is specified, any webhook with one or more of the specified trigger events is included in the output. If `events` is not specified, webhooks of all event types are included in the output. @@ -527,56 +531,56 @@ associated model. :param page_token: str (optional) Token indicating the page of artifact results to fetch - + :returns: Iterator over :class:`RegistryWebhook` .. py:method:: reject_transition_request(name: str, version: str, stage: Stage [, comment: Optional[str]]) -> RejectTransitionRequestResponse Reject a transition request. - + Rejects a model version stage transition request. - + :param name: str Name of the model. :param version: str Version of the model. :param stage: :class:`Stage` Target stage of the transition. Valid values are: - + * `None`: The initial stage of a model version. - + * `Staging`: Staging or pre-production stage. - + * `Production`: Production stage. - + * `Archived`: Archived stage. :param comment: str (optional) User-provided comment on the action. - + :returns: :class:`RejectTransitionRequestResponse` .. py:method:: rename_model(name: str [, new_name: Optional[str]]) -> RenameModelResponse Rename a model. - + Renames a registered model. - + :param name: str Registered model unique name identifier. :param new_name: str (optional) If provided, updates the name for this `registered_model`. - + :returns: :class:`RenameModelResponse` .. py:method:: search_model_versions( [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) -> Iterator[ModelVersion] Searches model versions. - + Searches for specific model versions based on the supplied __filter__. - + :param filter: str (optional) String filter condition, like "name='my-model-name'". Must be a single boolean condition, with string values wrapped in single quotes. @@ -588,16 +592,16 @@ timestamp, followed by name ASC, followed by version DESC. :param page_token: str (optional) Pagination token to go to next page based on previous search query. - + :returns: Iterator over :class:`ModelVersion` .. py:method:: search_models( [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) -> Iterator[Model] Search models. - + Search for registered models based on the specified __filter__. - + :param filter: str (optional) String filter condition, like "name LIKE 'my-model-name'". Interpreted in the backend automatically as "name LIKE '%my-model-name%'". Single boolean condition, with string values wrapped in single @@ -610,16 +614,16 @@ name ASC. :param page_token: str (optional) Pagination token to go to the next page based on a previous search query. - + :returns: Iterator over :class:`Model` .. py:method:: set_model_tag(name: str, key: str, value: str) Set a tag. - + Sets a tag on a registered model. - + :param name: str Unique name of the model. :param key: str @@ -629,16 +633,16 @@ :param value: str String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size. - - + + .. py:method:: set_model_version_tag(name: str, version: str, key: str, value: str) Set a version tag. - + Sets a model version tag. - + :param name: str Unique name of the model. :param version: str @@ -650,69 +654,69 @@ :param value: str String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size. - - + + .. py:method:: set_permissions(registered_model_id: str [, access_control_list: Optional[List[RegisteredModelAccessControlRequest]]]) -> RegisteredModelPermissions Set registered model permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param registered_model_id: str The registered model for which to get or manage permissions. :param access_control_list: List[:class:`RegisteredModelAccessControlRequest`] (optional) - + :returns: :class:`RegisteredModelPermissions` .. py:method:: test_registry_webhook(id: str [, event: Optional[RegistryWebhookEvent]]) -> TestRegistryWebhookResponse Test a webhook. - + **NOTE:** This endpoint is in Public Preview. - + Tests a registry webhook. - + :param id: str Webhook ID :param event: :class:`RegistryWebhookEvent` (optional) If `event` is specified, the test trigger uses the specified event. If `event` is not specified, the test trigger uses a randomly chosen event associated with the webhook. - + :returns: :class:`TestRegistryWebhookResponse` .. py:method:: transition_stage(name: str, version: str, stage: Stage, archive_existing_versions: bool [, comment: Optional[str]]) -> TransitionStageResponse Transition a stage. - + Transition a model version's stage. This is a Databricks workspace version of the [MLflow endpoint] that also accepts a comment associated with the transition to be recorded.", - + [MLflow endpoint]: https://www.mlflow.org/docs/latest/rest-api.html#transition-modelversion-stage - + :param name: str Name of the model. :param version: str Version of the model. :param stage: :class:`Stage` Target stage of the transition. Valid values are: - + * `None`: The initial stage of a model version. - + * `Staging`: Staging or pre-production stage. - + * `Production`: Production stage. - + * `Archived`: Archived stage. :param archive_existing_versions: bool Specifies whether to archive all current model versions in the target stage. :param comment: str (optional) User-provided comment on the action. - + :returns: :class:`TransitionStageResponse` @@ -729,28 +733,30 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") mv = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp") - created = w.model_registry.create_comment(comment=f'sdk-{time.time_ns()}', - name=mv.model_version.name, - version=mv.model_version.version) + created = w.model_registry.create_comment( + comment=f"sdk-{time.time_ns()}", + name=mv.model_version.name, + version=mv.model_version.version, + ) - _ = w.model_registry.update_comment(comment=f'sdk-{time.time_ns()}', id=created.comment.id) + _ = w.model_registry.update_comment(comment=f"sdk-{time.time_ns()}", id=created.comment.id) # cleanup w.model_registry.delete_comment(id=created.comment.id) Update a comment. - + Post an edit to a comment on a model version. - + :param id: str Unique identifier of an activity :param comment: str User-provided comment on the action. - + :returns: :class:`UpdateCommentResponse` @@ -767,24 +773,26 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp") - w.model_registry.update_model_version(description=f'sdk-{time.time_ns()}', - name=created.model_version.name, - version=created.model_version.version) + w.model_registry.update_model_version( + description=f"sdk-{time.time_ns()}", + name=created.model_version.name, + version=created.model_version.version, + ) Update model. - + Updates a registered model. - + :param name: str Registered model unique name identifier. :param description: str (optional) If provided, updates the description for this `registered_model`. - - + + .. py:method:: update_model_version(name: str, version: str [, description: Optional[str]]) @@ -800,39 +808,41 @@ w = WorkspaceClient() - model = w.model_registry.create_model(name=f'sdk-{time.time_ns()}') + model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}") created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp") - w.model_registry.update_model_version(description=f'sdk-{time.time_ns()}', - name=created.model_version.name, - version=created.model_version.version) + w.model_registry.update_model_version( + description=f"sdk-{time.time_ns()}", + name=created.model_version.name, + version=created.model_version.version, + ) Update model version. - + Updates the model version. - + :param name: str Name of the registered model :param version: str Model version number :param description: str (optional) If provided, updates the description for this `registered_model`. - - + + .. py:method:: update_permissions(registered_model_id: str [, access_control_list: Optional[List[RegisteredModelAccessControlRequest]]]) -> RegisteredModelPermissions Update registered model permissions. - + Updates the permissions on a registered model. Registered models can inherit permissions from their root object. - + :param registered_model_id: str The registered model for which to get or manage permissions. :param access_control_list: List[:class:`RegisteredModelAccessControlRequest`] (optional) - + :returns: :class:`RegisteredModelPermissions` @@ -850,21 +860,23 @@ w = WorkspaceClient() - created = w.model_registry.create_webhook(description=f'sdk-{time.time_ns()}', - events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED], - http_url_spec=ml.HttpUrlSpec(url=w.config.host)) + created = w.model_registry.create_webhook( + description=f"sdk-{time.time_ns()}", + events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED], + http_url_spec=ml.HttpUrlSpec(url=w.config.host), + ) - w.model_registry.update_webhook(id=created.webhook.id, description=f'sdk-{time.time_ns()}') + w.model_registry.update_webhook(id=created.webhook.id, description=f"sdk-{time.time_ns()}") # cleanup w.model_registry.delete_webhook(id=created.webhook.id) Update a webhook. - + **NOTE:** This endpoint is in Public Preview. - + Updates a registry webhook. - + :param id: str Webhook ID :param description: str (optional) @@ -872,42 +884,42 @@ :param events: List[:class:`RegistryWebhookEvent`] (optional) Events that can trigger a registry webhook: * `MODEL_VERSION_CREATED`: A new model version was created for the associated model. - + * `MODEL_VERSION_TRANSITIONED_STAGE`: A model version’s stage was changed. - + * `TRANSITION_REQUEST_CREATED`: A user requested a model version’s stage be transitioned. - + * `COMMENT_CREATED`: A user wrote a comment on a registered model. - + * `REGISTERED_MODEL_CREATED`: A new registered model was created. This event type can only be specified for a registry-wide webhook, which can be created by not specifying a model name in the create request. - + * `MODEL_VERSION_TAG_SET`: A user set a tag on the model version. - + * `MODEL_VERSION_TRANSITIONED_TO_STAGING`: A model version was transitioned to staging. - + * `MODEL_VERSION_TRANSITIONED_TO_PRODUCTION`: A model version was transitioned to production. - + * `MODEL_VERSION_TRANSITIONED_TO_ARCHIVED`: A model version was archived. - + * `TRANSITION_REQUEST_TO_STAGING_CREATED`: A user requested a model version be transitioned to staging. - + * `TRANSITION_REQUEST_TO_PRODUCTION_CREATED`: A user requested a model version be transitioned to production. - + * `TRANSITION_REQUEST_TO_ARCHIVED_CREATED`: A user requested a model version be archived. :param http_url_spec: :class:`HttpUrlSpec` (optional) :param job_spec: :class:`JobSpec` (optional) :param status: :class:`RegistryWebhookStatus` (optional) Enable or disable triggering the webhook, or put the webhook into test mode. The default is `ACTIVE`: * `ACTIVE`: Webhook is triggered when an associated event happens. - + * `DISABLED`: Webhook is not triggered. - + * `TEST_MODE`: Webhook can be triggered through the test endpoint, but is not triggered on a real event. - - + + \ No newline at end of file diff --git a/docs/workspace/pipelines/pipelines.rst b/docs/workspace/pipelines/pipelines.rst index ec31991ef..38f440147 100644 --- a/docs/workspace/pipelines/pipelines.rst +++ b/docs/workspace/pipelines/pipelines.rst @@ -5,11 +5,11 @@ .. py:class:: PipelinesAPI The Delta Live Tables API allows you to create, edit, delete, start, and view details about pipelines. - + Delta Live Tables is a framework for building reliable, maintainable, and testable data processing pipelines. You define the transformations to perform on your data, and Delta Live Tables manages task orchestration, cluster management, monitoring, data quality, and error handling. - + Instead of defining your data pipelines using a series of separate Apache Spark tasks, Delta Live Tables manages how your data is transformed based on a target schema you define for each processing step. You can also enforce data quality with Delta Live Tables expectations. Expectations allow you to define expected @@ -30,29 +30,32 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" created = w.pipelines.create( continuous=False, - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", libraries=[pipelines.PipelineLibrary(notebook=pipelines.NotebookLibrary(path=notebook_path))], clusters=[ - pipelines.PipelineCluster(instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - label="default", - num_workers=1, - custom_tags={ - "cluster_type": "default", - }) - ]) + pipelines.PipelineCluster( + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + label="default", + num_workers=1, + custom_tags={ + "cluster_type": "default", + }, + ) + ], + ) # cleanup w.pipelines.delete(pipeline_id=created.pipeline_id) Create a pipeline. - + Creates a new data processing pipeline based on the requested configuration. If successful, this method returns the ID of the new pipeline. - + :param allow_duplicate_names: bool (optional) If false, deployment will fail if name conflicts with that of another pipeline. :param budget_policy_id: str (optional) @@ -98,7 +101,7 @@ :param run_as: :class:`RunAs` (optional) Write-only setting, available only in Create/Update calls. Specifies the user or service principal that the pipeline runs as. If not specified, the pipeline runs as the user who created the pipeline. - + Only `user_name` or `service_principal_name` can be specified. If both are specified, an error is thrown. :param schema: str (optional) @@ -113,19 +116,19 @@ to the Hive metastore or Unity Catalog. To publish to Unity Catalog, also specify `catalog`. :param trigger: :class:`PipelineTrigger` (optional) Which pipeline trigger to use. Deprecated: Use `continuous` instead. - + :returns: :class:`CreatePipelineResponse` .. py:method:: delete(pipeline_id: str) Delete a pipeline. - + Deletes a pipeline. - + :param pipeline_id: str - - + + .. py:method:: get(pipeline_id: str) -> GetPipelineResponse @@ -143,20 +146,23 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" created = w.pipelines.create( continuous=False, - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", libraries=[pipelines.PipelineLibrary(notebook=pipelines.NotebookLibrary(path=notebook_path))], clusters=[ - pipelines.PipelineCluster(instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - label="default", - num_workers=1, - custom_tags={ - "cluster_type": "default", - }) - ]) + pipelines.PipelineCluster( + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + label="default", + num_workers=1, + custom_tags={ + "cluster_type": "default", + }, + ) + ], + ) by_id = w.pipelines.get(pipeline_id=created.pipeline_id) @@ -164,47 +170,47 @@ w.pipelines.delete(pipeline_id=created.pipeline_id) Get a pipeline. - + :param pipeline_id: str - + :returns: :class:`GetPipelineResponse` .. py:method:: get_permission_levels(pipeline_id: str) -> GetPipelinePermissionLevelsResponse Get pipeline permission levels. - + Gets the permission levels that a user can have on an object. - + :param pipeline_id: str The pipeline for which to get or manage permissions. - + :returns: :class:`GetPipelinePermissionLevelsResponse` .. py:method:: get_permissions(pipeline_id: str) -> PipelinePermissions Get pipeline permissions. - + Gets the permissions of a pipeline. Pipelines can inherit permissions from their root object. - + :param pipeline_id: str The pipeline for which to get or manage permissions. - + :returns: :class:`PipelinePermissions` .. py:method:: get_update(pipeline_id: str, update_id: str) -> GetUpdateResponse Get a pipeline update. - + Gets an update from an active pipeline. - + :param pipeline_id: str The ID of the pipeline. :param update_id: str The ID of the update. - + :returns: :class:`GetUpdateResponse` @@ -223,20 +229,23 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" created = w.pipelines.create( continuous=False, - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", libraries=[pipelines.PipelineLibrary(notebook=pipelines.NotebookLibrary(path=notebook_path))], clusters=[ - pipelines.PipelineCluster(instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - label="default", - num_workers=1, - custom_tags={ - "cluster_type": "default", - }) - ]) + pipelines.PipelineCluster( + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + label="default", + num_workers=1, + custom_tags={ + "cluster_type": "default", + }, + ) + ], + ) events = w.pipelines.list_pipeline_events(pipeline_id=created.pipeline_id) @@ -244,15 +253,15 @@ w.pipelines.delete(pipeline_id=created.pipeline_id) List pipeline events. - + Retrieves events for a pipeline. - + :param pipeline_id: str :param filter: str (optional) Criteria to select a subset of results, expressed using a SQL-like syntax. The supported filters are: 1. level='INFO' (or WARN or ERROR) 2. level in ('INFO', 'WARN') 3. id='[event-id]' 4. timestamp > 'TIMESTAMP' (or >=,<,<=,=) - + Composite expressions are supported, for example: level in ('ERROR', 'WARN') AND timestamp> '2021-07-22T06:37:33.083Z' :param max_results: int (optional) @@ -266,7 +275,7 @@ Page token returned by previous call. This field is mutually exclusive with all fields in this request except max_results. An error is returned if any fields other than max_results are set when this field is set. - + :returns: Iterator over :class:`PipelineEvent` @@ -285,16 +294,16 @@ all = w.pipelines.list_pipelines(pipelines.ListPipelinesRequest()) List pipelines. - + Lists pipelines defined in the Delta Live Tables system. - + :param filter: str (optional) Select a subset of results based on the specified criteria. The supported filters are: - + * `notebook=''` to select pipelines that reference the provided notebook path. * `name LIKE '[pattern]'` to select pipelines with a name that matches pattern. Wildcards are supported, for example: `name LIKE '%shopping%'` - + Composite filters are not supported. This field is optional. :param max_results: int (optional) The maximum number of entries to return in a single page. The system may return fewer than @@ -306,16 +315,16 @@ default is id asc. This field is optional. :param page_token: str (optional) Page token returned by previous call - + :returns: Iterator over :class:`PipelineStateInfo` .. py:method:: list_updates(pipeline_id: str [, max_results: Optional[int], page_token: Optional[str], until_update_id: Optional[str]]) -> ListUpdatesResponse List pipeline updates. - + List updates for an active pipeline. - + :param pipeline_id: str The pipeline to return updates for. :param max_results: int (optional) @@ -324,31 +333,31 @@ Page token returned by previous call :param until_update_id: str (optional) If present, returns updates until and including this update_id. - + :returns: :class:`ListUpdatesResponse` .. py:method:: set_permissions(pipeline_id: str [, access_control_list: Optional[List[PipelineAccessControlRequest]]]) -> PipelinePermissions Set pipeline permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param pipeline_id: str The pipeline for which to get or manage permissions. :param access_control_list: List[:class:`PipelineAccessControlRequest`] (optional) - + :returns: :class:`PipelinePermissions` .. py:method:: start_update(pipeline_id: str [, cause: Optional[StartUpdateCause], full_refresh: Optional[bool], full_refresh_selection: Optional[List[str]], refresh_selection: Optional[List[str]], validate_only: Optional[bool]]) -> StartUpdateResponse Start a pipeline. - + Starts a new update for the pipeline. If there is already an active update for the pipeline, the request will fail and the active update will remain running. - + :param pipeline_id: str :param cause: :class:`StartUpdateCause` (optional) :param full_refresh: bool (optional) @@ -364,19 +373,19 @@ :param validate_only: bool (optional) If true, this update only validates the correctness of pipeline source code but does not materialize or publish any datasets. - + :returns: :class:`StartUpdateResponse` .. py:method:: stop(pipeline_id: str) -> Wait[GetPipelineResponse] Stop a pipeline. - + Stops the pipeline by canceling the active update. If there is no active update for the pipeline, this request is a no-op. - + :param pipeline_id: str - + :returns: Long-running operation waiter for :class:`GetPipelineResponse`. See :method:wait_get_pipeline_idle for more details. @@ -400,41 +409,47 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" created = w.pipelines.create( continuous=False, - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", libraries=[pipelines.PipelineLibrary(notebook=pipelines.NotebookLibrary(path=notebook_path))], clusters=[ - pipelines.PipelineCluster(instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - label="default", - num_workers=1, - custom_tags={ - "cluster_type": "default", - }) - ]) + pipelines.PipelineCluster( + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + label="default", + num_workers=1, + custom_tags={ + "cluster_type": "default", + }, + ) + ], + ) w.pipelines.update( pipeline_id=created.pipeline_id, - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", libraries=[pipelines.PipelineLibrary(notebook=pipelines.NotebookLibrary(path=notebook_path))], clusters=[ - pipelines.PipelineCluster(instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], - label="default", - num_workers=1, - custom_tags={ - "cluster_type": "default", - }) - ]) + pipelines.PipelineCluster( + instance_pool_id=os.environ["TEST_INSTANCE_POOL_ID"], + label="default", + num_workers=1, + custom_tags={ + "cluster_type": "default", + }, + ) + ], + ) # cleanup w.pipelines.delete(pipeline_id=created.pipeline_id) Edit a pipeline. - + Updates a pipeline with the supplied configuration. - + :param pipeline_id: str Unique identifier for this pipeline. :param allow_duplicate_names: bool (optional) @@ -484,7 +499,7 @@ :param run_as: :class:`RunAs` (optional) Write-only setting, available only in Create/Update calls. Specifies the user or service principal that the pipeline runs as. If not specified, the pipeline runs as the user who created the pipeline. - + Only `user_name` or `service_principal_name` can be specified. If both are specified, an error is thrown. :param schema: str (optional) @@ -499,20 +514,20 @@ to the Hive metastore or Unity Catalog. To publish to Unity Catalog, also specify `catalog`. :param trigger: :class:`PipelineTrigger` (optional) Which pipeline trigger to use. Deprecated: Use `continuous` instead. - - + + .. py:method:: update_permissions(pipeline_id: str [, access_control_list: Optional[List[PipelineAccessControlRequest]]]) -> PipelinePermissions Update pipeline permissions. - + Updates the permissions on a pipeline. Pipelines can inherit permissions from their root object. - + :param pipeline_id: str The pipeline for which to get or manage permissions. :param access_control_list: List[:class:`PipelineAccessControlRequest`] (optional) - + :returns: :class:`PipelinePermissions` diff --git a/docs/workspace/serving/serving_endpoints.rst b/docs/workspace/serving/serving_endpoints.rst index 687976f5d..83609fc09 100644 --- a/docs/workspace/serving/serving_endpoints.rst +++ b/docs/workspace/serving/serving_endpoints.rst @@ -5,7 +5,7 @@ .. py:class:: ServingEndpointsExt The Serving Endpoints API allows you to create, update, and delete model serving endpoints. - + You can use a serving endpoint to serve models from the Databricks Model Registry or from Unity Catalog. Endpoints expose the underlying models as scalable REST API endpoints using serverless compute. This means the endpoints and associated compute resources are fully managed by Databricks and will not appear in your @@ -18,27 +18,29 @@ .. py:method:: build_logs(name: str, served_model_name: str) -> BuildLogsResponse Get build logs for a served model. - + Retrieves the build logs associated with the provided served model. - + :param name: str The name of the serving endpoint that the served model belongs to. This field is required. :param served_model_name: str The name of the served model that build logs will be retrieved for. This field is required. - + :returns: :class:`BuildLogsResponse` - .. py:method:: create(name: str [, ai_gateway: Optional[AiGatewayConfig], config: Optional[EndpointCoreConfigInput], rate_limits: Optional[List[RateLimit]], route_optimized: Optional[bool], tags: Optional[List[EndpointTag]]]) -> Wait[ServingEndpointDetailed] + .. py:method:: create(name: str [, ai_gateway: Optional[AiGatewayConfig], budget_policy_id: Optional[str], config: Optional[EndpointCoreConfigInput], rate_limits: Optional[List[RateLimit]], route_optimized: Optional[bool], tags: Optional[List[EndpointTag]]]) -> Wait[ServingEndpointDetailed] Create a new serving endpoint. - + :param name: str The name of the serving endpoint. This field is required and must be unique across a Databricks workspace. An endpoint name can consist of alphanumeric characters, dashes, and underscores. :param ai_gateway: :class:`AiGatewayConfig` (optional) The AI Gateway configuration for the serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported. + :param budget_policy_id: str (optional) + The budget policy to be applied to the serving endpoint. :param config: :class:`EndpointCoreConfigInput` (optional) The core config of the serving endpoint. :param rate_limits: List[:class:`RateLimit`] (optional) @@ -48,46 +50,46 @@ Enable route optimization for the serving endpoint. :param tags: List[:class:`EndpointTag`] (optional) Tags to be attached to the serving endpoint and automatically propagated to billing logs. - + :returns: Long-running operation waiter for :class:`ServingEndpointDetailed`. See :method:wait_get_serving_endpoint_not_updating for more details. - .. py:method:: create_and_wait(name: str [, ai_gateway: Optional[AiGatewayConfig], config: Optional[EndpointCoreConfigInput], rate_limits: Optional[List[RateLimit]], route_optimized: Optional[bool], tags: Optional[List[EndpointTag]], timeout: datetime.timedelta = 0:20:00]) -> ServingEndpointDetailed + .. py:method:: create_and_wait(name: str [, ai_gateway: Optional[AiGatewayConfig], budget_policy_id: Optional[str], config: Optional[EndpointCoreConfigInput], rate_limits: Optional[List[RateLimit]], route_optimized: Optional[bool], tags: Optional[List[EndpointTag]], timeout: datetime.timedelta = 0:20:00]) -> ServingEndpointDetailed .. py:method:: delete(name: str) Delete a serving endpoint. - + :param name: str - - + + .. py:method:: export_metrics(name: str) -> ExportMetricsResponse Get metrics of a serving endpoint. - + Retrieves the metrics associated with the provided serving endpoint in either Prometheus or OpenMetrics exposition format. - + :param name: str The name of the serving endpoint to retrieve metrics for. This field is required. - + :returns: :class:`ExportMetricsResponse` .. py:method:: get(name: str) -> ServingEndpointDetailed Get a single serving endpoint. - + Retrieves the details for a single serving endpoint. - + :param name: str The name of the serving endpoint. This field is required. - + :returns: :class:`ServingEndpointDetailed` @@ -100,38 +102,38 @@ .. py:method:: get_open_api(name: str) -> GetOpenApiResponse Get the schema for a serving endpoint. - + Get the query schema of the serving endpoint in OpenAPI format. The schema contains information for the supported paths, input and output format and datatypes. - + :param name: str The name of the serving endpoint that the served model belongs to. This field is required. - + :returns: :class:`GetOpenApiResponse` .. py:method:: get_permission_levels(serving_endpoint_id: str) -> GetServingEndpointPermissionLevelsResponse Get serving endpoint permission levels. - + Gets the permission levels that a user can have on an object. - + :param serving_endpoint_id: str The serving endpoint for which to get or manage permissions. - + :returns: :class:`GetServingEndpointPermissionLevelsResponse` .. py:method:: get_permissions(serving_endpoint_id: str) -> ServingEndpointPermissions Get serving endpoint permissions. - + Gets the permissions of a serving endpoint. Serving endpoints can inherit permissions from their root object. - + :param serving_endpoint_id: str The serving endpoint for which to get or manage permissions. - + :returns: :class:`ServingEndpointPermissions` @@ -158,62 +160,62 @@ .. py:method:: list() -> Iterator[ServingEndpoint] Get all serving endpoints. - + :returns: Iterator over :class:`ServingEndpoint` .. py:method:: logs(name: str, served_model_name: str) -> ServerLogsResponse Get the latest logs for a served model. - + Retrieves the service logs associated with the provided served model. - + :param name: str The name of the serving endpoint that the served model belongs to. This field is required. :param served_model_name: str The name of the served model that logs will be retrieved for. This field is required. - + :returns: :class:`ServerLogsResponse` .. py:method:: patch(name: str [, add_tags: Optional[List[EndpointTag]], delete_tags: Optional[List[str]]]) -> EndpointTags Update tags of a serving endpoint. - + Used to batch add and delete tags from a serving endpoint with a single API call. - + :param name: str The name of the serving endpoint who's tags to patch. This field is required. :param add_tags: List[:class:`EndpointTag`] (optional) List of endpoint tags to add :param delete_tags: List[str] (optional) List of tag keys to delete - + :returns: :class:`EndpointTags` .. py:method:: put(name: str [, rate_limits: Optional[List[RateLimit]]]) -> PutResponse Update rate limits of a serving endpoint. - + Used to update the rate limits of a serving endpoint. NOTE: Only foundation model endpoints are currently supported. For external models, use AI Gateway to manage rate limits. - + :param name: str The name of the serving endpoint whose rate limits are being updated. This field is required. :param rate_limits: List[:class:`RateLimit`] (optional) The list of endpoint rate limits. - + :returns: :class:`PutResponse` .. py:method:: put_ai_gateway(name: str [, guardrails: Optional[AiGatewayGuardrails], inference_table_config: Optional[AiGatewayInferenceTableConfig], rate_limits: Optional[List[AiGatewayRateLimit]], usage_tracking_config: Optional[AiGatewayUsageTrackingConfig]]) -> PutAiGatewayResponse Update AI Gateway of a serving endpoint. - + Used to update the AI Gateway of a serving endpoint. NOTE: Only external model and provisioned throughput endpoints are currently supported. - + :param name: str The name of the serving endpoint whose AI Gateway is being updated. This field is required. :param guardrails: :class:`AiGatewayGuardrails` (optional) @@ -226,14 +228,14 @@ :param usage_tracking_config: :class:`AiGatewayUsageTrackingConfig` (optional) Configuration to enable usage tracking using system tables. These tables allow you to monitor operational usage on endpoints and their associated costs. - + :returns: :class:`PutAiGatewayResponse` .. py:method:: query(name: str [, dataframe_records: Optional[List[Any]], dataframe_split: Optional[DataframeSplitInput], extra_params: Optional[Dict[str, str]], input: Optional[Any], inputs: Optional[Any], instances: Optional[List[Any]], max_tokens: Optional[int], messages: Optional[List[ChatMessage]], n: Optional[int], prompt: Optional[Any], stop: Optional[List[str]], stream: Optional[bool], temperature: Optional[float]]) -> QueryEndpointResponse Query a serving endpoint. - + :param name: str The name of the serving endpoint. This field is required. :param dataframe_records: List[Any] (optional) @@ -277,32 +279,32 @@ The temperature field used ONLY for __completions__ and __chat external & foundation model__ serving endpoints. This is a float between 0.0 and 2.0 with a default of 1.0 and should only be used with other chat/completions query fields. - + :returns: :class:`QueryEndpointResponse` .. py:method:: set_permissions(serving_endpoint_id: str [, access_control_list: Optional[List[ServingEndpointAccessControlRequest]]]) -> ServingEndpointPermissions Set serving endpoint permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param serving_endpoint_id: str The serving endpoint for which to get or manage permissions. :param access_control_list: List[:class:`ServingEndpointAccessControlRequest`] (optional) - + :returns: :class:`ServingEndpointPermissions` .. py:method:: update_config(name: str [, auto_capture_config: Optional[AutoCaptureConfigInput], served_entities: Optional[List[ServedEntityInput]], served_models: Optional[List[ServedModelInput]], traffic_config: Optional[TrafficConfig]]) -> Wait[ServingEndpointDetailed] Update config of a serving endpoint. - + Updates any combination of the serving endpoint's served entities, the compute configuration of those served entities, and the endpoint's traffic config. An endpoint that already has an update in progress can not be updated until the current update completes or fails. - + :param name: str The name of the serving endpoint to update. This field is required. :param auto_capture_config: :class:`AutoCaptureConfigInput` (optional) @@ -317,7 +319,7 @@ config. :param traffic_config: :class:`TrafficConfig` (optional) The traffic configuration associated with the serving endpoint config. - + :returns: Long-running operation waiter for :class:`ServingEndpointDetailed`. See :method:wait_get_serving_endpoint_not_updating for more details. @@ -329,14 +331,14 @@ .. py:method:: update_permissions(serving_endpoint_id: str [, access_control_list: Optional[List[ServingEndpointAccessControlRequest]]]) -> ServingEndpointPermissions Update serving endpoint permissions. - + Updates the permissions on a serving endpoint. Serving endpoints can inherit permissions from their root object. - + :param serving_endpoint_id: str The serving endpoint for which to get or manage permissions. :param access_control_list: List[:class:`ServingEndpointAccessControlRequest`] (optional) - + :returns: :class:`ServingEndpointPermissions` diff --git a/docs/workspace/serving/serving_endpoints_data_plane.rst b/docs/workspace/serving/serving_endpoints_data_plane.rst index 8fb09e7ff..bb22c3dd7 100644 --- a/docs/workspace/serving/serving_endpoints_data_plane.rst +++ b/docs/workspace/serving/serving_endpoints_data_plane.rst @@ -10,7 +10,7 @@ .. py:method:: query(name: str [, dataframe_records: Optional[List[Any]], dataframe_split: Optional[DataframeSplitInput], extra_params: Optional[Dict[str, str]], input: Optional[Any], inputs: Optional[Any], instances: Optional[List[Any]], max_tokens: Optional[int], messages: Optional[List[ChatMessage]], n: Optional[int], prompt: Optional[Any], stop: Optional[List[str]], stream: Optional[bool], temperature: Optional[float]]) -> QueryEndpointResponse Query a serving endpoint. - + :param name: str The name of the serving endpoint. This field is required. :param dataframe_records: List[Any] (optional) @@ -54,6 +54,6 @@ The temperature field used ONLY for __completions__ and __chat external & foundation model__ serving endpoints. This is a float between 0.0 and 2.0 with a default of 1.0 and should only be used with other chat/completions query fields. - + :returns: :class:`QueryEndpointResponse` \ No newline at end of file diff --git a/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst b/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst index 66c621997..1d5244f0a 100644 --- a/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst +++ b/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst @@ -10,42 +10,42 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteAibiDashboardEmbeddingAccessPolicySettingResponse Delete the AI/BI dashboard embedding access policy. - + Delete the AI/BI dashboard embedding access policy, reverting back to the default. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteAibiDashboardEmbeddingAccessPolicySettingResponse` .. py:method:: get( [, etag: Optional[str]]) -> AibiDashboardEmbeddingAccessPolicySetting Retrieve the AI/BI dashboard embedding access policy. - + Retrieves the AI/BI dashboard embedding access policy. The default setting is ALLOW_APPROVED_DOMAINS, permitting AI/BI dashboards to be embedded on approved domains. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`AibiDashboardEmbeddingAccessPolicySetting` .. py:method:: update(allow_missing: bool, setting: AibiDashboardEmbeddingAccessPolicySetting, field_mask: str) -> AibiDashboardEmbeddingAccessPolicySetting Update the AI/BI dashboard embedding access policy. - + Updates the AI/BI dashboard embedding access policy at the workspace level. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`AibiDashboardEmbeddingAccessPolicySetting` @@ -55,10 +55,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`AibiDashboardEmbeddingAccessPolicySetting` \ No newline at end of file diff --git a/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst b/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst index 0c9294130..546d9ad7d 100644 --- a/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst +++ b/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst @@ -10,43 +10,43 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteAibiDashboardEmbeddingApprovedDomainsSettingResponse Delete AI/BI dashboard embedding approved domains. - + Delete the list of domains approved to host embedded AI/BI dashboards, reverting back to the default empty list. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteAibiDashboardEmbeddingApprovedDomainsSettingResponse` .. py:method:: get( [, etag: Optional[str]]) -> AibiDashboardEmbeddingApprovedDomainsSetting Retrieve the list of domains approved to host embedded AI/BI dashboards. - + Retrieves the list of domains approved to host embedded AI/BI dashboards. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` .. py:method:: update(allow_missing: bool, setting: AibiDashboardEmbeddingApprovedDomainsSetting, field_mask: str) -> AibiDashboardEmbeddingApprovedDomainsSetting Update the list of domains approved to host embedded AI/BI dashboards. - + Updates the list of domains approved to host embedded AI/BI dashboards. This update will fail if the current workspace access policy is not ALLOW_APPROVED_DOMAINS. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` @@ -56,10 +56,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` \ No newline at end of file diff --git a/docs/workspace/settings/automatic_cluster_update.rst b/docs/workspace/settings/automatic_cluster_update.rst index 350e0e713..748cf428a 100644 --- a/docs/workspace/settings/automatic_cluster_update.rst +++ b/docs/workspace/settings/automatic_cluster_update.rst @@ -10,28 +10,28 @@ .. py:method:: get( [, etag: Optional[str]]) -> AutomaticClusterUpdateSetting Get the automatic cluster update setting. - + Gets the automatic cluster update setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`AutomaticClusterUpdateSetting` .. py:method:: update(allow_missing: bool, setting: AutomaticClusterUpdateSetting, field_mask: str) -> AutomaticClusterUpdateSetting Update the automatic cluster update setting. - + Updates the automatic cluster update setting for the workspace. A fresh etag needs to be provided in `PATCH` requests (as part of the setting field). The etag can be retrieved by making a `GET` request before the `PATCH` request. If the setting is updated concurrently, `PATCH` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`AutomaticClusterUpdateSetting` @@ -41,10 +41,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`AutomaticClusterUpdateSetting` \ No newline at end of file diff --git a/docs/workspace/settings/compliance_security_profile.rst b/docs/workspace/settings/compliance_security_profile.rst index 855451b82..807dcc1c6 100644 --- a/docs/workspace/settings/compliance_security_profile.rst +++ b/docs/workspace/settings/compliance_security_profile.rst @@ -6,34 +6,34 @@ Controls whether to enable the compliance security profile for the current workspace. Enabling it on a workspace is permanent. By default, it is turned off. - + This settings can NOT be disabled once it is enabled. .. py:method:: get( [, etag: Optional[str]]) -> ComplianceSecurityProfileSetting Get the compliance security profile setting. - + Gets the compliance security profile setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`ComplianceSecurityProfileSetting` .. py:method:: update(allow_missing: bool, setting: ComplianceSecurityProfileSetting, field_mask: str) -> ComplianceSecurityProfileSetting Update the compliance security profile setting. - + Updates the compliance security profile setting for the workspace. A fresh etag needs to be provided in `PATCH` requests (as part of the setting field). The etag can be retrieved by making a `GET` request before the `PATCH` request. If the setting is updated concurrently, `PATCH` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`ComplianceSecurityProfileSetting` @@ -43,10 +43,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`ComplianceSecurityProfileSetting` \ No newline at end of file diff --git a/docs/workspace/settings/credentials_manager.rst b/docs/workspace/settings/credentials_manager.rst index c8bfa4f30..ea3162f6c 100644 --- a/docs/workspace/settings/credentials_manager.rst +++ b/docs/workspace/settings/credentials_manager.rst @@ -10,16 +10,16 @@ .. py:method:: exchange_token(partition_id: PartitionId, token_type: List[TokenType], scopes: List[str]) -> ExchangeTokenResponse Exchange token. - + Exchange tokens with an Identity Provider to get a new access token. It allows specifying scopes to determine token permissions. - + :param partition_id: :class:`PartitionId` The partition of Credentials store :param token_type: List[:class:`TokenType`] A list of token types being requested :param scopes: List[str] Array of scopes for the token request. - + :returns: :class:`ExchangeTokenResponse` \ No newline at end of file diff --git a/docs/workspace/settings/default_namespace.rst b/docs/workspace/settings/default_namespace.rst index 960949930..a98d09b41 100644 --- a/docs/workspace/settings/default_namespace.rst +++ b/docs/workspace/settings/default_namespace.rst @@ -6,61 +6,61 @@ The default namespace setting API allows users to configure the default namespace for a Databricks workspace. - + Through this API, users can retrieve, set, or modify the default namespace used when queries do not reference a fully qualified three-level name. For example, if you use the API to set 'retail_prod' as the default catalog, then a query 'SELECT * FROM myTable' would reference the object 'retail_prod.default.myTable' (the schema 'default' is always assumed). - + This setting requires a restart of clusters and SQL warehouses to take effect. Additionally, the default namespace only applies when using Unity Catalog-enabled compute. .. py:method:: delete( [, etag: Optional[str]]) -> DeleteDefaultNamespaceSettingResponse Delete the default namespace setting. - + Deletes the default namespace setting for the workspace. A fresh etag needs to be provided in `DELETE` requests (as a query parameter). The etag can be retrieved by making a `GET` request before the `DELETE` request. If the setting is updated/deleted concurrently, `DELETE` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteDefaultNamespaceSettingResponse` .. py:method:: get( [, etag: Optional[str]]) -> DefaultNamespaceSetting Get the default namespace setting. - + Gets the default namespace setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DefaultNamespaceSetting` .. py:method:: update(allow_missing: bool, setting: DefaultNamespaceSetting, field_mask: str) -> DefaultNamespaceSetting Update the default namespace setting. - + Updates the default namespace setting for the workspace. A fresh etag needs to be provided in `PATCH` requests (as part of the setting field). The etag can be retrieved by making a `GET` request before the `PATCH` request. Note that if the setting does not exist, `GET` returns a NOT_FOUND error and the etag is present in the error response, which should be set in the `PATCH` request. If the setting is updated concurrently, `PATCH` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`DefaultNamespaceSetting` @@ -77,10 +77,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`DefaultNamespaceSetting` \ No newline at end of file diff --git a/docs/workspace/settings/disable_legacy_access.rst b/docs/workspace/settings/disable_legacy_access.rst index a015e777f..d7622f774 100644 --- a/docs/workspace/settings/disable_legacy_access.rst +++ b/docs/workspace/settings/disable_legacy_access.rst @@ -5,7 +5,7 @@ .. py:class:: DisableLegacyAccessAPI 'Disabling legacy access' has the following impacts: - + 1. Disables direct access to the Hive Metastore. However, you can still access Hive Metastore through HMS Federation. 2. Disables Fallback Mode (docs link) on any External Location access from the workspace. 3. Alters DBFS path access to use External Location permissions in place of legacy credentials. 4. Enforces @@ -14,41 +14,41 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteDisableLegacyAccessResponse Delete Legacy Access Disablement Status. - + Deletes legacy access disablement status. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteDisableLegacyAccessResponse` .. py:method:: get( [, etag: Optional[str]]) -> DisableLegacyAccess Retrieve Legacy Access Disablement Status. - + Retrieves legacy access disablement Status. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DisableLegacyAccess` .. py:method:: update(allow_missing: bool, setting: DisableLegacyAccess, field_mask: str) -> DisableLegacyAccess Update Legacy Access Disablement Status. - + Updates legacy access disablement status. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`DisableLegacyAccess` @@ -58,10 +58,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`DisableLegacyAccess` \ No newline at end of file diff --git a/docs/workspace/settings/disable_legacy_dbfs.rst b/docs/workspace/settings/disable_legacy_dbfs.rst index 502111fe4..e0d5b1610 100644 --- a/docs/workspace/settings/disable_legacy_dbfs.rst +++ b/docs/workspace/settings/disable_legacy_dbfs.rst @@ -10,41 +10,41 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteDisableLegacyDbfsResponse Delete the disable legacy DBFS setting. - + Deletes the disable legacy DBFS setting for a workspace, reverting back to the default. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteDisableLegacyDbfsResponse` .. py:method:: get( [, etag: Optional[str]]) -> DisableLegacyDbfs Get the disable legacy DBFS setting. - + Gets the disable legacy DBFS setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DisableLegacyDbfs` .. py:method:: update(allow_missing: bool, setting: DisableLegacyDbfs, field_mask: str) -> DisableLegacyDbfs Update the disable legacy DBFS setting. - + Updates the disable legacy DBFS setting for the workspace. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`DisableLegacyDbfs` @@ -54,10 +54,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`DisableLegacyDbfs` \ No newline at end of file diff --git a/docs/workspace/settings/enhanced_security_monitoring.rst b/docs/workspace/settings/enhanced_security_monitoring.rst index c9dfb547d..d0f9eee3d 100644 --- a/docs/workspace/settings/enhanced_security_monitoring.rst +++ b/docs/workspace/settings/enhanced_security_monitoring.rst @@ -7,35 +7,35 @@ Controls whether enhanced security monitoring is enabled for the current workspace. If the compliance security profile is enabled, this is automatically enabled. By default, it is disabled. However, if the compliance security profile is enabled, this is automatically enabled. - + If the compliance security profile is disabled, you can enable or disable this setting and it is not permanent. .. py:method:: get( [, etag: Optional[str]]) -> EnhancedSecurityMonitoringSetting Get the enhanced security monitoring setting. - + Gets the enhanced security monitoring setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`EnhancedSecurityMonitoringSetting` .. py:method:: update(allow_missing: bool, setting: EnhancedSecurityMonitoringSetting, field_mask: str) -> EnhancedSecurityMonitoringSetting Update the enhanced security monitoring setting. - + Updates the enhanced security monitoring setting for the workspace. A fresh etag needs to be provided in `PATCH` requests (as part of the setting field). The etag can be retrieved by making a `GET` request before the `PATCH` request. If the setting is updated concurrently, `PATCH` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`EnhancedSecurityMonitoringSetting` @@ -45,10 +45,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`EnhancedSecurityMonitoringSetting` \ No newline at end of file diff --git a/docs/workspace/settings/ip_access_lists.rst b/docs/workspace/settings/ip_access_lists.rst index a265c5943..03061165d 100644 --- a/docs/workspace/settings/ip_access_lists.rst +++ b/docs/workspace/settings/ip_access_lists.rst @@ -5,21 +5,21 @@ .. py:class:: IpAccessListsAPI IP Access List enables admins to configure IP access lists. - + IP access lists affect web application access and REST API access to this workspace only. If the feature is disabled for a workspace, all access is allowed for this workspace. There is support for allow lists (inclusion) and block lists (exclusion). - + When a connection is attempted: 1. **First, all block lists are checked.** If the connection IP address matches any block list, the connection is rejected. 2. **If the connection was not rejected by block lists**, the IP address is compared with the allow lists. - + If there is at least one allow list for the workspace, the connection is allowed only if the IP address matches an allow list. If there are no allow lists for the workspace, all IP addresses are allowed. - + For all allow lists and block lists combined, the workspace supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. - + After changes to the IP access list feature, it can take a few minutes for changes to take effect. .. py:method:: create(label: str, list_type: ListType [, ip_addresses: Optional[List[str]]]) -> CreateIpAccessListResponse @@ -36,52 +36,54 @@ w = WorkspaceClient() - created = w.ip_access_lists.create(label=f'sdk-{time.time_ns()}', - ip_addresses=["1.0.0.0/16"], - list_type=settings.ListType.BLOCK) + created = w.ip_access_lists.create( + label=f"sdk-{time.time_ns()}", + ip_addresses=["1.0.0.0/16"], + list_type=settings.ListType.BLOCK, + ) # cleanup w.ip_access_lists.delete(ip_access_list_id=created.ip_access_list.list_id) Create access list. - + Creates an IP access list for this workspace. - + A list can be an allow list or a block list. See the top of this file for a description of how the server treats allow lists and block lists at runtime. - + When creating or updating an IP access list: - + * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value `QUOTA_EXCEEDED`. * If the new list would block the calling user's current IP, error 400 is returned with `error_code` value `INVALID_STATE`. - + It can take a few minutes for the changes to take effect. **Note**: Your new IP access list has no effect until you enable the feature. See :method:workspaceconf/setStatus - + :param label: str Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. :param ip_addresses: List[str] (optional) - + :returns: :class:`CreateIpAccessListResponse` .. py:method:: delete(ip_access_list_id: str) Delete access list. - + Deletes an IP access list, specified by its list ID. - + :param ip_access_list_id: str The ID for the corresponding IP access list - - + + .. py:method:: get(ip_access_list_id: str) -> FetchIpAccessListResponse @@ -98,9 +100,11 @@ w = WorkspaceClient() - created = w.ip_access_lists.create(label=f'sdk-{time.time_ns()}', - ip_addresses=["1.0.0.0/16"], - list_type=settings.ListType.BLOCK) + created = w.ip_access_lists.create( + label=f"sdk-{time.time_ns()}", + ip_addresses=["1.0.0.0/16"], + list_type=settings.ListType.BLOCK, + ) by_id = w.ip_access_lists.get(ip_access_list_id=created.ip_access_list.list_id) @@ -108,12 +112,12 @@ w.ip_access_lists.delete(ip_access_list_id=created.ip_access_list.list_id) Get access list. - + Gets an IP access list, specified by its list ID. - + :param ip_access_list_id: str The ID for the corresponding IP access list - + :returns: :class:`FetchIpAccessListResponse` @@ -131,9 +135,9 @@ all = w.ip_access_lists.list() Get access lists. - + Gets all IP access lists for the specified workspace. - + :returns: Iterator over :class:`IpAccessListInfo` @@ -151,23 +155,27 @@ w = WorkspaceClient() - created = w.ip_access_lists.create(label=f'sdk-{time.time_ns()}', - ip_addresses=["1.0.0.0/16"], - list_type=settings.ListType.BLOCK) + created = w.ip_access_lists.create( + label=f"sdk-{time.time_ns()}", + ip_addresses=["1.0.0.0/16"], + list_type=settings.ListType.BLOCK, + ) - w.ip_access_lists.replace(ip_access_list_id=created.ip_access_list.list_id, - label=f'sdk-{time.time_ns()}', - ip_addresses=["1.0.0.0/24"], - list_type=settings.ListType.BLOCK, - enabled=False) + w.ip_access_lists.replace( + ip_access_list_id=created.ip_access_list.list_id, + label=f"sdk-{time.time_ns()}", + ip_addresses=["1.0.0.0/24"], + list_type=settings.ListType.BLOCK, + enabled=False, + ) # cleanup w.ip_access_lists.delete(ip_access_list_id=created.ip_access_list.list_id) Replace access list. - + Replaces an IP access list, specified by its ID. - + A list can include allow lists and block lists. See the top of this file for a description of how the server treats allow lists and block lists at run time. When replacing an IP access list: * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one @@ -176,42 +184,42 @@ returned with `error_code` value `INVALID_STATE`. It can take a few minutes for the changes to take effect. Note that your resulting IP access list has no effect until you enable the feature. See :method:workspaceconf/setStatus. - + :param ip_access_list_id: str The ID for the corresponding IP access list :param label: str Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. :param enabled: bool Specifies whether this IP access list is enabled. :param ip_addresses: List[str] (optional) - - + + .. py:method:: update(ip_access_list_id: str [, enabled: Optional[bool], ip_addresses: Optional[List[str]], label: Optional[str], list_type: Optional[ListType]]) Update access list. - + Updates an existing IP access list, specified by its ID. - + A list can include allow lists and block lists. See the top of this file for a description of how the server treats allow lists and block lists at run time. - + When updating an IP access list: - + * For all allow lists and block lists combined, the API supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value `QUOTA_EXCEEDED`. * If the updated list would block the calling user's current IP, error 400 is returned with `error_code` value `INVALID_STATE`. - + It can take a few minutes for the changes to take effect. Note that your resulting IP access list has no effect until you enable the feature. See :method:workspaceconf/setStatus. - + :param ip_access_list_id: str The ID for the corresponding IP access list :param enabled: bool (optional) @@ -221,9 +229,9 @@ Label for the IP access list. This **cannot** be empty. :param list_type: :class:`ListType` (optional) Type of IP access list. Valid values are as follows and are case-sensitive: - + * `ALLOW`: An allow list. Include this IP or range. * `BLOCK`: A block list. Exclude this IP or range. IP addresses in the block list are excluded even if they are included in an allow list. - - + + \ No newline at end of file diff --git a/docs/workspace/settings/notification_destinations.rst b/docs/workspace/settings/notification_destinations.rst index 8fb2d0c3c..45c8abea1 100644 --- a/docs/workspace/settings/notification_destinations.rst +++ b/docs/workspace/settings/notification_destinations.rst @@ -12,64 +12,64 @@ .. py:method:: create( [, config: Optional[Config], display_name: Optional[str]]) -> NotificationDestination Create a notification destination. - + Creates a notification destination. Requires workspace admin permissions. - + :param config: :class:`Config` (optional) The configuration for the notification destination. Must wrap EXACTLY one of the nested configs. :param display_name: str (optional) The display name for the notification destination. - + :returns: :class:`NotificationDestination` .. py:method:: delete(id: str) Delete a notification destination. - + Deletes a notification destination. Requires workspace admin permissions. - + :param id: str - - + + .. py:method:: get(id: str) -> NotificationDestination Get a notification destination. - + Gets a notification destination. - + :param id: str - + :returns: :class:`NotificationDestination` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ListNotificationDestinationsResult] List notification destinations. - + Lists notification destinations. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ListNotificationDestinationsResult` .. py:method:: update(id: str [, config: Optional[Config], display_name: Optional[str]]) -> NotificationDestination Update a notification destination. - + Updates a notification destination. Requires workspace admin permissions. At least one field is required in the request body. - + :param id: str UUID identifying notification destination. :param config: :class:`Config` (optional) The configuration for the notification destination. Must wrap EXACTLY one of the nested configs. :param display_name: str (optional) The display name for the notification destination. - + :returns: :class:`NotificationDestination` \ No newline at end of file diff --git a/docs/workspace/settings/restrict_workspace_admins.rst b/docs/workspace/settings/restrict_workspace_admins.rst index b025112cc..c2853d133 100644 --- a/docs/workspace/settings/restrict_workspace_admins.rst +++ b/docs/workspace/settings/restrict_workspace_admins.rst @@ -17,47 +17,47 @@ .. py:method:: delete( [, etag: Optional[str]]) -> DeleteRestrictWorkspaceAdminsSettingResponse Delete the restrict workspace admins setting. - + Reverts the restrict workspace admins setting status for the workspace. A fresh etag needs to be provided in `DELETE` requests (as a query parameter). The etag can be retrieved by making a `GET` request before the DELETE request. If the setting is updated/deleted concurrently, `DELETE` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`DeleteRestrictWorkspaceAdminsSettingResponse` .. py:method:: get( [, etag: Optional[str]]) -> RestrictWorkspaceAdminsSetting Get the restrict workspace admins setting. - + Gets the restrict workspace admins setting. - + :param etag: str (optional) etag used for versioning. The response is at least as fresh as the eTag provided. This is used for optimistic concurrency control as a way to help prevent simultaneous writes of a setting overwriting each other. It is strongly suggested that systems make use of the etag in the read -> delete pattern to perform setting deletions in order to avoid race conditions. That is, get an etag from a GET request, and pass it with the DELETE request to identify the rule set version you are deleting. - + :returns: :class:`RestrictWorkspaceAdminsSetting` .. py:method:: update(allow_missing: bool, setting: RestrictWorkspaceAdminsSetting, field_mask: str) -> RestrictWorkspaceAdminsSetting Update the restrict workspace admins setting. - + Updates the restrict workspace admins setting for the workspace. A fresh etag needs to be provided in `PATCH` requests (as part of the setting field). The etag can be retrieved by making a GET request before the `PATCH` request. If the setting is updated concurrently, `PATCH` fails with 409 and the request must be retried by using the fresh etag in the 409 response. - + :param allow_missing: bool This should always be set to true for Settings API. Added for AIP compliance. :param setting: :class:`RestrictWorkspaceAdminsSetting` @@ -67,10 +67,10 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. - + :returns: :class:`RestrictWorkspaceAdminsSetting` \ No newline at end of file diff --git a/docs/workspace/settings/settings.rst b/docs/workspace/settings/settings.rst index aa806280e..b2e435949 100644 --- a/docs/workspace/settings/settings.rst +++ b/docs/workspace/settings/settings.rst @@ -29,7 +29,7 @@ Controls whether to enable the compliance security profile for the current workspace. Enabling it on a workspace is permanent. By default, it is turned off. - + This settings can NOT be disabled once it is enabled. .. py:property:: default_namespace @@ -37,12 +37,12 @@ The default namespace setting API allows users to configure the default namespace for a Databricks workspace. - + Through this API, users can retrieve, set, or modify the default namespace used when queries do not reference a fully qualified three-level name. For example, if you use the API to set 'retail_prod' as the default catalog, then a query 'SELECT * FROM myTable' would reference the object 'retail_prod.default.myTable' (the schema 'default' is always assumed). - + This setting requires a restart of clusters and SQL warehouses to take effect. Additionally, the default namespace only applies when using Unity Catalog-enabled compute. @@ -50,7 +50,7 @@ :type: DisableLegacyAccessAPI 'Disabling legacy access' has the following impacts: - + 1. Disables direct access to the Hive Metastore. However, you can still access Hive Metastore through HMS Federation. 2. Disables Fallback Mode (docs link) on any External Location access from the workspace. 3. Alters DBFS path access to use External Location permissions in place of legacy credentials. 4. Enforces @@ -68,7 +68,7 @@ Controls whether enhanced security monitoring is enabled for the current workspace. If the compliance security profile is enabled, this is automatically enabled. By default, it is disabled. However, if the compliance security profile is enabled, this is automatically enabled. - + If the compliance security profile is disabled, you can enable or disable this setting and it is not permanent. diff --git a/docs/workspace/settings/token_management.rst b/docs/workspace/settings/token_management.rst index 50dbe1328..ceaa64cc6 100644 --- a/docs/workspace/settings/token_management.rst +++ b/docs/workspace/settings/token_management.rst @@ -23,8 +23,10 @@ groups = w.groups.group_display_name_to_id_map(iam.ListGroupsRequest()) - spn = w.service_principals.create(display_name=f'sdk-{time.time_ns()}', - groups=[iam.ComplexValue(value=groups["admins"])]) + spn = w.service_principals.create( + display_name=f"sdk-{time.time_ns()}", + groups=[iam.ComplexValue(value=groups["admins"])], + ) obo = w.token_management.create_obo_token(application_id=spn.application_id, lifetime_seconds=60) @@ -33,29 +35,29 @@ w.token_management.delete(token_id=obo.token_info.token_id) Create on-behalf token. - + Creates a token on behalf of a service principal. - + :param application_id: str Application ID of the service principal. :param comment: str (optional) Comment that describes the purpose of the token. :param lifetime_seconds: int (optional) The number of seconds before the token expires. - + :returns: :class:`CreateOboTokenResponse` .. py:method:: delete(token_id: str) Delete a token. - + Deletes a token, specified by its ID. - + :param token_id: str The ID of the token to revoke. - - + + .. py:method:: get(token_id: str) -> GetTokenResponse @@ -74,8 +76,10 @@ groups = w.groups.group_display_name_to_id_map(iam.ListGroupsRequest()) - spn = w.service_principals.create(display_name=f'sdk-{time.time_ns()}', - groups=[iam.ComplexValue(value=groups["admins"])]) + spn = w.service_principals.create( + display_name=f"sdk-{time.time_ns()}", + groups=[iam.ComplexValue(value=groups["admins"])], + ) obo = w.token_management.create_obo_token(application_id=spn.application_id, lifetime_seconds=60) @@ -86,30 +90,30 @@ w.token_management.delete(token_id=obo.token_info.token_id) Get token info. - + Gets information about a token, specified by its ID. - + :param token_id: str The ID of the token to get. - + :returns: :class:`GetTokenResponse` .. py:method:: get_permission_levels() -> GetTokenPermissionLevelsResponse Get token permission levels. - + Gets the permission levels that a user can have on an object. - + :returns: :class:`GetTokenPermissionLevelsResponse` .. py:method:: get_permissions() -> TokenPermissions Get token permissions. - + Gets the permissions of all tokens. Tokens can inherit permissions from their root object. - + :returns: :class:`TokenPermissions` @@ -128,36 +132,36 @@ all = w.token_management.list(settings.ListTokenManagementRequest()) List all tokens. - + Lists all tokens associated with the specified workspace or user. - + :param created_by_id: int (optional) User ID of the user that created the token. :param created_by_username: str (optional) Username of the user that created the token. - + :returns: Iterator over :class:`TokenInfo` .. py:method:: set_permissions( [, access_control_list: Optional[List[TokenAccessControlRequest]]]) -> TokenPermissions Set token permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param access_control_list: List[:class:`TokenAccessControlRequest`] (optional) - + :returns: :class:`TokenPermissions` .. py:method:: update_permissions( [, access_control_list: Optional[List[TokenAccessControlRequest]]]) -> TokenPermissions Update token permissions. - + Updates the permissions on all tokens. Tokens can inherit permissions from their root object. - + :param access_control_list: List[:class:`TokenAccessControlRequest`] (optional) - + :returns: :class:`TokenPermissions` \ No newline at end of file diff --git a/docs/workspace/settings/tokens.rst b/docs/workspace/settings/tokens.rst index 899db00d1..200eb9c83 100644 --- a/docs/workspace/settings/tokens.rst +++ b/docs/workspace/settings/tokens.rst @@ -20,39 +20,39 @@ w = WorkspaceClient() - token = w.tokens.create(comment=f'sdk-{time.time_ns()}', lifetime_seconds=300) + token = w.tokens.create(comment=f"sdk-{time.time_ns()}", lifetime_seconds=300) # cleanup w.tokens.delete(token_id=token.token_info.token_id) Create a user token. - + Creates and returns a token for a user. If this call is made through token authentication, it creates a token with the same client ID as the authenticated token. If the user's token quota is exceeded, this call returns an error **QUOTA_EXCEEDED**. - + :param comment: str (optional) Optional description to attach to the token. :param lifetime_seconds: int (optional) The lifetime of the token, in seconds. - + If the lifetime is not specified, this token remains valid indefinitely. - + :returns: :class:`CreateTokenResponse` .. py:method:: delete(token_id: str) Revoke token. - + Revokes an access token. - + If a token with the specified ID is not valid, this call returns an error **RESOURCE_DOES_NOT_EXIST**. - + :param token_id: str The ID of the token to be revoked. - - + + .. py:method:: list() -> Iterator[PublicTokenInfo] @@ -69,8 +69,8 @@ all = w.tokens.list() List tokens. - + Lists all the valid tokens for a user-workspace pair. - + :returns: Iterator over :class:`PublicTokenInfo` \ No newline at end of file diff --git a/docs/workspace/settings/workspace_conf.rst b/docs/workspace/settings/workspace_conf.rst index 3759de043..d73b16180 100644 --- a/docs/workspace/settings/workspace_conf.rst +++ b/docs/workspace/settings/workspace_conf.rst @@ -20,20 +20,20 @@ conf = w.workspace_conf.get_status(keys="enableWorkspaceFilesystem") Check configuration status. - + Gets the configuration status for a workspace. - + :param keys: str - + :returns: Dict[str,str] .. py:method:: set_status(contents: Dict[str, str]) Enable/disable features. - + Sets the configuration status for a workspace, including enabling or disabling it. - - - + + + \ No newline at end of file diff --git a/docs/workspace/sharing/providers.rst b/docs/workspace/sharing/providers.rst index 7d27acc3d..263545400 100644 --- a/docs/workspace/sharing/providers.rst +++ b/docs/workspace/sharing/providers.rst @@ -27,16 +27,16 @@ } """ - created = w.providers.create(name=f'sdk-{time.time_ns()}', recipient_profile_str=public_share_recipient) + created = w.providers.create(name=f"sdk-{time.time_ns()}", recipient_profile_str=public_share_recipient) # cleanup w.providers.delete(name=created.name) Create an auth provider. - + Creates a new authentication provider minimally based on a name and authentication type. The caller must be an admin on the metastore. - + :param name: str The name of the Provider. :param authentication_type: :class:`AuthenticationType` @@ -46,21 +46,21 @@ :param recipient_profile_str: str (optional) This field is required when the __authentication_type__ is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** or not provided. - + :returns: :class:`ProviderInfo` .. py:method:: delete(name: str) Delete a provider. - + Deletes an authentication provider, if the caller is a metastore admin or is the owner of the provider. - + :param name: str Name of the provider. - - + + .. py:method:: get(name: str) -> ProviderInfo @@ -83,7 +83,7 @@ } """ - created = w.providers.create(name=f'sdk-{time.time_ns()}', recipient_profile_str=public_share_recipient) + created = w.providers.create(name=f"sdk-{time.time_ns()}", recipient_profile_str=public_share_recipient) _ = w.providers.get(name=created.name) @@ -91,13 +91,13 @@ w.providers.delete(name=created.name) Get a provider. - + Gets a specific authentication provider. The caller must supply the name of the provider, and must either be a metastore admin or the owner of the provider. - + :param name: str Name of the provider. - + :returns: :class:`ProviderInfo` @@ -116,11 +116,11 @@ all = w.providers.list(sharing.ListProvidersRequest()) List providers. - + Gets an array of available authentication providers. The caller must either be a metastore admin or the owner of the providers. Providers not owned by the caller are not included in the response. There is no guarantee of a specific ordering of the elements in the array. - + :param data_provider_global_metastore_id: str (optional) If not provided, all providers will be returned. If no providers exist with this ID, no results will be returned. @@ -134,10 +134,33 @@ from the response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ProviderInfo` + .. py:method:: list_provider_share_assets(provider_name: str, share_name: str [, function_max_results: Optional[int], notebook_max_results: Optional[int], table_max_results: Optional[int], volume_max_results: Optional[int]]) -> ListProviderShareAssetsResponse + + List assets by provider share. + + Get arrays of assets associated with a specified provider's share. The caller is the recipient of the + share. + + :param provider_name: str + The name of the provider who owns the share. + :param share_name: str + The name of the share. + :param function_max_results: int (optional) + Maximum number of functions to return. + :param notebook_max_results: int (optional) + Maximum number of notebooks to return. + :param table_max_results: int (optional) + Maximum number of tables to return. + :param volume_max_results: int (optional) + Maximum number of volumes to return. + + :returns: :class:`ListProviderShareAssetsResponse` + + .. py:method:: list_shares(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ProviderShare] @@ -158,7 +181,7 @@ } """ - created = w.providers.create(name=f'sdk-{time.time_ns()}', recipient_profile_str=public_share_recipient) + created = w.providers.create(name=f"sdk-{time.time_ns()}", recipient_profile_str=public_share_recipient) shares = w.providers.list_shares(name=created.name) @@ -166,11 +189,11 @@ w.providers.delete(name=created.name) List shares by Provider. - + Gets an array of a specified provider's shares within the metastore where: - + * the caller is a metastore admin, or * the caller is the owner. - + :param name: str Name of the provider in which to list shares. :param max_results: int (optional) @@ -183,7 +206,7 @@ response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ProviderShare` @@ -207,7 +230,7 @@ } """ - created = w.providers.create(name=f'sdk-{time.time_ns()}', recipient_profile_str=public_share_recipient) + created = w.providers.create(name=f"sdk-{time.time_ns()}", recipient_profile_str=public_share_recipient) _ = w.providers.update(name=created.name, comment="Comment for update") @@ -215,11 +238,11 @@ w.providers.delete(name=created.name) Update a provider. - + Updates the information for an authentication provider, if the caller is a metastore admin or is the owner of the provider. If the update changes the provider name, the caller must be both a metastore admin and the owner of the provider. - + :param name: str Name of the provider. :param comment: str (optional) @@ -231,6 +254,6 @@ :param recipient_profile_str: str (optional) This field is required when the __authentication_type__ is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** or not provided. - + :returns: :class:`ProviderInfo` \ No newline at end of file diff --git a/docs/workspace/sharing/recipient_activation.rst b/docs/workspace/sharing/recipient_activation.rst index 2c214d9c0..bc8ac2715 100644 --- a/docs/workspace/sharing/recipient_activation.rst +++ b/docs/workspace/sharing/recipient_activation.rst @@ -8,30 +8,30 @@ the authentication type of `TOKEN`. The data recipient follows the activation link shared by the data provider to download the credential file that includes the access token. The recipient will then use the credential file to establish a secure connection with the provider to receive the shared data. - + Note that you can download the credential file only once. Recipients should treat the downloaded credential as a secret and must not share it outside of their organization. .. py:method:: get_activation_url_info(activation_url: str) Get a share activation URL. - + Gets an activation URL for a share. - + :param activation_url: str The one time activation url. It also accepts activation token. - - + + .. py:method:: retrieve_token(activation_url: str) -> RetrieveTokenResponse Get an access token. - + Retrieve access token with an activation url. This is a public API without any authentication. - + :param activation_url: str The one time activation url. It also accepts activation token. - + :returns: :class:`RetrieveTokenResponse` \ No newline at end of file diff --git a/docs/workspace/sharing/recipients.rst b/docs/workspace/sharing/recipients.rst index 76e1da171..e640bf038 100644 --- a/docs/workspace/sharing/recipients.rst +++ b/docs/workspace/sharing/recipients.rst @@ -7,12 +7,12 @@ A recipient is an object you create using :method:recipients/create to represent an organization which you want to allow access shares. The way how sharing works differs depending on whether or not your recipient has access to a Databricks workspace that is enabled for Unity Catalog: - + - For recipients with access to a Databricks workspace that is enabled for Unity Catalog, you can create a recipient object along with a unique sharing identifier you get from the recipient. The sharing identifier is the key identifier that enables the secure connection. This sharing mode is called **Databricks-to-Databricks sharing**. - + - For recipients without access to a Databricks workspace that is enabled for Unity Catalog, when you create a recipient object, Databricks generates an activation link you can send to the recipient. The recipient follows the activation link to download the credential file, and then uses the credential file @@ -31,16 +31,16 @@ w = WorkspaceClient() - created = w.recipients.create(name=f'sdk-{time.time_ns()}') + created = w.recipients.create(name=f"sdk-{time.time_ns()}") # cleanup w.recipients.delete(name=created.name) Create a share recipient. - + Creates a new recipient with the delta sharing authentication type in the metastore. The caller must be a metastore admin or have the **CREATE_RECIPIENT** privilege on the metastore. - + :param name: str Name of Recipient. :param authentication_type: :class:`AuthenticationType` @@ -64,20 +64,20 @@ :param sharing_code: str (optional) The one-time sharing code provided by the data recipient. This field is only present when the __authentication_type__ is **DATABRICKS**. - + :returns: :class:`RecipientInfo` .. py:method:: delete(name: str) Delete a share recipient. - + Deletes the specified recipient from the metastore. The caller must be the owner of the recipient. - + :param name: str Name of the recipient. - - + + .. py:method:: get(name: str) -> RecipientInfo @@ -93,7 +93,7 @@ w = WorkspaceClient() - created = w.recipients.create(name=f'sdk-{time.time_ns()}') + created = w.recipients.create(name=f"sdk-{time.time_ns()}") _ = w.recipients.get(name=created.name) @@ -101,14 +101,14 @@ w.recipients.delete(name=created.name) Get a share recipient. - + Gets a share recipient from the metastore if: - + * the caller is the owner of the share recipient, or: * is a metastore admin - + :param name: str Name of the recipient. - + :returns: :class:`RecipientInfo` @@ -127,12 +127,12 @@ all = w.recipients.list(sharing.ListRecipientsRequest()) List share recipients. - + Gets an array of all share recipients within the current metastore where: - + * the caller is a metastore admin, or * the caller is the owner. There is no guarantee of a specific ordering of the elements in the array. - + :param data_recipient_global_metastore_id: str (optional) If not provided, all recipients will be returned. If no recipients exist with this ID, no results will be returned. @@ -146,7 +146,7 @@ from the response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`RecipientInfo` @@ -163,7 +163,7 @@ w = WorkspaceClient() - created = w.recipients.create(name=f'sdk-{time.time_ns()}') + created = w.recipients.create(name=f"sdk-{time.time_ns()}") recipient_info = w.recipients.rotate_token(name=created.name, existing_token_expire_in_seconds=0) @@ -171,17 +171,17 @@ w.recipients.delete(name=created.name) Rotate a token. - + Refreshes the specified recipient's delta sharing authentication token with the provided token info. The caller must be the owner of the recipient. - + :param name: str The name of the Recipient. :param existing_token_expire_in_seconds: int The expiration time of the bearer token in ISO 8601 format. This will set the expiration_time of existing token only to a smaller timestamp, it cannot extend the expiration_time. Use 0 to expire the existing token immediately, negative number will return an error. - + :returns: :class:`RecipientInfo` @@ -198,7 +198,7 @@ w = WorkspaceClient() - created = w.recipients.create(name=f'sdk-{time.time_ns()}') + created = w.recipients.create(name=f"sdk-{time.time_ns()}") share_permissions = w.recipients.share_permissions(name=created.name) @@ -206,10 +206,10 @@ w.recipients.delete(name=created.name) Get recipient share permissions. - + Gets the share permissions for the specified Recipient. The caller must be a metastore admin or the owner of the Recipient. - + :param name: str The name of the Recipient. :param max_results: int (optional) @@ -222,7 +222,7 @@ unset from the response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: :class:`GetRecipientSharePermissionsResponse` @@ -239,19 +239,19 @@ w = WorkspaceClient() - created = w.recipients.create(name=f'sdk-{time.time_ns()}') + created = w.recipients.create(name=f"sdk-{time.time_ns()}") - w.recipients.update(name=created.name, comment=f'sdk-{time.time_ns()}') + w.recipients.update(name=created.name, comment=f"sdk-{time.time_ns()}") # cleanup w.recipients.delete(name=created.name) Update a share recipient. - + Updates an existing recipient in the metastore. The caller must be a metastore admin or the owner of the recipient. If the recipient name will be updated, the user must be both a metastore admin and the owner of the recipient. - + :param name: str Name of the recipient. :param comment: str (optional) @@ -268,6 +268,6 @@ Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write. - + :returns: :class:`RecipientInfo` \ No newline at end of file diff --git a/docs/workspace/sharing/shares.rst b/docs/workspace/sharing/shares.rst index 4d14b811d..1fafe755f 100644 --- a/docs/workspace/sharing/shares.rst +++ b/docs/workspace/sharing/shares.rst @@ -22,36 +22,36 @@ w = WorkspaceClient() - created_share = w.shares.create(name=f'sdk-{time.time_ns()}') + created_share = w.shares.create(name=f"sdk-{time.time_ns()}") # cleanup w.shares.delete(name=created_share.name) Create a share. - + Creates a new share for data objects. Data objects can be added after creation with **update**. The caller must be a metastore admin or have the **CREATE_SHARE** privilege on the metastore. - + :param name: str Name of the share. :param comment: str (optional) User-provided free-form text description. :param storage_root: str (optional) Storage root URL for the share. - + :returns: :class:`ShareInfo` .. py:method:: delete(name: str) Delete a share. - + Deletes a data object share from the metastore. The caller must be an owner of the share. - + :param name: str The name of the share. - - + + .. py:method:: get(name: str [, include_shared_data: Optional[bool]]) -> ShareInfo @@ -67,7 +67,7 @@ w = WorkspaceClient() - created_share = w.shares.create(name=f'sdk-{time.time_ns()}') + created_share = w.shares.create(name=f"sdk-{time.time_ns()}") _ = w.shares.get(name=created_share.name) @@ -75,15 +75,15 @@ w.shares.delete(name=created_share.name) Get a share. - + Gets a data object share from the metastore. The caller must be a metastore admin or the owner of the share. - + :param name: str The name of the share. :param include_shared_data: bool (optional) Query for data to include in the share. - + :returns: :class:`ShareInfo` @@ -102,10 +102,10 @@ all = w.shares.list(sharing.ListSharesRequest()) List shares. - + Gets an array of data object shares from the metastore. The caller must be a metastore admin or the owner of the share. There is no guarantee of a specific ordering of the elements in the array. - + :param max_results: int (optional) Maximum number of shares to return. - when set to 0, the page length is set to a server configured value (recommended); - when set to a value greater than 0, the page length is the minimum of this @@ -116,17 +116,17 @@ response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - + :returns: Iterator over :class:`ShareInfo` - .. py:method:: share_permissions(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> catalog.PermissionsList + .. py:method:: share_permissions(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> GetSharePermissionsResponse Get permissions. - + Gets the permissions for a data share from the metastore. The caller must be a metastore admin or the owner of the share. - + :param name: str The name of the share. :param max_results: int (optional) @@ -139,8 +139,8 @@ unset from the response. :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. - - :returns: :class:`PermissionsList` + + :returns: :class:`GetSharePermissionsResponse` .. py:method:: update(name: str [, comment: Optional[str], new_name: Optional[str], owner: Optional[str], storage_root: Optional[str], updates: Optional[List[SharedDataObjectUpdate]]]) -> ShareInfo @@ -158,29 +158,36 @@ w = WorkspaceClient() - table_name = f'sdk-{time.time_ns()}' + table_name = f"sdk-{time.time_ns()}" - created_catalog = w.catalogs.create(name=f'sdk-{time.time_ns()}') + created_catalog = w.catalogs.create(name=f"sdk-{time.time_ns()}") - created_schema = w.schemas.create(name=f'sdk-{time.time_ns()}', catalog_name=created_catalog.name) + created_schema = w.schemas.create(name=f"sdk-{time.time_ns()}", catalog_name=created_catalog.name) _ = w.statement_execution.execute( warehouse_id=os.environ["TEST_DEFAULT_WAREHOUSE_ID"], catalog=created_catalog.name, schema=created_schema.name, - statement="CREATE TABLE %s TBLPROPERTIES (delta.enableDeletionVectors=false) AS SELECT 2+2 as four" % - (table_name)).result() - - table_full_name = "%s.%s.%s" % (created_catalog.name, created_schema.name, table_name) - - created_share = w.shares.create(name=f'sdk-{time.time_ns()}') - - _ = w.shares.update(name=created_share.name, - updates=[ - sharing.SharedDataObjectUpdate(action=sharing.SharedDataObjectUpdateAction.ADD, - data_object=sharing.SharedDataObject( - name=table_full_name, data_object_type="TABLE")) - ]) + statement="CREATE TABLE %s TBLPROPERTIES (delta.enableDeletionVectors=false) AS SELECT 2+2 as four" % (table_name), + ).result() + + table_full_name = "%s.%s.%s" % ( + created_catalog.name, + created_schema.name, + table_name, + ) + + created_share = w.shares.create(name=f"sdk-{time.time_ns()}") + + _ = w.shares.update( + name=created_share.name, + updates=[ + sharing.SharedDataObjectUpdate( + action=sharing.SharedDataObjectUpdateAction.ADD, + data_object=sharing.SharedDataObject(name=table_full_name, data_object_type="TABLE"), + ) + ], + ) # cleanup w.schemas.delete(full_name=created_schema.full_name) @@ -189,23 +196,23 @@ w.shares.delete(name=created_share.name) Update a share. - + Updates the share with the changes and data objects in the request. The caller must be the owner of the share or a metastore admin. - + When the caller is a metastore admin, only the __owner__ field can be updated. - + In the case that the share name is changed, **updateShare** requires that the caller is both the share owner and a metastore admin. - + If there are notebook files in the share, the __storage_root__ field cannot be updated. - + For each table that is added through this method, the share owner must also have **SELECT** privilege on the table. This privilege must be maintained indefinitely for recipients to be able to access the table. Typically, you should use a group as the share owner. - + Table removals through **update** do not require additional privileges. - + :param name: str The name of the share. :param comment: str (optional) @@ -218,34 +225,24 @@ Storage root URL for the share. :param updates: List[:class:`SharedDataObjectUpdate`] (optional) Array of shared data object updates. - + :returns: :class:`ShareInfo` - .. py:method:: update_permissions(name: str [, changes: Optional[List[catalog.PermissionsChange]], max_results: Optional[int], page_token: Optional[str]]) + .. py:method:: update_permissions(name: str [, changes: Optional[List[PermissionsChange]]]) -> UpdateSharePermissionsResponse Update permissions. - + Updates the permissions for a data share in the metastore. The caller must be a metastore admin or an owner of the share. - - For new recipient grants, the user must also be the owner of the recipients. recipient revocations do - not require additional privileges. - + + For new recipient grants, the user must also be the recipient owner or metastore admin. recipient + revocations do not require additional privileges. + :param name: str The name of the share. :param changes: List[:class:`PermissionsChange`] (optional) Array of permission changes. - :param max_results: int (optional) - Maximum number of permissions to return. - when set to 0, the page length is set to a server - configured value (recommended); - when set to a value greater than 0, the page length is the minimum - of this value and a server configured value; - when set to a value less than 0, an invalid parameter - error is returned; - If not set, all valid permissions are returned (not recommended). - Note: The - number of returned permissions might be less than the specified max_results size, even zero. The - only definitive indication that no further permissions can be fetched is when the next_page_token is - unset from the response. - :param page_token: str (optional) - Opaque pagination token to go to next page based on previous query. - - + + :returns: :class:`UpdateSharePermissionsResponse` \ No newline at end of file diff --git a/docs/workspace/sql/alerts.rst b/docs/workspace/sql/alerts.rst index c8d9c31ab..30195a424 100644 --- a/docs/workspace/sql/alerts.rst +++ b/docs/workspace/sql/alerts.rst @@ -25,45 +25,51 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SELECT 1")) + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SELECT 1", + ) + ) alert = w.alerts.create( - alert=sql.CreateAlertRequestAlert(condition=sql.AlertCondition(operand=sql.AlertConditionOperand( - column=sql.AlertOperandColumn(name="1")), - op=sql.AlertOperator.EQUAL, - threshold=sql.AlertConditionThreshold( - value=sql.AlertOperandValue( - double_value=1))), - display_name=f'sdk-{time.time_ns()}', - query_id=query.id)) + alert=sql.CreateAlertRequestAlert( + condition=sql.AlertCondition( + operand=sql.AlertConditionOperand(column=sql.AlertOperandColumn(name="1")), + op=sql.AlertOperator.EQUAL, + threshold=sql.AlertConditionThreshold(value=sql.AlertOperandValue(double_value=1)), + ), + display_name=f"sdk-{time.time_ns()}", + query_id=query.id, + ) + ) # cleanup w.queries.delete(id=query.id) w.alerts.delete(id=alert.id) Create an alert. - + Creates an alert. - + :param alert: :class:`CreateAlertRequestAlert` (optional) - + :returns: :class:`Alert` .. py:method:: delete(id: str) Delete an alert. - + Moves an alert to the trash. Trashed alerts immediately disappear from searches and list views, and can no longer trigger. You can restore a trashed alert through the UI. A trashed alert is permanently deleted after 30 days. - + :param id: str - - + + .. py:method:: get(id: str) -> Alert @@ -82,20 +88,26 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SELECT 1")) + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SELECT 1", + ) + ) alert = w.alerts.create( - alert=sql.CreateAlertRequestAlert(condition=sql.AlertCondition(operand=sql.AlertConditionOperand( - column=sql.AlertOperandColumn(name="1")), - op=sql.AlertOperator.EQUAL, - threshold=sql.AlertConditionThreshold( - value=sql.AlertOperandValue( - double_value=1))), - display_name=f'sdk-{time.time_ns()}', - query_id=query.id)) + alert=sql.CreateAlertRequestAlert( + condition=sql.AlertCondition( + operand=sql.AlertConditionOperand(column=sql.AlertOperandColumn(name="1")), + op=sql.AlertOperator.EQUAL, + threshold=sql.AlertConditionThreshold(value=sql.AlertOperandValue(double_value=1)), + ), + display_name=f"sdk-{time.time_ns()}", + query_id=query.id, + ) + ) by_id = w.alerts.get(id=alert.id) @@ -104,11 +116,11 @@ w.alerts.delete(id=alert.id) Get an alert. - + Gets an alert. - + :param id: str - + :returns: :class:`Alert` @@ -127,13 +139,13 @@ all = w.alerts.list(sql.ListAlertsRequest()) List alerts. - + Gets a list of alerts accessible to the user, ordered by creation time. **Warning:** Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ListAlertsResponseAlert` @@ -153,33 +165,41 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SELECT 1")) + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SELECT 1", + ) + ) alert = w.alerts.create( - alert=sql.CreateAlertRequestAlert(condition=sql.AlertCondition(operand=sql.AlertConditionOperand( - column=sql.AlertOperandColumn(name="1")), - op=sql.AlertOperator.EQUAL, - threshold=sql.AlertConditionThreshold( - value=sql.AlertOperandValue( - double_value=1))), - display_name=f'sdk-{time.time_ns()}', - query_id=query.id)) - - _ = w.alerts.update(id=alert.id, - alert=sql.UpdateAlertRequestAlert(display_name=f'sdk-{time.time_ns()}'), - update_mask="display_name") + alert=sql.CreateAlertRequestAlert( + condition=sql.AlertCondition( + operand=sql.AlertConditionOperand(column=sql.AlertOperandColumn(name="1")), + op=sql.AlertOperator.EQUAL, + threshold=sql.AlertConditionThreshold(value=sql.AlertOperandValue(double_value=1)), + ), + display_name=f"sdk-{time.time_ns()}", + query_id=query.id, + ) + ) + + _ = w.alerts.update( + id=alert.id, + alert=sql.UpdateAlertRequestAlert(display_name=f"sdk-{time.time_ns()}"), + update_mask="display_name", + ) # cleanup w.queries.delete(id=query.id) w.alerts.delete(id=alert.id) Update an alert. - + Updates an alert. - + :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The @@ -187,11 +207,11 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. :param alert: :class:`UpdateAlertRequestAlert` (optional) - + :returns: :class:`Alert` \ No newline at end of file diff --git a/docs/workspace/sql/alerts_legacy.rst b/docs/workspace/sql/alerts_legacy.rst index 6dfd96128..5b048d2bf 100644 --- a/docs/workspace/sql/alerts_legacy.rst +++ b/docs/workspace/sql/alerts_legacy.rst @@ -8,24 +8,24 @@ periodically runs a query, evaluates a condition of its result, and notifies one or more users and/or notification destinations if the condition was met. Alerts can be scheduled using the `sql_task` type of the Jobs API, e.g. :method:jobs/create. - + **Note**: A new version of the Databricks SQL API is now available. Please see the latest version. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html .. py:method:: create(name: str, options: AlertOptions, query_id: str [, parent: Optional[str], rearm: Optional[int]]) -> LegacyAlert Create an alert. - + Creates an alert. An alert is a Databricks SQL object that periodically runs a query, evaluates a condition of its result, and notifies users or notification destinations if the condition was met. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:alerts/create instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param name: str Name of the alert. :param options: :class:`AlertOptions` @@ -37,68 +37,68 @@ :param rearm: int (optional) Number of seconds after being triggered before the alert rearms itself and can be triggered again. If `null`, alert will never be triggered again. - + :returns: :class:`LegacyAlert` .. py:method:: delete(alert_id: str) Delete an alert. - + Deletes an alert. Deleted alerts are no longer accessible and cannot be restored. **Note**: Unlike queries and dashboards, alerts cannot be moved to the trash. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:alerts/delete instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param alert_id: str - - + + .. py:method:: get(alert_id: str) -> LegacyAlert Get an alert. - + Gets an alert. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:alerts/get instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param alert_id: str - + :returns: :class:`LegacyAlert` .. py:method:: list() -> Iterator[LegacyAlert] Get alerts. - + Gets a list of alerts. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:alerts/list instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :returns: Iterator over :class:`LegacyAlert` .. py:method:: update(alert_id: str, name: str, options: AlertOptions, query_id: str [, rearm: Optional[int]]) Update an alert. - + Updates an alert. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:alerts/update instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param alert_id: str :param name: str Name of the alert. @@ -109,6 +109,6 @@ :param rearm: int (optional) Number of seconds after being triggered before the alert rearms itself and can be triggered again. If `null`, alert will never be triggered again. - - + + \ No newline at end of file diff --git a/docs/workspace/sql/dashboard_widgets.rst b/docs/workspace/sql/dashboard_widgets.rst index d4bbcde1d..63e100640 100644 --- a/docs/workspace/sql/dashboard_widgets.rst +++ b/docs/workspace/sql/dashboard_widgets.rst @@ -10,7 +10,7 @@ .. py:method:: create(dashboard_id: str, options: WidgetOptions, width: int [, text: Optional[str], visualization_id: Optional[str]]) -> Widget Add widget to a dashboard. - + :param dashboard_id: str Dashboard ID returned by :method:dashboards/create. :param options: :class:`WidgetOptions` @@ -21,24 +21,24 @@ contains a visualization in the `visualization` field. :param visualization_id: str (optional) Query Vizualization ID returned by :method:queryvisualizations/create. - + :returns: :class:`Widget` .. py:method:: delete(id: str) Remove widget. - + :param id: str Widget ID returned by :method:dashboardwidgets/create - - + + .. py:method:: update(id: str, dashboard_id: str, options: WidgetOptions, width: int [, text: Optional[str], visualization_id: Optional[str]]) -> Widget Update existing widget. - + :param id: str Widget ID returned by :method:dashboardwidgets/create :param dashboard_id: str @@ -51,6 +51,6 @@ contains a visualization in the `visualization` field. :param visualization_id: str (optional) Query Vizualization ID returned by :method:queryvisualizations/create. - + :returns: :class:`Widget` \ No newline at end of file diff --git a/docs/workspace/sql/dashboards.rst b/docs/workspace/sql/dashboards.rst index f22c7c96b..3ed0c4b77 100644 --- a/docs/workspace/sql/dashboards.rst +++ b/docs/workspace/sql/dashboards.rst @@ -23,13 +23,13 @@ w = WorkspaceClient() - created = w.dashboards.create(name=f'sdk-{time.time_ns()}') + created = w.dashboards.create(name=f"sdk-{time.time_ns()}") # cleanup w.dashboards.delete(dashboard_id=created.id) Create a dashboard object. - + :param name: str The title of this dashboard that appears in list views and at the top of the dashboard page. :param dashboard_filters_enabled: bool (optional) @@ -42,7 +42,7 @@ Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) :param tags: List[str] (optional) - + :returns: :class:`Dashboard` @@ -59,7 +59,7 @@ w = WorkspaceClient() - created = w.dashboards.create(name=f'sdk-{time.time_ns()}') + created = w.dashboards.create(name=f"sdk-{time.time_ns()}") w.dashboards.delete(dashboard_id=created.id) @@ -67,13 +67,13 @@ w.dashboards.delete(dashboard_id=created.id) Remove a dashboard. - + Moves a dashboard to the trash. Trashed dashboards do not appear in list views or searches, and cannot be shared. - + :param dashboard_id: str - - + + .. py:method:: get(dashboard_id: str) -> Dashboard @@ -89,7 +89,7 @@ w = WorkspaceClient() - created = w.dashboards.create(name=f'sdk-{time.time_ns()}') + created = w.dashboards.create(name=f"sdk-{time.time_ns()}") by_id = w.dashboards.get(dashboard_id=created.id) @@ -97,11 +97,11 @@ w.dashboards.delete(dashboard_id=created.id) Retrieve a definition. - + Returns a JSON representation of a dashboard object, including its visualization and query objects. - + :param dashboard_id: str - + :returns: :class:`Dashboard` @@ -120,12 +120,12 @@ all = w.dashboards.list(sql.ListDashboardsRequest()) Get dashboard objects. - + Fetch a paginated list of dashboard objects. - + **Warning**: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - + :param order: :class:`ListOrder` (optional) Name of dashboard attribute to order by. :param page: int (optional) @@ -134,7 +134,7 @@ Number of dashboards to return per page. :param q: str (optional) Full text search term. - + :returns: Iterator over :class:`Dashboard` @@ -151,7 +151,7 @@ w = WorkspaceClient() - created = w.dashboards.create(name=f'sdk-{time.time_ns()}') + created = w.dashboards.create(name=f"sdk-{time.time_ns()}") w.dashboards.restore(dashboard_id=created.id) @@ -159,23 +159,23 @@ w.dashboards.delete(dashboard_id=created.id) Restore a dashboard. - + A restored dashboard appears in list views and searches and can be shared. - + :param dashboard_id: str - - + + .. py:method:: update(dashboard_id: str [, name: Optional[str], run_as_role: Optional[RunAsRole], tags: Optional[List[str]]]) -> Dashboard Change a dashboard definition. - + Modify this dashboard definition. This operation only affects attributes of the dashboard object. It does not add, modify, or remove widgets. - + **Note**: You cannot undo this operation. - + :param dashboard_id: str :param name: str (optional) The title of this dashboard that appears in list views and at the top of the dashboard page. @@ -183,6 +183,6 @@ Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) :param tags: List[str] (optional) - + :returns: :class:`Dashboard` \ No newline at end of file diff --git a/docs/workspace/sql/data_sources.rst b/docs/workspace/sql/data_sources.rst index 8f7321fa0..472bdfb0e 100644 --- a/docs/workspace/sql/data_sources.rst +++ b/docs/workspace/sql/data_sources.rst @@ -7,13 +7,13 @@ This API is provided to assist you in making new query objects. When creating a query object, you may optionally specify a `data_source_id` for the SQL warehouse against which it will run. If you don't already know the `data_source_id` for your desired SQL warehouse, this API will help you find it. - + This API does not support searches. It returns the full list of SQL warehouses in your workspace. We advise you to use any text editor, REST client, or `grep` to search the response from this API for the name of your SQL warehouse as it appears in Databricks SQL. - + **Note**: A new version of the Databricks SQL API is now available. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html .. py:method:: list() -> Iterator[DataSource] @@ -30,15 +30,15 @@ srcs = w.data_sources.list() Get a list of SQL warehouses. - + Retrieves a full list of SQL warehouses available in this workspace. All fields that appear in this API response are enumerated for clarity. However, you need only a SQL warehouse's `id` to create new queries against it. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:warehouses/list instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :returns: Iterator over :class:`DataSource` \ No newline at end of file diff --git a/docs/workspace/sql/dbsql_permissions.rst b/docs/workspace/sql/dbsql_permissions.rst index 7f9e5d19c..a5bd010f1 100644 --- a/docs/workspace/sql/dbsql_permissions.rst +++ b/docs/workspace/sql/dbsql_permissions.rst @@ -7,76 +7,76 @@ The SQL Permissions API is similar to the endpoints of the :method:permissions/set. However, this exposes only one endpoint, which gets the Access Control List for a given object. You cannot modify any permissions using this API. - + There are three levels of permission: - + - `CAN_VIEW`: Allows read-only access - + - `CAN_RUN`: Allows read access and run access (superset of `CAN_VIEW`) - + - `CAN_MANAGE`: Allows all actions: read, run, edit, delete, modify permissions (superset of `CAN_RUN`) - + **Note**: A new version of the Databricks SQL API is now available. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html .. py:method:: get(object_type: ObjectTypePlural, object_id: str) -> GetResponse Get object ACL. - + Gets a JSON representation of the access control list (ACL) for a specified object. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:workspace/getpermissions instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param object_type: :class:`ObjectTypePlural` The type of object permissions to check. :param object_id: str Object ID. An ACL is returned for the object with this UUID. - + :returns: :class:`GetResponse` .. py:method:: set(object_type: ObjectTypePlural, object_id: str [, access_control_list: Optional[List[AccessControl]]]) -> SetResponse Set object ACL. - + Sets the access control list (ACL) for a specified object. This operation will complete rewrite the ACL. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:workspace/setpermissions instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param object_type: :class:`ObjectTypePlural` The type of object permission to set. :param object_id: str Object ID. The ACL for the object with this UUID is overwritten by this request's POST content. :param access_control_list: List[:class:`AccessControl`] (optional) - + :returns: :class:`SetResponse` .. py:method:: transfer_ownership(object_type: OwnableObjectType, object_id: TransferOwnershipObjectId [, new_owner: Optional[str]]) -> Success Transfer object ownership. - + Transfers ownership of a dashboard, query, or alert to an active user. Requires an admin API key. - + **Note**: A new version of the Databricks SQL API is now available. For queries and alerts, please use :method:queries/update and :method:alerts/update respectively instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param object_type: :class:`OwnableObjectType` The type of object on which to change ownership. :param object_id: :class:`TransferOwnershipObjectId` The ID of the object on which to change ownership. :param new_owner: str (optional) Email address for the new owner, who must exist in the workspace. - + :returns: :class:`Success` \ No newline at end of file diff --git a/docs/workspace/sql/queries.rst b/docs/workspace/sql/queries.rst index 959552850..4cc9b5b52 100644 --- a/docs/workspace/sql/queries.rst +++ b/docs/workspace/sql/queries.rst @@ -24,34 +24,38 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SHOW TABLES")) + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SHOW TABLES", + ) + ) # cleanup w.queries.delete(id=query.id) Create a query. - + Creates a query. - + :param query: :class:`CreateQueryRequestQuery` (optional) - + :returns: :class:`Query` .. py:method:: delete(id: str) Delete a query. - + Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and cannot be used for alerts. You can restore a trashed query through the UI. A trashed query is permanently deleted after 30 days. - + :param id: str - - + + .. py:method:: get(id: str) -> Query @@ -70,10 +74,14 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SHOW TABLES")) + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SHOW TABLES", + ) + ) by_id = w.queries.get(id=query.id) @@ -81,37 +89,37 @@ w.queries.delete(id=query.id) Get a query. - + Gets a query. - + :param id: str - + :returns: :class:`Query` .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ListQueryObjectsResponseQuery] List queries. - + Gets a list of queries accessible to the user, ordered by creation time. **Warning:** Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - + :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`ListQueryObjectsResponseQuery` .. py:method:: list_visualizations(id: str [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[Visualization] List visualizations on a query. - + Gets a list of visualizations on a query. - + :param id: str :param page_size: int (optional) :param page_token: str (optional) - + :returns: Iterator over :class:`Visualization` @@ -131,24 +139,32 @@ srcs = w.data_sources.list() - query = w.queries.create(query=sql.CreateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - warehouse_id=srcs[0].warehouse_id, - description="test query from Go SDK", - query_text="SHOW TABLES")) - - updated = w.queries.update(id=query.id, - query=sql.UpdateQueryRequestQuery(display_name=f'sdk-{time.time_ns()}', - description="UPDATED: test query from Go SDK", - query_text="SELECT 2+2"), - update_mask="display_name,description,query_text") + query = w.queries.create( + query=sql.CreateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + warehouse_id=srcs[0].warehouse_id, + description="test query from Go SDK", + query_text="SHOW TABLES", + ) + ) + + updated = w.queries.update( + id=query.id, + query=sql.UpdateQueryRequestQuery( + display_name=f"sdk-{time.time_ns()}", + description="UPDATED: test query from Go SDK", + query_text="SELECT 2+2", + ), + update_mask="display_name,description,query_text", + ) # cleanup w.queries.delete(id=query.id) Update a query. - + Updates a query. - + :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The @@ -156,11 +172,11 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. :param query: :class:`UpdateQueryRequestQuery` (optional) - + :returns: :class:`Query` \ No newline at end of file diff --git a/docs/workspace/sql/queries_legacy.rst b/docs/workspace/sql/queries_legacy.rst index a7ab56836..c35ed9b69 100644 --- a/docs/workspace/sql/queries_legacy.rst +++ b/docs/workspace/sql/queries_legacy.rst @@ -7,34 +7,34 @@ These endpoints are used for CRUD operations on query definitions. Query definitions include the target SQL warehouse, query text, name, description, tags, parameters, and visualizations. Queries can be scheduled using the `sql_task` type of the Jobs API, e.g. :method:jobs/create. - + **Note**: A new version of the Databricks SQL API is now available. Please see the latest version. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html .. py:method:: create( [, data_source_id: Optional[str], description: Optional[str], name: Optional[str], options: Optional[Any], parent: Optional[str], query: Optional[str], run_as_role: Optional[RunAsRole], tags: Optional[List[str]]]) -> LegacyQuery Create a new query definition. - + Creates a new query definition. Queries created with this endpoint belong to the authenticated user making the request. - + The `data_source_id` field specifies the ID of the SQL warehouse to run this query against. You can use the Data Sources API to see a complete list of available SQL warehouses. Or you can copy the `data_source_id` from an existing query. - + **Note**: You cannot add a visualization until you create the query. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queries/create instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param data_source_id: str (optional) Data source ID maps to the ID of the data source used by the resource and is distinct from the warehouse ID. [Learn more] - + [Learn more]: https://docs.databricks.com/api/workspace/datasources/list :param description: str (optional) General description that conveys additional information about this query such as usage notes. @@ -52,71 +52,71 @@ Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) :param tags: List[str] (optional) - + :returns: :class:`LegacyQuery` .. py:method:: delete(query_id: str) Delete a query. - + Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and they cannot be used for alerts. The trash is deleted after 30 days. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queries/delete instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param query_id: str - - + + .. py:method:: get(query_id: str) -> LegacyQuery Get a query definition. - + Retrieve a query object definition along with contextual permissions information about the currently authenticated user. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queries/get instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param query_id: str - + :returns: :class:`LegacyQuery` .. py:method:: list( [, order: Optional[str], page: Optional[int], page_size: Optional[int], q: Optional[str]]) -> Iterator[LegacyQuery] Get a list of queries. - + Gets a list of queries. Optionally, this list can be filtered by a search term. - + **Warning**: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queries/list instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param order: str (optional) Name of query attribute to order by. Default sort order is ascending. Append a dash (`-`) to order descending instead. - + - `name`: The name of the query. - + - `created_at`: The timestamp the query was created. - + - `runtime`: The time it took to run this query. This is blank for parameterized queries. A blank value is treated as the highest value for sorting. - + - `executed_at`: The timestamp when the query was last run. - + - `created_by`: The user name of the user that created the query. :param page: int (optional) Page number to retrieve. @@ -124,45 +124,45 @@ Number of queries to return per page. :param q: str (optional) Full text search term - + :returns: Iterator over :class:`LegacyQuery` .. py:method:: restore(query_id: str) Restore a query. - + Restore a query that has been moved to the trash. A restored query appears in list views and searches. You can use restored queries for alerts. - + **Note**: A new version of the Databricks SQL API is now available. Please see the latest version. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param query_id: str - - + + .. py:method:: update(query_id: str [, data_source_id: Optional[str], description: Optional[str], name: Optional[str], options: Optional[Any], query: Optional[str], run_as_role: Optional[RunAsRole], tags: Optional[List[str]]]) -> LegacyQuery Change a query definition. - + Modify this query definition. - + **Note**: You cannot undo this operation. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queries/update instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param query_id: str :param data_source_id: str (optional) Data source ID maps to the ID of the data source used by the resource and is distinct from the warehouse ID. [Learn more] - + [Learn more]: https://docs.databricks.com/api/workspace/datasources/list :param description: str (optional) General description that conveys additional information about this query such as usage notes. @@ -178,6 +178,6 @@ Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) :param tags: List[str] (optional) - + :returns: :class:`LegacyQuery` \ No newline at end of file diff --git a/docs/workspace/sql/query_history.rst b/docs/workspace/sql/query_history.rst index 2f5520cdf..5acfb5127 100644 --- a/docs/workspace/sql/query_history.rst +++ b/docs/workspace/sql/query_history.rst @@ -19,17 +19,20 @@ w = WorkspaceClient() - _ = w.query_history.list(filter_by=sql.QueryFilter( - query_start_time_range=sql.TimeRange(start_time_ms=1690243200000, end_time_ms=1690329600000))) + _ = w.query_history.list( + filter_by=sql.QueryFilter( + query_start_time_range=sql.TimeRange(start_time_ms=1690243200000, end_time_ms=1690329600000) + ) + ) List Queries. - + List the history of queries through SQL warehouses, and serverless compute. - + You can filter by user ID, warehouse ID, status, and time range. Most recently started queries are returned first (up to max_results in request). The pagination token returned in response can be used to list subsequent query statuses. - + :param filter_by: :class:`QueryFilter` (optional) A filter to limit query history results. This field is optional. :param include_metrics: bool (optional) @@ -41,6 +44,6 @@ A token that can be used to get the next page of results. The token can contains characters that need to be encoded before using it in a URL. For example, the character '+' needs to be replaced by %2B. This field is optional. - + :returns: :class:`ListQueriesResponse` \ No newline at end of file diff --git a/docs/workspace/sql/query_visualizations.rst b/docs/workspace/sql/query_visualizations.rst index ac3d6c565..f0865ae0a 100644 --- a/docs/workspace/sql/query_visualizations.rst +++ b/docs/workspace/sql/query_visualizations.rst @@ -10,31 +10,31 @@ .. py:method:: create( [, visualization: Optional[CreateVisualizationRequestVisualization]]) -> Visualization Add a visualization to a query. - + Adds a visualization to a query. - + :param visualization: :class:`CreateVisualizationRequestVisualization` (optional) - + :returns: :class:`Visualization` .. py:method:: delete(id: str) Remove a visualization. - + Removes a visualization. - + :param id: str - - + + .. py:method:: update(id: str, update_mask: str [, visualization: Optional[UpdateVisualizationRequestVisualization]]) -> Visualization Update a visualization. - + Updates a visualization. - + :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The @@ -42,11 +42,11 @@ `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - + A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API changes in the future. :param visualization: :class:`UpdateVisualizationRequestVisualization` (optional) - + :returns: :class:`Visualization` \ No newline at end of file diff --git a/docs/workspace/sql/query_visualizations_legacy.rst b/docs/workspace/sql/query_visualizations_legacy.rst index f56f78a5f..d91b97c8c 100644 --- a/docs/workspace/sql/query_visualizations_legacy.rst +++ b/docs/workspace/sql/query_visualizations_legacy.rst @@ -6,23 +6,23 @@ This is an evolving API that facilitates the addition and removal of vizualisations from existing queries within the Databricks Workspace. Data structures may change over time. - + **Note**: A new version of the Databricks SQL API is now available. Please see the latest version. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html .. py:method:: create(query_id: str, type: str, options: Any [, description: Optional[str], name: Optional[str]]) -> LegacyVisualization Add visualization to a query. - + Creates visualization in the query. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queryvisualizations/create instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param query_id: str The identifier returned by :method:queries/create :param type: str @@ -34,38 +34,38 @@ A short description of this visualization. This is not displayed in the UI. :param name: str (optional) The name of the visualization that appears on dashboards and the query screen. - + :returns: :class:`LegacyVisualization` .. py:method:: delete(id: str) Remove visualization. - + Removes a visualization from the query. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queryvisualizations/delete instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param id: str Widget ID returned by :method:queryvizualisations/create - - + + .. py:method:: update(id: str [, created_at: Optional[str], description: Optional[str], name: Optional[str], options: Optional[Any], query: Optional[LegacyQuery], type: Optional[str], updated_at: Optional[str]]) -> LegacyVisualization Edit existing visualization. - + Updates visualization in the query. - + **Note**: A new version of the Databricks SQL API is now available. Please use :method:queryvisualizations/update instead. [Learn more] - + [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html - + :param id: str The UUID for this visualization. :param created_at: str (optional) @@ -80,6 +80,6 @@ :param type: str (optional) The type of visualization: chart, table, pivot table, and so on. :param updated_at: str (optional) - + :returns: :class:`LegacyVisualization` \ No newline at end of file diff --git a/docs/workspace/sql/redash_config.rst b/docs/workspace/sql/redash_config.rst index 9b4382dd5..cee23c1bd 100644 --- a/docs/workspace/sql/redash_config.rst +++ b/docs/workspace/sql/redash_config.rst @@ -9,6 +9,6 @@ .. py:method:: get_config() -> ClientConfig Read workspace configuration for Redash-v2. - + :returns: :class:`ClientConfig` \ No newline at end of file diff --git a/docs/workspace/sql/statement_execution.rst b/docs/workspace/sql/statement_execution.rst index 44f64b512..5dabcc0d2 100644 --- a/docs/workspace/sql/statement_execution.rst +++ b/docs/workspace/sql/statement_execution.rst @@ -6,13 +6,13 @@ The Databricks SQL Statement Execution API can be used to execute SQL statements on a SQL warehouse and fetch the result. - + **Getting started** - + We suggest beginning with the [Databricks SQL Statement Execution API tutorial]. - + **Overview of statement execution and result fetching** - + Statement execution begins by issuing a :method:statementexecution/executeStatement request with a valid SQL statement and warehouse ID, along with optional parameters such as the data catalog and output format. If no other parameters are specified, the server will wait for up to 10s before returning a response. If @@ -20,7 +20,7 @@ array and metadata. Otherwise, if no result is available after the 10s timeout expired, the response will provide the statement ID that can be used to poll for results by using a :method:statementexecution/getStatement request. - + You can specify whether the call should behave synchronously, asynchronously or start synchronously with a fallback to asynchronous execution. This is controlled with the `wait_timeout` and `on_wait_timeout` settings. If `wait_timeout` is set between 5-50 seconds (default: 10s), the call waits for results up to @@ -28,7 +28,7 @@ statement ID. The `on_wait_timeout` setting specifies what should happen when the timeout is reached while the statement execution has not yet finished. This can be set to either `CONTINUE`, to fallback to asynchronous mode, or it can be set to `CANCEL`, which cancels the statement. - + In summary: - Synchronous mode - `wait_timeout=30s` and `on_wait_timeout=CANCEL` - The call waits up to 30 seconds; if the statement execution finishes within this time, the result data is returned directly in the response. If the execution takes longer than 30 seconds, the execution is canceled and the call returns @@ -40,38 +40,38 @@ seconds; if the statement execution finishes within this time, the result data is returned directly in the response. If the execution takes longer than 10 seconds, a statement ID is returned. The statement ID can be used to fetch status and results in the same way as in the asynchronous mode. - + Depending on the size, the result can be split into multiple chunks. If the statement execution is successful, the statement response contains a manifest and the first chunk of the result. The manifest contains schema information and provides metadata for each chunk in the result. Result chunks can be retrieved by index with :method:statementexecution/getStatementResultChunkN which may be called in any order and in parallel. For sequential fetching, each chunk, apart from the last, also contains a `next_chunk_index` and `next_chunk_internal_link` that point to the next chunk. - + A statement can be canceled with :method:statementexecution/cancelExecution. - + **Fetching result data: format and disposition** - + To specify the format of the result data, use the `format` field, which can be set to one of the following options: `JSON_ARRAY` (JSON), `ARROW_STREAM` ([Apache Arrow Columnar]), or `CSV`. - + There are two ways to receive statement results, controlled by the `disposition` setting, which can be either `INLINE` or `EXTERNAL_LINKS`: - + - `INLINE`: In this mode, the result data is directly included in the response. It's best suited for smaller results. This mode can only be used with the `JSON_ARRAY` format. - + - `EXTERNAL_LINKS`: In this mode, the response provides links that can be used to download the result data in chunks separately. This approach is ideal for larger results and offers higher throughput. This mode can be used with all the formats: `JSON_ARRAY`, `ARROW_STREAM`, and `CSV`. - + By default, the API uses `format=JSON_ARRAY` and `disposition=INLINE`. - + **Limits and limitations** - + Note: The byte limit for INLINE disposition is based on internal storage metrics and will not exactly match the byte count of the actual payload. - + - Statements with `disposition=INLINE` are limited to 25 MiB and will fail when this limit is exceeded. - Statements with `disposition=EXTERNAL_LINKS` are limited to 100 GiB. Result sets larger than this limit will be truncated. Truncation is indicated by the `truncated` field in the result manifest. - The maximum @@ -84,33 +84,34 @@ once every 15 minutes. - The results are only available for one hour after success; polling does not extend this. - The SQL Execution API must be used for the entire lifecycle of the statement. For example, you cannot use the Jobs API to execute the command, and then the SQL Execution API to cancel it. - + [Apache Arrow Columnar]: https://arrow.apache.org/overview/ [Databricks SQL Statement Execution API tutorial]: https://docs.databricks.com/sql/api/sql-execution-tutorial.html + .. py:method:: cancel_execution(statement_id: str) Cancel statement execution. - + Requests that an executing statement be canceled. Callers must poll for status to see the terminal state. - + :param statement_id: str The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls. - - + + .. py:method:: execute_statement(statement: str, warehouse_id: str [, byte_limit: Optional[int], catalog: Optional[str], disposition: Optional[Disposition], format: Optional[Format], on_wait_timeout: Optional[ExecuteStatementRequestOnWaitTimeout], parameters: Optional[List[StatementParameterListItem]], row_limit: Optional[int], schema: Optional[str], wait_timeout: Optional[str]]) -> StatementResponse Execute a SQL statement. - + :param statement: str The SQL statement to execute. The statement can optionally be parameterized, see `parameters`. :param warehouse_id: str Warehouse upon which to execute a statement. See also [What are SQL warehouses?] - + [What are SQL warehouses?]: https://docs.databricks.com/sql/admin/warehouse-type.html :param byte_limit: int (optional) Applies the given byte limit to the statement's result size. Byte counts are based on internal data @@ -120,37 +121,37 @@ explcitly set. :param catalog: str (optional) Sets default catalog for statement execution, similar to [`USE CATALOG`] in SQL. - + [`USE CATALOG`]: https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-catalog.html :param disposition: :class:`Disposition` (optional) :param format: :class:`Format` (optional) Statement execution supports three result formats: `JSON_ARRAY` (default), `ARROW_STREAM`, and `CSV`. - + Important: The formats `ARROW_STREAM` and `CSV` are supported only with `EXTERNAL_LINKS` disposition. `JSON_ARRAY` is supported in `INLINE` and `EXTERNAL_LINKS` disposition. - + When specifying `format=JSON_ARRAY`, result data will be formatted as an array of arrays of values, where each value is either the *string representation* of a value, or `null`. For example, the output of `SELECT concat('id-', id) AS strCol, id AS intCol, null AS nullCol FROM range(3)` would look like this: - + ``` [ [ "id-1", "1", null ], [ "id-2", "2", null ], [ "id-3", "3", null ], ] ``` - + When specifying `format=JSON_ARRAY` and `disposition=EXTERNAL_LINKS`, each chunk in the result contains compact JSON with no indentation or extra whitespace. - + When specifying `format=ARROW_STREAM` and `disposition=EXTERNAL_LINKS`, each chunk in the result will be formatted as Apache Arrow Stream. See the [Apache Arrow streaming format]. - + When specifying `format=CSV` and `disposition=EXTERNAL_LINKS`, each chunk in the result will be a CSV according to [RFC 4180] standard. All the columns values will have *string representation* similar to the `JSON_ARRAY` format, and `null` values will be encoded as “null”. Only the first chunk in the result would contain a header row with column names. For example, the output of `SELECT concat('id-', id) AS strCol, id AS intCol, null as nullCol FROM range(3)` would look like this: - + ``` strCol,intCol,nullCol id-1,1,null id-2,2,null id-3,3,null ``` - + [Apache Arrow streaming format]: https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format [RFC 4180]: https://www.rfc-editor.org/rfc/rfc4180 :param on_wait_timeout: :class:`ExecuteStatementRequestOnWaitTimeout` (optional) @@ -165,27 +166,27 @@ of a name, a value, and optionally a type. To represent a NULL value, the `value` field may be omitted or set to `null` explicitly. If the `type` field is omitted, the value is interpreted as a string. - + If the type is given, parameters will be checked for type correctness according to the given type. A value is correct if the provided string can be converted to the requested type using the `cast` function. The exact semantics are described in the section [`cast` function] of the SQL language reference. - + For example, the following statement contains two parameters, `my_name` and `my_date`: - + SELECT * FROM my_table WHERE name = :my_name AND date = :my_date - + The parameters can be passed in the request body as follows: - + { ..., "statement": "SELECT * FROM my_table WHERE name = :my_name AND date = :my_date", "parameters": [ { "name": "my_name", "value": "the name" }, { "name": "my_date", "value": "2020-01-01", "type": "DATE" } ] } - + Currently, positional parameters denoted by a `?` marker are not supported by the Databricks SQL Statement Execution API. - + Also see the section [Parameter markers] of the SQL language reference. - + [Parameter markers]: https://docs.databricks.com/sql/language-manual/sql-ref-parameter-marker.html [`cast` function]: https://docs.databricks.com/sql/language-manual/functions/cast.html :param row_limit: int (optional) @@ -194,59 +195,59 @@ the limit or not. :param schema: str (optional) Sets default schema for statement execution, similar to [`USE SCHEMA`] in SQL. - + [`USE SCHEMA`]: https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-schema.html :param wait_timeout: str (optional) The time in seconds the call will wait for the statement's result set as `Ns`, where `N` can be set to 0 or to a value between 5 and 50. - + When set to `0s`, the statement will execute in asynchronous mode and the call will not wait for the execution to finish. In this case, the call returns directly with `PENDING` state and a statement ID which can be used for polling with :method:statementexecution/getStatement. - + When set between 5 and 50 seconds, the call will behave synchronously up to this timeout and wait for the statement execution to finish. If the execution finishes within this time, the call returns immediately with a manifest and result data (or a `FAILED` state in case of an execution error). If the statement takes longer to execute, `on_wait_timeout` determines what should happen after the timeout is reached. - + :returns: :class:`StatementResponse` .. py:method:: get_statement(statement_id: str) -> StatementResponse Get status, manifest, and result first chunk. - + This request can be used to poll for the statement's status. When the `status.state` field is `SUCCEEDED` it will also return the result manifest and the first chunk of the result data. When the statement is in the terminal states `CANCELED`, `CLOSED` or `FAILED`, it returns HTTP 200 with the state set. After at least 12 hours in terminal state, the statement is removed from the warehouse and further calls will receive an HTTP 404 response. - + **NOTE** This call currently might take up to 5 seconds to get the latest status and result. - + :param statement_id: str The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls. - + :returns: :class:`StatementResponse` .. py:method:: get_statement_result_chunk_n(statement_id: str, chunk_index: int) -> ResultData Get result chunk by index. - + After the statement execution has `SUCCEEDED`, this request can be used to fetch any chunk by index. Whereas the first chunk with `chunk_index=0` is typically fetched with :method:statementexecution/executeStatement or :method:statementexecution/getStatement, this request can be used to fetch subsequent chunks. The response structure is identical to the nested `result` element described in the :method:statementexecution/getStatement request, and similarly includes the `next_chunk_index` and `next_chunk_internal_link` fields for simple iteration through the result set. - + :param statement_id: str The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls. :param chunk_index: int - + :returns: :class:`ResultData` \ No newline at end of file diff --git a/docs/workspace/sql/warehouses.rst b/docs/workspace/sql/warehouses.rst index fd55d5b0c..7695dbc8b 100644 --- a/docs/workspace/sql/warehouses.rst +++ b/docs/workspace/sql/warehouses.rst @@ -22,28 +22,29 @@ w = WorkspaceClient() created = w.warehouses.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", cluster_size="2X-Small", max_num_clusters=1, auto_stop_mins=10, tags=sql.EndpointTags( - custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com") - ])).result() + custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com")] + ), + ).result() # cleanup w.warehouses.delete(id=created.id) Create a warehouse. - + Creates a new SQL warehouse. - + :param auto_stop_mins: int (optional) The amount of time in minutes that a SQL warehouse must be idle (i.e., no RUNNING queries) before it is automatically stopped. - + Supported values: - Must be >= 0 mins for serverless warehouses - Must be == 0 or >= 10 mins for non-serverless warehouses - 0 indicates no autostop. - + Defaults to 120 mins :param channel: :class:`Channel` (optional) Channel Details @@ -51,14 +52,14 @@ Size of the clusters allocated for this warehouse. Increasing the size of a spark cluster allows you to run larger queries on it. If you want to increase the number of concurrent queries, please tune max_num_clusters. - + Supported values: - 2X-Small - X-Small - Small - Medium - Large - X-Large - 2X-Large - 3X-Large - 4X-Large :param creator_name: str (optional) warehouse creator name :param enable_photon: bool (optional) Configures whether the warehouse should use Photon optimized clusters. - + Defaults to false. :param enable_serverless_compute: bool (optional) Configures whether the warehouse should use serverless compute @@ -66,33 +67,33 @@ Deprecated. Instance profile used to pass IAM role to the cluster :param max_num_clusters: int (optional) Maximum number of clusters that the autoscaler will create to handle concurrent queries. - + Supported values: - Must be >= min_num_clusters - Must be <= 30. - + Defaults to min_clusters if unset. :param min_num_clusters: int (optional) Minimum number of available clusters that will be maintained for this SQL warehouse. Increasing this will ensure that a larger number of clusters are always running and therefore may reduce the cold start time for new queries. This is similar to reserved vs. revocable cores in a resource manager. - + Supported values: - Must be > 0 - Must be <= min(max_num_clusters, 30) - + Defaults to 1 :param name: str (optional) Logical name for the cluster. - + Supported values: - Must be unique within an org. - Must be less than 100 characters. :param spot_instance_policy: :class:`SpotInstancePolicy` (optional) Configurations whether the warehouse should use spot instances. :param tags: :class:`EndpointTags` (optional) A set of key-value pairs that will be tagged on all resources (e.g., AWS instances and EBS volumes) associated with this SQL warehouse. - + Supported values: - Number of tags < 45. :param warehouse_type: :class:`CreateWarehouseRequestWarehouseType` (optional) Warehouse type: `PRO` or `CLASSIC`. If you want to use serverless compute, you must set to `PRO` and also set the field `enable_serverless_compute` to `true`. - + :returns: Long-running operation waiter for :class:`GetWarehouseResponse`. See :method:wait_get_warehouse_running for more details. @@ -104,13 +105,13 @@ .. py:method:: delete(id: str) Delete a warehouse. - + Deletes a SQL warehouse. - + :param id: str Required. Id of the SQL warehouse. - - + + .. py:method:: edit(id: str [, auto_stop_mins: Optional[int], channel: Optional[Channel], cluster_size: Optional[str], creator_name: Optional[str], enable_photon: Optional[bool], enable_serverless_compute: Optional[bool], instance_profile_arn: Optional[str], max_num_clusters: Optional[int], min_num_clusters: Optional[int], name: Optional[str], spot_instance_policy: Optional[SpotInstancePolicy], tags: Optional[EndpointTags], warehouse_type: Optional[EditWarehouseRequestWarehouseType]]) -> Wait[GetWarehouseResponse] @@ -128,35 +129,38 @@ w = WorkspaceClient() created = w.warehouses.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", cluster_size="2X-Small", max_num_clusters=1, auto_stop_mins=10, tags=sql.EndpointTags( - custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com") - ])).result() + custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com")] + ), + ).result() - _ = w.warehouses.edit(id=created.id, - name=f'sdk-{time.time_ns()}', - cluster_size="2X-Small", - max_num_clusters=1, - auto_stop_mins=10) + _ = w.warehouses.edit( + id=created.id, + name=f"sdk-{time.time_ns()}", + cluster_size="2X-Small", + max_num_clusters=1, + auto_stop_mins=10, + ) # cleanup w.warehouses.delete(id=created.id) Update a warehouse. - + Updates the configuration for a SQL warehouse. - + :param id: str Required. Id of the warehouse to configure. :param auto_stop_mins: int (optional) The amount of time in minutes that a SQL warehouse must be idle (i.e., no RUNNING queries) before it is automatically stopped. - + Supported values: - Must be == 0 or >= 10 mins - 0 indicates no autostop. - + Defaults to 120 mins :param channel: :class:`Channel` (optional) Channel Details @@ -164,14 +168,14 @@ Size of the clusters allocated for this warehouse. Increasing the size of a spark cluster allows you to run larger queries on it. If you want to increase the number of concurrent queries, please tune max_num_clusters. - + Supported values: - 2X-Small - X-Small - Small - Medium - Large - X-Large - 2X-Large - 3X-Large - 4X-Large :param creator_name: str (optional) warehouse creator name :param enable_photon: bool (optional) Configures whether the warehouse should use Photon optimized clusters. - + Defaults to false. :param enable_serverless_compute: bool (optional) Configures whether the warehouse should use serverless compute. @@ -179,33 +183,33 @@ Deprecated. Instance profile used to pass IAM role to the cluster :param max_num_clusters: int (optional) Maximum number of clusters that the autoscaler will create to handle concurrent queries. - + Supported values: - Must be >= min_num_clusters - Must be <= 30. - + Defaults to min_clusters if unset. :param min_num_clusters: int (optional) Minimum number of available clusters that will be maintained for this SQL warehouse. Increasing this will ensure that a larger number of clusters are always running and therefore may reduce the cold start time for new queries. This is similar to reserved vs. revocable cores in a resource manager. - + Supported values: - Must be > 0 - Must be <= min(max_num_clusters, 30) - + Defaults to 1 :param name: str (optional) Logical name for the cluster. - + Supported values: - Must be unique within an org. - Must be less than 100 characters. :param spot_instance_policy: :class:`SpotInstancePolicy` (optional) Configurations whether the warehouse should use spot instances. :param tags: :class:`EndpointTags` (optional) A set of key-value pairs that will be tagged on all resources (e.g., AWS instances and EBS volumes) associated with this SQL warehouse. - + Supported values: - Number of tags < 45. :param warehouse_type: :class:`EditWarehouseRequestWarehouseType` (optional) Warehouse type: `PRO` or `CLASSIC`. If you want to use serverless compute, you must set to `PRO` and also set the field `enable_serverless_compute` to `true`. - + :returns: Long-running operation waiter for :class:`GetWarehouseResponse`. See :method:wait_get_warehouse_running for more details. @@ -229,13 +233,14 @@ w = WorkspaceClient() created = w.warehouses.create( - name=f'sdk-{time.time_ns()}', + name=f"sdk-{time.time_ns()}", cluster_size="2X-Small", max_num_clusters=1, auto_stop_mins=10, tags=sql.EndpointTags( - custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com") - ])).result() + custom_tags=[sql.EndpointTagPair(key="Owner", value="eng-dev-ecosystem-team_at_databricks.com")] + ), + ).result() wh = w.warehouses.get(id=created.id) @@ -243,46 +248,46 @@ w.warehouses.delete(id=created.id) Get warehouse info. - + Gets the information for a single SQL warehouse. - + :param id: str Required. Id of the SQL warehouse. - + :returns: :class:`GetWarehouseResponse` .. py:method:: get_permission_levels(warehouse_id: str) -> GetWarehousePermissionLevelsResponse Get SQL warehouse permission levels. - + Gets the permission levels that a user can have on an object. - + :param warehouse_id: str The SQL warehouse for which to get or manage permissions. - + :returns: :class:`GetWarehousePermissionLevelsResponse` .. py:method:: get_permissions(warehouse_id: str) -> WarehousePermissions Get SQL warehouse permissions. - + Gets the permissions of a SQL warehouse. SQL warehouses can inherit permissions from their root object. - + :param warehouse_id: str The SQL warehouse for which to get or manage permissions. - + :returns: :class:`WarehousePermissions` .. py:method:: get_workspace_warehouse_config() -> GetWorkspaceWarehouseConfigResponse Get the workspace configuration. - + Gets the workspace level configuration that is shared by all SQL warehouses in a workspace. - + :returns: :class:`GetWorkspaceWarehouseConfigResponse` @@ -301,36 +306,36 @@ all = w.warehouses.list(sql.ListWarehousesRequest()) List warehouses. - + Lists all SQL warehouses that a user has manager permissions on. - + :param run_as_user_id: int (optional) Service Principal which will be used to fetch the list of warehouses. If not specified, the user from the session header is used. - + :returns: Iterator over :class:`EndpointInfo` .. py:method:: set_permissions(warehouse_id: str [, access_control_list: Optional[List[WarehouseAccessControlRequest]]]) -> WarehousePermissions Set SQL warehouse permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param warehouse_id: str The SQL warehouse for which to get or manage permissions. :param access_control_list: List[:class:`WarehouseAccessControlRequest`] (optional) - + :returns: :class:`WarehousePermissions` .. py:method:: set_workspace_warehouse_config( [, channel: Optional[Channel], config_param: Optional[RepeatedEndpointConfPairs], data_access_config: Optional[List[EndpointConfPair]], enabled_warehouse_types: Optional[List[WarehouseTypePair]], global_param: Optional[RepeatedEndpointConfPairs], google_service_account: Optional[str], instance_profile_arn: Optional[str], security_policy: Optional[SetWorkspaceWarehouseConfigRequestSecurityPolicy], sql_configuration_parameters: Optional[RepeatedEndpointConfPairs]]) Set the workspace configuration. - + Sets the workspace level configuration that is shared by all SQL warehouses in a workspace. - + :param channel: :class:`Channel` (optional) Optional: Channel selection details :param config_param: :class:`RepeatedEndpointConfPairs` (optional) @@ -353,19 +358,19 @@ Security policy for warehouses :param sql_configuration_parameters: :class:`RepeatedEndpointConfPairs` (optional) SQL configuration parameters - - + + .. py:method:: start(id: str) -> Wait[GetWarehouseResponse] Start a warehouse. - + Starts a SQL warehouse. - + :param id: str Required. Id of the SQL warehouse. - + :returns: Long-running operation waiter for :class:`GetWarehouseResponse`. See :method:wait_get_warehouse_running for more details. @@ -377,12 +382,12 @@ .. py:method:: stop(id: str) -> Wait[GetWarehouseResponse] Stop a warehouse. - + Stops a SQL warehouse. - + :param id: str Required. Id of the SQL warehouse. - + :returns: Long-running operation waiter for :class:`GetWarehouseResponse`. See :method:wait_get_warehouse_stopped for more details. @@ -394,14 +399,14 @@ .. py:method:: update_permissions(warehouse_id: str [, access_control_list: Optional[List[WarehouseAccessControlRequest]]]) -> WarehousePermissions Update SQL warehouse permissions. - + Updates the permissions on a SQL warehouse. SQL warehouses can inherit permissions from their root object. - + :param warehouse_id: str The SQL warehouse for which to get or manage permissions. :param access_control_list: List[:class:`WarehouseAccessControlRequest`] (optional) - + :returns: :class:`WarehousePermissions` diff --git a/docs/workspace/vectorsearch/vector_search_endpoints.rst b/docs/workspace/vectorsearch/vector_search_endpoints.rst index 1abd09b95..ea81ef3c4 100644 --- a/docs/workspace/vectorsearch/vector_search_endpoints.rst +++ b/docs/workspace/vectorsearch/vector_search_endpoints.rst @@ -9,14 +9,14 @@ .. py:method:: create_endpoint(name: str, endpoint_type: EndpointType) -> Wait[EndpointInfo] Create an endpoint. - + Create a new endpoint. - + :param name: str Name of endpoint :param endpoint_type: :class:`EndpointType` Type of endpoint. - + :returns: Long-running operation waiter for :class:`EndpointInfo`. See :method:wait_get_endpoint_vector_search_endpoint_online for more details. @@ -28,30 +28,30 @@ .. py:method:: delete_endpoint(endpoint_name: str) Delete an endpoint. - + :param endpoint_name: str Name of the endpoint - - + + .. py:method:: get_endpoint(endpoint_name: str) -> EndpointInfo Get an endpoint. - + :param endpoint_name: str Name of the endpoint - + :returns: :class:`EndpointInfo` .. py:method:: list_endpoints( [, page_token: Optional[str]]) -> Iterator[EndpointInfo] List all endpoints. - + :param page_token: str (optional) Token for pagination - + :returns: Iterator over :class:`EndpointInfo` diff --git a/docs/workspace/vectorsearch/vector_search_indexes.rst b/docs/workspace/vectorsearch/vector_search_indexes.rst index 415e19d90..7828d0ef2 100644 --- a/docs/workspace/vectorsearch/vector_search_indexes.rst +++ b/docs/workspace/vectorsearch/vector_search_indexes.rst @@ -6,7 +6,7 @@ **Index**: An efficient representation of your embedding vectors that supports real-time and efficient approximate nearest neighbor (ANN) search queries. - + There are 2 types of Vector Search indexes: * **Delta Sync Index**: An index that automatically syncs with a source Delta Table, automatically and incrementally updating the index as the underlying data in the Delta Table changes. * **Direct Vector Access Index**: An index that supports direct read and write of @@ -15,9 +15,9 @@ .. py:method:: create_index(name: str, endpoint_name: str, primary_key: str, index_type: VectorIndexType [, delta_sync_index_spec: Optional[DeltaSyncVectorIndexSpecRequest], direct_access_index_spec: Optional[DirectAccessVectorIndexSpec]]) -> CreateVectorIndexResponse Create an index. - + Create a new index. - + :param name: str Name of the index :param endpoint_name: str @@ -26,7 +26,7 @@ Primary key of the index :param index_type: :class:`VectorIndexType` There are 2 types of Vector Search indexes: - + - `DELTA_SYNC`: An index that automatically syncs with a source Delta Table, automatically and incrementally updating the index as the underlying data in the Delta Table changes. - `DIRECT_ACCESS`: An index that supports direct read and write of vectors and metadata through our @@ -35,75 +35,77 @@ Specification for Delta Sync Index. Required if `index_type` is `DELTA_SYNC`. :param direct_access_index_spec: :class:`DirectAccessVectorIndexSpec` (optional) Specification for Direct Vector Access Index. Required if `index_type` is `DIRECT_ACCESS`. - + :returns: :class:`CreateVectorIndexResponse` .. py:method:: delete_data_vector_index(index_name: str, primary_keys: List[str]) -> DeleteDataVectorIndexResponse Delete data from index. - + Handles the deletion of data from a specified vector index. - + :param index_name: str Name of the vector index where data is to be deleted. Must be a Direct Vector Access Index. :param primary_keys: List[str] List of primary keys for the data to be deleted. - + :returns: :class:`DeleteDataVectorIndexResponse` .. py:method:: delete_index(index_name: str) Delete an index. - + Delete an index. - + :param index_name: str Name of the index - - + + .. py:method:: get_index(index_name: str) -> VectorIndex Get an index. - + Get an index. - + :param index_name: str Name of the index - + :returns: :class:`VectorIndex` .. py:method:: list_indexes(endpoint_name: str [, page_token: Optional[str]]) -> Iterator[MiniVectorIndex] List indexes. - + List all indexes in the given endpoint. - + :param endpoint_name: str Name of the endpoint :param page_token: str (optional) Token for pagination - + :returns: Iterator over :class:`MiniVectorIndex` - .. py:method:: query_index(index_name: str, columns: List[str] [, filters_json: Optional[str], num_results: Optional[int], query_text: Optional[str], query_type: Optional[str], query_vector: Optional[List[float]], score_threshold: Optional[float]]) -> QueryVectorIndexResponse + .. py:method:: query_index(index_name: str, columns: List[str] [, columns_to_rerank: Optional[List[str]], filters_json: Optional[str], num_results: Optional[int], query_text: Optional[str], query_type: Optional[str], query_vector: Optional[List[float]], score_threshold: Optional[float]]) -> QueryVectorIndexResponse Query an index. - + Query the specified vector index. - + :param index_name: str Name of the vector index to query. :param columns: List[str] List of column names to include in the response. + :param columns_to_rerank: List[str] (optional) + Column names used to retrieve data to send to the reranker. :param filters_json: str (optional) JSON string representing query filters. - + Example filters: - `{"id <": 5}`: Filter for id less than 5. - `{"id >": 5}`: Filter for id greater than 5. - `{"id <=": 5}`: Filter for id less than equal to 5. - `{"id >=": 5}`: Filter for id greater than equal to 5. - `{"id": 5}`: Filter for id equal to 5. @@ -118,66 +120,66 @@ vectors. :param score_threshold: float (optional) Threshold for the approximate nearest neighbor search. Defaults to 0.0. - + :returns: :class:`QueryVectorIndexResponse` .. py:method:: query_next_page(index_name: str [, endpoint_name: Optional[str], page_token: Optional[str]]) -> QueryVectorIndexResponse Query next page. - + Use `next_page_token` returned from previous `QueryVectorIndex` or `QueryVectorIndexNextPage` request to fetch next page of results. - + :param index_name: str Name of the vector index to query. :param endpoint_name: str (optional) Name of the endpoint. :param page_token: str (optional) Page token returned from previous `QueryVectorIndex` or `QueryVectorIndexNextPage` API. - + :returns: :class:`QueryVectorIndexResponse` .. py:method:: scan_index(index_name: str [, last_primary_key: Optional[str], num_results: Optional[int]]) -> ScanVectorIndexResponse Scan an index. - + Scan the specified vector index and return the first `num_results` entries after the exclusive `primary_key`. - + :param index_name: str Name of the vector index to scan. :param last_primary_key: str (optional) Primary key of the last entry returned in the previous scan. :param num_results: int (optional) Number of results to return. Defaults to 10. - + :returns: :class:`ScanVectorIndexResponse` .. py:method:: sync_index(index_name: str) Synchronize an index. - + Triggers a synchronization process for a specified vector index. - + :param index_name: str Name of the vector index to synchronize. Must be a Delta Sync Index. - - + + .. py:method:: upsert_data_vector_index(index_name: str, inputs_json: str) -> UpsertDataVectorIndexResponse Upsert data into an index. - + Handles the upserting of data into a specified vector index. - + :param index_name: str Name of the vector index where data is to be upserted. Must be a Direct Vector Access Index. :param inputs_json: str JSON string representing the data to be upserted. - + :returns: :class:`UpsertDataVectorIndexResponse` \ No newline at end of file diff --git a/docs/workspace/workspace/git_credentials.rst b/docs/workspace/workspace/git_credentials.rst index 34851e84a..d5efd62eb 100644 --- a/docs/workspace/workspace/git_credentials.rst +++ b/docs/workspace/workspace/git_credentials.rst @@ -5,9 +5,9 @@ .. py:class:: GitCredentialsAPI Registers personal access token for Databricks to do operations on behalf of the user. - + See [more info]. - + [more info]: https://docs.databricks.com/repos/get-access-tokens-from-git-provider.html .. py:method:: create(git_provider: str [, git_username: Optional[str], personal_access_token: Optional[str]]) -> CreateCredentialsResponse @@ -27,11 +27,11 @@ w.git_credentials.delete(credential_id=cr.credential_id) Create a credential entry. - + Creates a Git credential entry for the user. Only one Git credential per user is supported, so any attempts to create credentials if an entry already exists will fail. Use the PATCH endpoint to update existing credentials, or the DELETE endpoint to delete existing credentials. - + :param git_provider: str Git provider. This field is case-insensitive. The available Git providers are `gitHub`, `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer`, @@ -45,22 +45,22 @@ :param personal_access_token: str (optional) The personal access token used to authenticate to the corresponding Git provider. For certain providers, support may exist for other types of scoped access tokens. [Learn more]. - + [Learn more]: https://docs.databricks.com/repos/get-access-tokens-from-git-provider.html - + :returns: :class:`CreateCredentialsResponse` .. py:method:: delete(credential_id: int) Delete a credential. - + Deletes the specified Git credential. - + :param credential_id: int The ID for the corresponding credential to access. - - + + .. py:method:: get(credential_id: int) -> GetCredentialsResponse @@ -82,12 +82,12 @@ w.git_credentials.delete(credential_id=cr.credential_id) Get a credential entry. - + Gets the Git credential with the specified credential ID. - + :param credential_id: int The ID for the corresponding credential to access. - + :returns: :class:`GetCredentialsResponse` @@ -105,9 +105,9 @@ list = w.git_credentials.list() Get Git credentials. - + Lists the calling user's Git credentials. One credential per user is supported. - + :returns: Iterator over :class:`CredentialInfo` @@ -126,18 +126,20 @@ cr = w.git_credentials.create(git_provider="gitHub", git_username="test", personal_access_token="test") - w.git_credentials.update(credential_id=cr.credential_id, - git_provider="gitHub", - git_username=f'sdk-{time.time_ns()}@example.com', - personal_access_token=f'sdk-{time.time_ns()}') + w.git_credentials.update( + credential_id=cr.credential_id, + git_provider="gitHub", + git_username=f"sdk-{time.time_ns()}@example.com", + personal_access_token=f"sdk-{time.time_ns()}", + ) # cleanup w.git_credentials.delete(credential_id=cr.credential_id) Update a credential. - + Updates the specified Git credential. - + :param credential_id: int The ID for the corresponding credential to access. :param git_provider: str @@ -153,8 +155,8 @@ :param personal_access_token: str (optional) The personal access token used to authenticate to the corresponding Git provider. For certain providers, support may exist for other types of scoped access tokens. [Learn more]. - + [Learn more]: https://docs.databricks.com/repos/get-access-tokens-from-git-provider.html - - + + \ No newline at end of file diff --git a/docs/workspace/workspace/repos.rst b/docs/workspace/workspace/repos.rst index 5f3e3e290..7388ffe6b 100644 --- a/docs/workspace/workspace/repos.rst +++ b/docs/workspace/workspace/repos.rst @@ -6,11 +6,11 @@ The Repos API allows users to manage their git repos. Users can use the API to access all repos that they have manage permissions on. - + Databricks Repos is a visual Git client in Databricks. It supports common Git operations such a cloning a repository, committing and pushing, pulling, branch management, and visual comparison of diffs when committing. - + Within Repos you can develop code in notebooks or other files and follow data science and engineering code development best practices using Git for version control, collaboration, and CI/CD. @@ -27,18 +27,22 @@ w = WorkspaceClient() - root = f'sdk-{time.time_ns()}' + root = f"sdk-{time.time_ns()}" - ri = w.repos.create(path=root, url="https://github.com/shreyas-goenka/empty-repo.git", provider="github") + ri = w.repos.create( + path=root, + url="https://github.com/shreyas-goenka/empty-repo.git", + provider="github", + ) # cleanup w.repos.delete(repo_id=ri.id) Create a repo. - + Creates a repo in the workspace and links it to the remote Git repo specified. Note that repos created programmatically must be linked to a remote Git repo, unlike repos created in the browser. - + :param url: str URL of the Git repository to be linked. :param provider: str @@ -51,20 +55,20 @@ :param sparse_checkout: :class:`SparseCheckout` (optional) If specified, the repo will be created with sparse checkout enabled. You cannot enable/disable sparse checkout after the repo is created. - + :returns: :class:`CreateRepoResponse` .. py:method:: delete(repo_id: int) Delete a repo. - + Deletes the specified repo. - + :param repo_id: int The ID for the corresponding repo to delete. - - + + .. py:method:: get(repo_id: int) -> GetRepoResponse @@ -80,9 +84,13 @@ w = WorkspaceClient() - root = f'sdk-{time.time_ns()}' + root = f"sdk-{time.time_ns()}" - ri = w.repos.create(path=root, url="https://github.com/shreyas-goenka/empty-repo.git", provider="github") + ri = w.repos.create( + path=root, + url="https://github.com/shreyas-goenka/empty-repo.git", + provider="github", + ) by_id = w.repos.get(repo_id=ri.id) @@ -90,36 +98,36 @@ w.repos.delete(repo_id=ri.id) Get a repo. - + Returns the repo with the given repo ID. - + :param repo_id: int ID of the Git folder (repo) object in the workspace. - + :returns: :class:`GetRepoResponse` .. py:method:: get_permission_levels(repo_id: str) -> GetRepoPermissionLevelsResponse Get repo permission levels. - + Gets the permission levels that a user can have on an object. - + :param repo_id: str The repo for which to get or manage permissions. - + :returns: :class:`GetRepoPermissionLevelsResponse` .. py:method:: get_permissions(repo_id: str) -> RepoPermissions Get repo permissions. - + Gets the permissions of a repo. Repos can inherit permissions from their root object. - + :param repo_id: str The repo for which to get or manage permissions. - + :returns: :class:`RepoPermissions` @@ -138,10 +146,10 @@ all = w.repos.list(workspace.ListReposRequest()) Get repos. - + Returns repos that the calling user has Manage permissions on. Use `next_page_token` to iterate through additional pages. - + :param next_page_token: str (optional) Token used to get the next page of results. If not specified, returns the first page of results as well as a next page token if there are more results. @@ -149,21 +157,21 @@ Filters repos that have paths starting with the given path prefix. If not provided or when provided an effectively empty prefix (`/` or `/Workspace`) Git folders (repos) from `/Workspace/Repos` will be served. - + :returns: Iterator over :class:`RepoInfo` .. py:method:: set_permissions(repo_id: str [, access_control_list: Optional[List[RepoAccessControlRequest]]]) -> RepoPermissions Set repo permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object. - + :param repo_id: str The repo for which to get or manage permissions. :param access_control_list: List[:class:`RepoAccessControlRequest`] (optional) - + :returns: :class:`RepoPermissions` @@ -180,9 +188,13 @@ w = WorkspaceClient() - root = f'sdk-{time.time_ns()}' + root = f"sdk-{time.time_ns()}" - ri = w.repos.create(path=root, url="https://github.com/shreyas-goenka/empty-repo.git", provider="github") + ri = w.repos.create( + path=root, + url="https://github.com/shreyas-goenka/empty-repo.git", + provider="github", + ) w.repos.update(repo_id=ri.id, branch="foo") @@ -190,10 +202,10 @@ w.repos.delete(repo_id=ri.id) Update a repo. - + Updates the repo to a different branch or tag, or updates the repo to the latest commit on the same branch. - + :param repo_id: int ID of the Git folder (repo) object in the workspace. :param branch: str (optional) @@ -205,19 +217,19 @@ Tag that the local version of the repo is checked out to. Updating the repo to a tag puts the repo in a detached HEAD state. Before committing new changes, you must update the repo to a branch instead of the detached HEAD. - - + + .. py:method:: update_permissions(repo_id: str [, access_control_list: Optional[List[RepoAccessControlRequest]]]) -> RepoPermissions Update repo permissions. - + Updates the permissions on a repo. Repos can inherit permissions from their root object. - + :param repo_id: str The repo for which to get or manage permissions. :param access_control_list: List[:class:`RepoAccessControlRequest`] (optional) - + :returns: :class:`RepoPermissions` \ No newline at end of file diff --git a/docs/workspace/workspace/secrets.rst b/docs/workspace/workspace/secrets.rst index 96d94e1de..2dc261114 100644 --- a/docs/workspace/workspace/secrets.rst +++ b/docs/workspace/workspace/secrets.rst @@ -5,11 +5,11 @@ .. py:class:: SecretsAPI The Secrets API allows you to manage secrets, secret scopes, and access permissions. - + Sometimes accessing data requires that you authenticate to external data sources through JDBC. Instead of directly entering your credentials into a notebook, use Databricks secrets to store your credentials and reference them in notebooks and jobs. - + Administrators, secret creators, and users granted permission can read Databricks secrets. While Databricks makes an effort to redact secret values that might be displayed in notebooks, it is not possible to prevent such users from reading secrets. @@ -27,9 +27,9 @@ w = WorkspaceClient() - key_name = f'sdk-{time.time_ns()}' + key_name = f"sdk-{time.time_ns()}" - scope_name = f'sdk-{time.time_ns()}' + scope_name = f"sdk-{time.time_ns()}" w.secrets.create_scope(scope=scope_name) @@ -38,10 +38,10 @@ w.secrets.delete_scope(scope=scope_name) Create a new secret scope. - + The scope name must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters. - + :param scope: str Scope name requested by the user. Scope names are unique. :param backend_azure_keyvault: :class:`AzureKeyVaultSecretScopeMetadata` (optional) @@ -50,98 +50,98 @@ The principal that is initially granted `MANAGE` permission to the created scope. :param scope_backend_type: :class:`ScopeBackendType` (optional) The backend type the scope will be created with. If not specified, will default to `DATABRICKS` - - + + .. py:method:: delete_acl(scope: str, principal: str) Delete an ACL. - + Deletes the given ACL on the given scope. - + Users must have the `MANAGE` permission to invoke this API. Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope, principal, or ACL exists. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to remove permissions from. :param principal: str The principal to remove an existing ACL from. - - + + .. py:method:: delete_scope(scope: str) Delete a secret scope. - + Deletes a secret scope. - + Throws `RESOURCE_DOES_NOT_EXIST` if the scope does not exist. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str Name of the scope to delete. - - + + .. py:method:: delete_secret(scope: str, key: str) Delete a secret. - + Deletes the secret stored in this secret scope. You must have `WRITE` or `MANAGE` permission on the secret scope. - + Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope or secret exists. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope that contains the secret to delete. :param key: str Name of the secret to delete. - - + + .. py:method:: get_acl(scope: str, principal: str) -> AclItem Get secret ACL details. - + Gets the details about the given ACL, such as the group and permission. Users must have the `MANAGE` permission to invoke this API. - + Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope exists. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to fetch ACL information from. :param principal: str The principal to fetch ACL information for. - + :returns: :class:`AclItem` .. py:method:: get_secret(scope: str, key: str) -> GetSecretResponse Get a secret. - + Gets the bytes representation of a secret value for the specified scope and key. - + Users need the READ permission to make this call. - + Note that the secret value returned is in bytes. The interpretation of the bytes is determined by the caller in DBUtils and the type the data is decoded into. - + Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret or secret scope exists. - + :param scope: str The name of the scope to fetch secret information from. :param key: str The key to fetch secret for. - + :returns: :class:`GetSecretResponse` @@ -158,9 +158,9 @@ w = WorkspaceClient() - key_name = f'sdk-{time.time_ns()}' + key_name = f"sdk-{time.time_ns()}" - scope_name = f'sdk-{time.time_ns()}' + scope_name = f"sdk-{time.time_ns()}" w.secrets.create_scope(scope=scope_name) @@ -171,15 +171,15 @@ w.secrets.delete_scope(scope=scope_name) Lists ACLs. - + List the ACLs for a given secret scope. Users must have the `MANAGE` permission to invoke this API. - + Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope exists. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to fetch ACL information from. - + :returns: Iterator over :class:`AclItem` @@ -197,11 +197,11 @@ scopes = w.secrets.list_scopes() List all scopes. - + Lists all secret scopes available in the workspace. - + Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :returns: Iterator over :class:`SecretScope` @@ -218,9 +218,9 @@ w = WorkspaceClient() - key_name = f'sdk-{time.time_ns()}' + key_name = f"sdk-{time.time_ns()}" - scope_name = f'sdk-{time.time_ns()}' + scope_name = f"sdk-{time.time_ns()}" w.secrets.create_scope(scope=scope_name) @@ -231,17 +231,17 @@ w.secrets.delete_scope(scope=scope_name) List secret keys. - + Lists the secret keys that are stored at this scope. This is a metadata-only operation; secret data cannot be retrieved using this API. Users need the READ permission to make this call. - + The lastUpdatedTimestamp returned is in milliseconds since epoch. Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope exists. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to list secrets within. - + :returns: Iterator over :class:`SecretMetadata` @@ -259,15 +259,19 @@ w = WorkspaceClient() - key_name = f'sdk-{time.time_ns()}' + key_name = f"sdk-{time.time_ns()}" - group = w.groups.create(display_name=f'sdk-{time.time_ns()}') + group = w.groups.create(display_name=f"sdk-{time.time_ns()}") - scope_name = f'sdk-{time.time_ns()}' + scope_name = f"sdk-{time.time_ns()}" w.secrets.create_scope(scope=scope_name) - w.secrets.put_acl(scope=scope_name, permission=workspace.AclPermission.MANAGE, principal=group.display_name) + w.secrets.put_acl( + scope=scope_name, + permission=workspace.AclPermission.MANAGE, + principal=group.display_name, + ) # cleanup w.groups.delete(id=group.id) @@ -275,40 +279,40 @@ w.secrets.delete_scope(scope=scope_name) Create/update an ACL. - + Creates or overwrites the Access Control List (ACL) associated with the given principal (user or group) on the specified scope point. - + In general, a user or group will use the most powerful permission available to them, and permissions are ordered as follows: - + * `MANAGE` - Allowed to change ACLs, and read and write to this secret scope. * `WRITE` - Allowed to read and write to this secret scope. * `READ` - Allowed to read this secret scope and list what secrets are available. - + Note that in general, secret values can only be read from within a command on a cluster (for example, through a notebook). There is no API to read the actual secret value material outside of a cluster. However, the user's permission will be applied based on who is executing the command, and they must have at least READ permission. - + Users must have the `MANAGE` permission to invoke this API. - + The principal is a user or group name corresponding to an existing Databricks principal to be granted or revoked access. - + Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope exists. Throws `RESOURCE_ALREADY_EXISTS` if a permission for the principal already exists. Throws `INVALID_PARAMETER_VALUE` if the permission or principal is invalid. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to apply permissions to. :param principal: str The principal in which the permission is applied. :param permission: :class:`AclPermission` The permission level applied to the principal. - - + + .. py:method:: put_secret(scope: str, key: str [, bytes_value: Optional[str], string_value: Optional[str]]) @@ -324,36 +328,36 @@ w = WorkspaceClient() - key_name = f'sdk-{time.time_ns()}' + key_name = f"sdk-{time.time_ns()}" - scope_name = f'sdk-{time.time_ns()}' + scope_name = f"sdk-{time.time_ns()}" w.secrets.create_scope(scope=scope_name) - w.secrets.put_secret(scope=scope_name, key=key_name, string_value=f'sdk-{time.time_ns()}') + w.secrets.put_secret(scope=scope_name, key=key_name, string_value=f"sdk-{time.time_ns()}") # cleanup w.secrets.delete_secret(scope=scope_name, key=key_name) w.secrets.delete_scope(scope=scope_name) Add a secret. - + Inserts a secret under the provided scope with the given name. If a secret already exists with the same name, this command overwrites the existing secret's value. The server encrypts the secret using the secret scope's encryption settings before storing it. - + You must have `WRITE` or `MANAGE` permission on the secret scope. The secret key must consist of alphanumeric characters, dashes, underscores, and periods, and cannot exceed 128 characters. The maximum allowed secret value size is 128 KB. The maximum number of secrets in a given scope is 1000. - + The input fields "string_value" or "bytes_value" specify the type of the secret, which will determine the value returned when the secret value is requested. Exactly one must be specified. - + Throws `RESOURCE_DOES_NOT_EXIST` if no such secret scope exists. Throws `RESOURCE_LIMIT_EXCEEDED` if maximum number of secrets in scope is exceeded. Throws `INVALID_PARAMETER_VALUE` if the key name or value length is invalid. Throws `PERMISSION_DENIED` if the user does not have permission to make this API call. - + :param scope: str The name of the scope to which the secret will be associated with. :param key: str @@ -362,6 +366,6 @@ If specified, value will be stored as bytes. :param string_value: str (optional) If specified, note that the value will be stored in UTF-8 (MB4) form. - - + + \ No newline at end of file diff --git a/docs/workspace/workspace/workspace.rst b/docs/workspace/workspace/workspace.rst index 595872deb..3eae91432 100644 --- a/docs/workspace/workspace/workspace.rst +++ b/docs/workspace/workspace/workspace.rst @@ -5,29 +5,29 @@ .. py:class:: WorkspaceExt The Workspace API allows you to list, import, export, and delete notebooks and folders. - + A notebook is a web-based interface to a document that contains runnable code, visualizations, and explanatory text. .. py:method:: delete(path: str [, recursive: Optional[bool]]) Delete a workspace object. - + Deletes an object or a directory (and optionally recursively deletes all objects in the directory). * If `path` does not exist, this call returns an error `RESOURCE_DOES_NOT_EXIST`. * If `path` is a non-empty directory and `recursive` is set to `false`, this call returns an error `DIRECTORY_NOT_EMPTY`. - + Object deletion cannot be undone and deleting a directory recursively is not atomic. - + :param path: str The absolute path of the notebook or directory. :param recursive: bool (optional) The flag that specifies whether to delete the object recursively. It is `false` by default. Please note this deleting directory is not atomic. If it fails in the middle, some of objects under this directory may be deleted and cannot be undone. - - + + .. py:method:: download(path: str [, format: ExportFormat]) -> BinaryIO @@ -45,12 +45,12 @@ w = WorkspaceClient() - py_file = f'/Users/{w.current_user.me().user_name}/file-{time.time_ns()}.py' + py_file = f"/Users/{w.current_user.me().user_name}/file-{time.time_ns()}.py" - w.workspace.upload(py_file, io.BytesIO(b'print(1)'), format=ImportFormat.AUTO) + w.workspace.upload(py_file, io.BytesIO(b"print(1)"), format=ImportFormat.AUTO) with w.workspace.download(py_file) as f: content = f.read() - assert content == b'print(1)' + assert content == b"print(1)" w.workspace.delete(py_file) @@ -79,63 +79,63 @@ w = WorkspaceClient() - notebook = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" export_response = w.workspace.export(format=workspace.ExportFormat.SOURCE, path=notebook) Export a workspace object. - + Exports an object or the contents of an entire directory. - + If `path` does not exist, this call returns an error `RESOURCE_DOES_NOT_EXIST`. - + If the exported data would exceed size limit, this call returns `MAX_NOTEBOOK_SIZE_EXCEEDED`. Currently, this API does not support exporting a library. - + :param path: str The absolute path of the object or directory. Exporting a directory is only supported for the `DBC`, `SOURCE`, and `AUTO` format. :param format: :class:`ExportFormat` (optional) This specifies the format of the exported file. By default, this is `SOURCE`. - + The value is case sensitive. - + - `SOURCE`: The notebook is exported as source code. Directory exports will not include non-notebook entries. - `HTML`: The notebook is exported as an HTML file. - `JUPYTER`: The notebook is exported as a Jupyter/IPython Notebook file. - `DBC`: The notebook is exported in Databricks archive format. Directory exports will not include non-notebook entries. - `R_MARKDOWN`: The notebook is exported to R Markdown format. - `AUTO`: The object or directory is exported depending on the objects type. Directory exports will include notebooks and workspace files. - + :returns: :class:`ExportResponse` .. py:method:: get_permission_levels(workspace_object_type: str, workspace_object_id: str) -> GetWorkspaceObjectPermissionLevelsResponse Get workspace object permission levels. - + Gets the permission levels that a user can have on an object. - + :param workspace_object_type: str The workspace object type for which to get or manage permissions. :param workspace_object_id: str The workspace object for which to get or manage permissions. - + :returns: :class:`GetWorkspaceObjectPermissionLevelsResponse` .. py:method:: get_permissions(workspace_object_type: str, workspace_object_id: str) -> WorkspaceObjectPermissions Get workspace object permissions. - + Gets the permissions of a workspace object. Workspace objects can inherit permissions from their parent objects or root object. - + :param workspace_object_type: str The workspace object type for which to get or manage permissions. :param workspace_object_id: str The workspace object for which to get or manage permissions. - + :returns: :class:`WorkspaceObjectPermissions` @@ -152,18 +152,18 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" obj = w.workspace.get_status(path=notebook_path) Get status. - + Gets the status of an object or a directory. If `path` does not exist, this call returns an error `RESOURCE_DOES_NOT_EXIST`. - + :param path: str The absolute path of the notebook or directory. - + :returns: :class:`ObjectInfo` @@ -182,35 +182,37 @@ w = WorkspaceClient() - notebook_path = f'/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}' + notebook_path = f"/Users/{w.current_user.me().user_name}/sdk-{time.time_ns()}" - w.workspace.import_(content=base64.b64encode(("CREATE LIVE TABLE dlt_sample AS SELECT 1").encode()).decode(), - format=workspace.ImportFormat.SOURCE, - language=workspace.Language.SQL, - overwrite=True, - path=notebook_path) + w.workspace.import_( + content=base64.b64encode(("CREATE LIVE TABLE dlt_sample AS SELECT 1").encode()).decode(), + format=workspace.ImportFormat.SOURCE, + language=workspace.Language.SQL, + overwrite=True, + path=notebook_path, + ) Import a workspace object. - + Imports a workspace object (for example, a notebook or file) or the contents of an entire directory. If `path` already exists and `overwrite` is set to `false`, this call returns an error `RESOURCE_ALREADY_EXISTS`. To import a directory, you can use either the `DBC` format or the `SOURCE` format with the `language` field unset. To import a single file as `SOURCE`, you must set the `language` field. - + :param path: str The absolute path of the object or directory. Importing a directory is only supported for the `DBC` and `SOURCE` formats. :param content: str (optional) The base64-encoded content. This has a limit of 10 MB. - + If the limit (10MB) is exceeded, exception with error code **MAX_NOTEBOOK_SIZE_EXCEEDED** is thrown. This parameter might be absent, and instead a posted file is used. :param format: :class:`ImportFormat` (optional) This specifies the format of the file to be imported. - + The value is case sensitive. - + - `AUTO`: The item is imported depending on an analysis of the item's extension and the header content provided in the request. If the item is imported as a notebook, then the item's extension is automatically removed. - `SOURCE`: The notebook or directory is imported as source code. - `HTML`: @@ -222,8 +224,8 @@ :param overwrite: bool (optional) The flag that specifies whether to overwrite existing object. It is `false` by default. For `DBC` format, `overwrite` is not supported since it may contain a directory. - - + + .. py:method:: list(path: str [, notebooks_modified_after: int, recursive: bool = False]) -> ObjectInfo @@ -238,7 +240,7 @@ w = WorkspaceClient() names = [] - for i in w.workspace.list(f'/Users/{w.current_user.me().user_name}', recursive=True): + for i in w.workspace.list(f"/Users/{w.current_user.me().user_name}", recursive=True): names.append(i.path) assert len(names) > 0 @@ -253,51 +255,51 @@ .. py:method:: mkdirs(path: str) Create a directory. - + Creates the specified directory (and necessary parent directories if they do not exist). If there is an object (not a directory) at any prefix of the input path, this call returns an error `RESOURCE_ALREADY_EXISTS`. - + Note that if this operation fails it may have succeeded in creating some of the necessary parent directories. - + :param path: str The absolute path of the directory. If the parent directories do not exist, it will also create them. If the directory already exists, this command will do nothing and succeed. - - + + .. py:method:: set_permissions(workspace_object_type: str, workspace_object_id: str [, access_control_list: Optional[List[WorkspaceObjectAccessControlRequest]]]) -> WorkspaceObjectPermissions Set workspace object permissions. - + Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their parent objects or root object. - + :param workspace_object_type: str The workspace object type for which to get or manage permissions. :param workspace_object_id: str The workspace object for which to get or manage permissions. :param access_control_list: List[:class:`WorkspaceObjectAccessControlRequest`] (optional) - + :returns: :class:`WorkspaceObjectPermissions` .. py:method:: update_permissions(workspace_object_type: str, workspace_object_id: str [, access_control_list: Optional[List[WorkspaceObjectAccessControlRequest]]]) -> WorkspaceObjectPermissions Update workspace object permissions. - + Updates the permissions on a workspace object. Workspace objects can inherit permissions from their parent objects or root object. - + :param workspace_object_type: str The workspace object type for which to get or manage permissions. :param workspace_object_id: str The workspace object for which to get or manage permissions. :param access_control_list: List[:class:`WorkspaceObjectAccessControlRequest`] (optional) - + :returns: :class:`WorkspaceObjectPermissions` @@ -315,12 +317,12 @@ w = WorkspaceClient() - notebook = f'/Users/{w.current_user.me().user_name}/notebook-{time.time_ns()}.py' + notebook = f"/Users/{w.current_user.me().user_name}/notebook-{time.time_ns()}.py" - w.workspace.upload(notebook, io.BytesIO(b'print(1)')) + w.workspace.upload(notebook, io.BytesIO(b"print(1)")) with w.workspace.download(notebook) as f: content = f.read() - assert content == b'# Databricks notebook source\nprint(1)' + assert content == b"# Databricks notebook source\nprint(1)" w.workspace.delete(notebook)