From 4430ade8d302d25daebbc2289327585ba122203c Mon Sep 17 00:00:00 2001 From: Hector Castejon Diaz Date: Tue, 17 Dec 2024 11:51:00 +0100 Subject: [PATCH] [Release] Release v0.40.0 ### API Changes: * Added [a.account_federation_policy](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_federation_policy.html) account-level service and [a.service_principal_federation_policy](https://databricks-sdk-py.readthedocs.io/en/latest/account/service_principal_federation_policy.html) account-level service. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterAttributes`. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterDetails`. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterSpec`. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.CreateCluster`. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.EditCluster`. * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.UpdateClusterResource`. * Added `update_parameter_syntax` field for `databricks.sdk.service.dashboards.MigrateDashboardRequest`. * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.RunTask`. * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.SubmitTask`. * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.Task`. * Changed `days_of_week` field for `databricks.sdk.service.pipelines.RestartWindow` to type `databricks.sdk.service.pipelines.RestartWindowDaysOfWeekList` dataclass. OpenAPI SHA: a6a317df8327c9b1e5cb59a03a42ffa2aabeef6d, Date: 2024-12-16 --- .codegen/_openapi_sha | 2 +- CHANGELOG.md | 19 + databricks/sdk/__init__.py | 16 +- databricks/sdk/service/catalog.py | 4 +- databricks/sdk/service/compute.py | 424 +++++- databricks/sdk/service/dashboards.py | 18 +- databricks/sdk/service/jobs.py | 103 +- databricks/sdk/service/oauth2.py | 461 +++++++ databricks/sdk/service/pipelines.py | 10 +- databricks/sdk/version.py | 2 +- docs/account/billing/billable_usage.rst | 43 +- docs/account/billing/budgets.rst | 95 +- docs/account/billing/log_delivery.rst | 213 ++- docs/account/billing/usage_dashboards.rst | 47 +- .../account/catalog/metastore_assignments.rst | 101 +- docs/account/catalog/metastores.rst | 79 +- docs/account/catalog/storage_credentials.rst | 117 +- docs/account/iam/access_control.rst | 73 +- docs/account/iam/groups.rst | 209 ++- docs/account/iam/service_principals.rst | 215 ++- docs/account/iam/users.rst | 297 ++--- docs/account/iam/workspace_assignment.rst | 89 +- .../account/oauth2/custom_app_integration.rst | 113 +- docs/account/oauth2/federation_policy.rst | 98 ++ docs/account/oauth2/index.rst | 2 + docs/account/oauth2/o_auth_published_apps.rst | 23 +- .../oauth2/published_app_integration.rst | 91 +- .../service_principal_federation_policy.rst | 108 ++ .../oauth2/service_principal_secrets.rst | 87 +- docs/account/provisioning/credentials.rst | 89 +- docs/account/provisioning/encryption_keys.rst | 151 ++- docs/account/provisioning/networks.rst | 105 +- docs/account/provisioning/private_access.rst | 255 ++-- docs/account/provisioning/storage.rst | 85 +- docs/account/provisioning/vpc_endpoints.rst | 121 +- docs/account/provisioning/workspaces.rst | 554 ++++---- .../settings/csp_enablement_account.rst | 59 +- .../settings/disable_legacy_features.rst | 81 +- .../settings/esm_enablement_account.rst | 53 +- docs/account/settings/ip_access_lists.rst | 239 ++-- .../account/settings/network_connectivity.rst | 179 ++- docs/account/settings/personal_compute.rst | 85 +- docs/account/settings/settings.rst | 34 +- docs/dbdataclasses/catalog.rst | 12 +- docs/dbdataclasses/compute.rst | 21 +- docs/dbdataclasses/jobs.rst | 8 +- docs/dbdataclasses/oauth2.rst | 12 + docs/workspace/apps/apps.rst | 268 ++-- .../workspace/catalog/artifact_allowlists.rst | 43 +- docs/workspace/catalog/catalogs.rst | 191 ++- docs/workspace/catalog/connections.rst | 141 +- docs/workspace/catalog/external_locations.rst | 225 ++-- docs/workspace/catalog/functions.rst | 179 ++- docs/workspace/catalog/grants.rst | 89 +- docs/workspace/catalog/metastores.rst | 255 ++-- docs/workspace/catalog/model_versions.rst | 203 ++- docs/workspace/catalog/online_tables.rst | 56 +- docs/workspace/catalog/quality_monitors.rst | 431 +++--- docs/workspace/catalog/registered_models.rst | 331 +++-- docs/workspace/catalog/resource_quotas.rst | 59 +- docs/workspace/catalog/schemas.rst | 169 ++- .../workspace/catalog/storage_credentials.rst | 265 ++-- docs/workspace/catalog/system_schemas.rst | 77 +- docs/workspace/catalog/table_constraints.rst | 93 +- docs/workspace/catalog/tables.rst | 255 ++-- .../catalog/temporary_table_credentials.rst | 49 +- docs/workspace/catalog/volumes.rst | 237 ++-- docs/workspace/catalog/workspace_bindings.rst | 135 +- .../cleanrooms/clean_room_assets.rst | 133 +- .../cleanrooms/clean_room_task_runs.rst | 27 +- docs/workspace/cleanrooms/clean_rooms.rst | 125 +- docs/workspace/compute/cluster_policies.rst | 307 +++-- docs/workspace/compute/clusters.rst | 1186 +++++++++-------- docs/workspace/compute/command_execution.rst | 142 +- .../workspace/compute/global_init_scripts.rst | 151 ++- docs/workspace/compute/instance_pools.rst | 311 +++-- docs/workspace/compute/instance_profiles.rst | 163 ++- docs/workspace/compute/libraries.rst | 103 +- .../policy_compliance_for_clusters.rst | 103 +- docs/workspace/compute/policy_families.rst | 57 +- docs/workspace/dashboards/genie.rst | 134 +- docs/workspace/dashboards/lakeview.rst | 364 ++--- docs/workspace/files/dbfs.rst | 220 +-- docs/workspace/files/files.rst | 225 ++-- .../iam/account_access_control_proxy.rst | 73 +- docs/workspace/iam/current_user.rst | 9 +- docs/workspace/iam/groups.rst | 209 ++- docs/workspace/iam/permission_migration.rst | 23 +- docs/workspace/iam/permissions.rst | 199 ++- docs/workspace/iam/service_principals.rst | 215 ++- docs/workspace/iam/users.rst | 347 +++-- docs/workspace/jobs/jobs.rst | 1112 ++++++++-------- .../jobs/policy_compliance_for_jobs.rst | 93 +- .../marketplace/consumer_fulfillments.rst | 41 +- .../marketplace/consumer_installations.rst | 101 +- .../marketplace/consumer_listings.rst | 111 +- .../consumer_personalization_requests.rst | 61 +- .../marketplace/consumer_providers.rst | 45 +- .../marketplace/provider_exchange_filters.rst | 61 +- .../marketplace/provider_exchanges.rst | 139 +- docs/workspace/marketplace/provider_files.rst | 65 +- .../marketplace/provider_listings.rst | 75 +- .../provider_personalization_requests.rst | 41 +- ...provider_provider_analytics_dashboards.rst | 53 +- .../marketplace/provider_providers.rst | 73 +- docs/workspace/ml/experiments.rst | 923 +++++++------ docs/workspace/ml/model_registry.rst | 1141 ++++++++-------- docs/workspace/pipelines/pipelines.rst | 572 ++++---- docs/workspace/provisioning/credentials.rst | 89 +- docs/workspace/serving/serving_endpoints.rst | 466 +++---- .../serving/serving_endpoints_data_plane.rst | 95 +- ...aibi_dashboard_embedding_access_policy.rst | 77 +- ...i_dashboard_embedding_approved_domains.rst | 79 +- .../settings/automatic_cluster_update.rst | 57 +- .../settings/compliance_security_profile.rst | 61 +- .../settings/credentials_manager.rst | 27 +- docs/workspace/settings/default_namespace.rst | 121 +- .../settings/disable_legacy_access.rst | 83 +- .../settings/disable_legacy_dbfs.rst | 75 +- .../settings/enhanced_security_monitoring.rst | 65 +- docs/workspace/settings/ip_access_lists.rst | 243 ++-- .../settings/notification_destinations.rst | 95 +- .../settings/restrict_workspace_admins.rst | 101 +- docs/workspace/settings/settings.rst | 68 +- docs/workspace/settings/token_management.rst | 127 +- docs/workspace/settings/tokens.rst | 59 +- docs/workspace/settings/workspace_conf.rst | 25 +- docs/workspace/sharing/providers.rst | 185 ++- .../sharing/recipient_activation.rst | 43 +- docs/workspace/sharing/recipients.rst | 271 ++-- docs/workspace/sharing/shares.rst | 253 ++-- docs/workspace/sql/alerts.rst | 93 +- docs/workspace/sql/alerts_legacy.rst | 173 ++- docs/workspace/sql/dashboard_widgets.rst | 73 +- docs/workspace/sql/dashboards.rst | 149 +-- docs/workspace/sql/data_sources.rst | 43 +- docs/workspace/sql/dbsql_permissions.rst | 125 +- docs/workspace/sql/queries.rst | 109 +- docs/workspace/sql/queries_legacy.rst | 303 +++-- docs/workspace/sql/query_history.rst | 43 +- docs/workspace/sql/query_visualizations.rst | 53 +- .../sql/query_visualizations_legacy.rst | 131 +- docs/workspace/sql/statement_execution.rst | 457 ++++--- docs/workspace/sql/warehouses.rst | 486 +++---- .../vectorsearch/vector_search_endpoints.rst | 60 +- .../vectorsearch/vector_search_indexes.rst | 271 ++-- docs/workspace/workspace/git_credentials.rst | 141 +- docs/workspace/workspace/repos.rst | 219 ++- docs/workspace/workspace/secrets.rst | 375 +++--- docs/workspace/workspace/workspace.rst | 353 +++-- 150 files changed, 13030 insertions(+), 11978 deletions(-) create mode 100644 docs/account/oauth2/federation_policy.rst create mode 100644 docs/account/oauth2/service_principal_federation_policy.rst diff --git a/.codegen/_openapi_sha b/.codegen/_openapi_sha index 68cd2f4be..8622b29ca 100644 --- a/.codegen/_openapi_sha +++ b/.codegen/_openapi_sha @@ -1 +1 @@ -7016dcbf2e011459416cf408ce21143bcc4b3a25 \ No newline at end of file +a6a317df8327c9b1e5cb59a03a42ffa2aabeef6d \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index aea3eb9c8..4f7aa3cc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,24 @@ # Version changelog +## [Release] Release v0.40.0 + +### API Changes: + + * Added [a.account_federation_policy](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_federation_policy.html) account-level service and [a.service_principal_federation_policy](https://databricks-sdk-py.readthedocs.io/en/latest/account/service_principal_federation_policy.html) account-level service. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterAttributes`. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterDetails`. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.ClusterSpec`. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.CreateCluster`. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.EditCluster`. + * Added `is_single_node`, `kind` and `use_ml_runtime` fields for `databricks.sdk.service.compute.UpdateClusterResource`. + * Added `update_parameter_syntax` field for `databricks.sdk.service.dashboards.MigrateDashboardRequest`. + * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.RunTask`. + * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.SubmitTask`. + * Added `clean_rooms_notebook_task` field for `databricks.sdk.service.jobs.Task`. + * Changed `days_of_week` field for `databricks.sdk.service.pipelines.RestartWindow` to type `databricks.sdk.service.pipelines.RestartWindowDaysOfWeekList` dataclass. + +OpenAPI SHA: a6a317df8327c9b1e5cb59a03a42ffa2aabeef6d, Date: 2024-12-16 + ## [Release] Release v0.39.0 ### Bug Fixes diff --git a/databricks/sdk/__init__.py b/databricks/sdk/__init__.py index beb3fd7bb..068069f04 100755 --- a/databricks/sdk/__init__.py +++ b/databricks/sdk/__init__.py @@ -56,9 +56,11 @@ ProviderListingsAPI, ProviderPersonalizationRequestsAPI, ProviderProviderAnalyticsDashboardsAPI, ProviderProvidersAPI) from databricks.sdk.service.ml import ExperimentsAPI, ModelRegistryAPI -from databricks.sdk.service.oauth2 import (CustomAppIntegrationAPI, +from databricks.sdk.service.oauth2 import (AccountFederationPolicyAPI, + CustomAppIntegrationAPI, OAuthPublishedAppsAPI, PublishedAppIntegrationAPI, + ServicePrincipalFederationPolicyAPI, ServicePrincipalSecretsAPI) from databricks.sdk.service.pipelines import PipelinesAPI from databricks.sdk.service.provisioning import (CredentialsAPI, @@ -826,6 +828,7 @@ def __init__(self, self._credentials = CredentialsAPI(self._api_client) self._custom_app_integration = CustomAppIntegrationAPI(self._api_client) self._encryption_keys = EncryptionKeysAPI(self._api_client) + self._federation_policy = AccountFederationPolicyAPI(self._api_client) self._groups = AccountGroupsAPI(self._api_client) self._ip_access_lists = AccountIpAccessListsAPI(self._api_client) self._log_delivery = LogDeliveryAPI(self._api_client) @@ -836,6 +839,7 @@ def __init__(self, self._o_auth_published_apps = OAuthPublishedAppsAPI(self._api_client) self._private_access = PrivateAccessAPI(self._api_client) self._published_app_integration = PublishedAppIntegrationAPI(self._api_client) + self._service_principal_federation_policy = ServicePrincipalFederationPolicyAPI(self._api_client) self._service_principal_secrets = ServicePrincipalSecretsAPI(self._api_client) self._service_principals = AccountServicePrincipalsAPI(self._api_client) self._settings = AccountSettingsAPI(self._api_client) @@ -881,6 +885,11 @@ def encryption_keys(self) -> EncryptionKeysAPI: """These APIs manage encryption key configurations for this workspace (optional).""" return self._encryption_keys + @property + def federation_policy(self) -> AccountFederationPolicyAPI: + """These APIs manage account federation policies.""" + return self._federation_policy + @property def groups(self) -> AccountGroupsAPI: """Groups simplify identity management, making it easier to assign access to Databricks account, data, and other securable objects.""" @@ -931,6 +940,11 @@ def published_app_integration(self) -> PublishedAppIntegrationAPI: """These APIs enable administrators to manage published OAuth app integrations, which is required for adding/using Published OAuth App Integration like Tableau Desktop for Databricks in AWS cloud.""" return self._published_app_integration + @property + def service_principal_federation_policy(self) -> ServicePrincipalFederationPolicyAPI: + """These APIs manage service principal federation policies.""" + return self._service_principal_federation_policy + @property def service_principal_secrets(self) -> ServicePrincipalSecretsAPI: """These APIs enable administrators to manage service principal secrets.""" diff --git a/databricks/sdk/service/catalog.py b/databricks/sdk/service/catalog.py index 0798bb5b6..f1b549339 100755 --- a/databricks/sdk/service/catalog.py +++ b/databricks/sdk/service/catalog.py @@ -3704,8 +3704,8 @@ def from_dict(cls, d: Dict[str, any]) -> GenerateTemporaryTableCredentialRespons class GetBindingsSecurableType(Enum): CATALOG = 'catalog' + CREDENTIAL = 'credential' EXTERNAL_LOCATION = 'external_location' - SERVICE_CREDENTIAL = 'service_credential' STORAGE_CREDENTIAL = 'storage_credential' @@ -7067,8 +7067,8 @@ def from_dict(cls, d: Dict[str, any]) -> UpdateAssignmentResponse: class UpdateBindingsSecurableType(Enum): CATALOG = 'catalog' + CREDENTIAL = 'credential' EXTERNAL_LOCATION = 'external_location' - SERVICE_CREDENTIAL = 'service_credential' STORAGE_CREDENTIAL = 'storage_credential' diff --git a/databricks/sdk/service/compute.py b/databricks/sdk/service/compute.py index d8be32003..0afdb6f19 100755 --- a/databricks/sdk/service/compute.py +++ b/databricks/sdk/service/compute.py @@ -659,13 +659,19 @@ class ClusterAttributes: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -706,6 +712,20 @@ class ClusterAttributes: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + + kind: Optional[Kind] = None + """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`.""" + node_type_id: Optional[str] = None """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 @@ -750,6 +770,12 @@ class ClusterAttributes: private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -773,6 +799,8 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind.value if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.policy_id is not None: body['policy_id'] = self.policy_id if self.runtime_engine is not None: body['runtime_engine'] = self.runtime_engine.value @@ -781,6 +809,7 @@ def as_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = [v for v in self.ssh_public_keys] + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -805,6 +834,8 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.policy_id is not None: body['policy_id'] = self.policy_id if self.runtime_engine is not None: body['runtime_engine'] = self.runtime_engine @@ -813,6 +844,7 @@ def as_shallow_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = self.ssh_public_keys + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -834,6 +866,8 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterAttributes: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), + kind=_enum(d, 'kind', Kind), node_type_id=d.get('node_type_id', None), policy_id=d.get('policy_id', None), runtime_engine=_enum(d, 'runtime_engine', RuntimeEngine), @@ -842,6 +876,7 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterAttributes: spark_env_vars=d.get('spark_env_vars', None), spark_version=d.get('spark_version', None), ssh_public_keys=d.get('ssh_public_keys', None), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -948,13 +983,19 @@ class ClusterDetails: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -1015,10 +1056,24 @@ class ClusterDetails: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + jdbc_port: Optional[int] = None """Port on which Spark JDBC server is listening, in the driver nod. No service will be listeningon on this port in executor nodes.""" + kind: Optional[Kind] = None + """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`.""" + last_restarted_time: Optional[int] = None """the timestamp that the cluster was started/restarted""" @@ -1111,6 +1166,12 @@ class ClusterDetails: """Information about why the cluster was terminated. This field only appears when the cluster is in a `TERMINATING` or `TERMINATED` state.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -1144,7 +1205,9 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node if self.jdbc_port is not None: body['jdbc_port'] = self.jdbc_port + if self.kind is not None: body['kind'] = self.kind.value if self.last_restarted_time is not None: body['last_restarted_time'] = self.last_restarted_time if self.last_state_loss_time is not None: body['last_state_loss_time'] = self.last_state_loss_time if self.node_type_id is not None: body['node_type_id'] = self.node_type_id @@ -1163,6 +1226,7 @@ def as_dict(self) -> dict: if self.state_message is not None: body['state_message'] = self.state_message if self.terminated_time is not None: body['terminated_time'] = self.terminated_time if self.termination_reason: body['termination_reason'] = self.termination_reason.as_dict() + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -1197,7 +1261,9 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node if self.jdbc_port is not None: body['jdbc_port'] = self.jdbc_port + if self.kind is not None: body['kind'] = self.kind if self.last_restarted_time is not None: body['last_restarted_time'] = self.last_restarted_time if self.last_state_loss_time is not None: body['last_state_loss_time'] = self.last_state_loss_time if self.node_type_id is not None: body['node_type_id'] = self.node_type_id @@ -1216,6 +1282,7 @@ def as_shallow_dict(self) -> dict: if self.state_message is not None: body['state_message'] = self.state_message if self.terminated_time is not None: body['terminated_time'] = self.terminated_time if self.termination_reason: body['termination_reason'] = self.termination_reason + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -1247,7 +1314,9 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterDetails: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), jdbc_port=d.get('jdbc_port', None), + kind=_enum(d, 'kind', Kind), last_restarted_time=d.get('last_restarted_time', None), last_state_loss_time=d.get('last_state_loss_time', None), node_type_id=d.get('node_type_id', None), @@ -1266,6 +1335,7 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterDetails: state_message=d.get('state_message', None), terminated_time=d.get('terminated_time', None), termination_reason=_from_dict(d, 'termination_reason', TerminationReason), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -1870,13 +1940,19 @@ class ClusterSpec: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -1917,6 +1993,20 @@ class ClusterSpec: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + + kind: Optional[Kind] = None + """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`.""" + node_type_id: Optional[str] = None """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 @@ -1975,6 +2065,12 @@ class ClusterSpec: private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -2001,6 +2097,8 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind.value if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -2010,6 +2108,7 @@ def as_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = [v for v in self.ssh_public_keys] + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -2037,6 +2136,8 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -2046,6 +2147,7 @@ def as_shallow_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = self.ssh_public_keys + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -2069,6 +2171,8 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterSpec: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), + kind=_enum(d, 'kind', Kind), node_type_id=d.get('node_type_id', None), num_workers=d.get('num_workers', None), policy_id=d.get('policy_id', None), @@ -2078,6 +2182,7 @@ def from_dict(cls, d: Dict[str, any]) -> ClusterSpec: spark_env_vars=d.get('spark_env_vars', None), spark_version=d.get('spark_version', None), ssh_public_keys=d.get('ssh_public_keys', None), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -2251,13 +2356,19 @@ class CreateCluster: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -2298,6 +2409,20 @@ class CreateCluster: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + + kind: Optional[Kind] = None + """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`.""" + node_type_id: Optional[str] = None """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 @@ -2352,6 +2477,12 @@ class CreateCluster: private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -2379,6 +2510,8 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind.value if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -2388,6 +2521,7 @@ def as_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = [v for v in self.ssh_public_keys] + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -2416,6 +2550,8 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -2425,6 +2561,7 @@ def as_shallow_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = self.ssh_public_keys + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -2449,6 +2586,8 @@ def from_dict(cls, d: Dict[str, any]) -> CreateCluster: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), + kind=_enum(d, 'kind', Kind), node_type_id=d.get('node_type_id', None), num_workers=d.get('num_workers', None), policy_id=d.get('policy_id', None), @@ -2458,6 +2597,7 @@ def from_dict(cls, d: Dict[str, any]) -> CreateCluster: spark_env_vars=d.get('spark_env_vars', None), spark_version=d.get('spark_version', None), ssh_public_keys=d.get('ssh_public_keys', None), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -2848,13 +2988,19 @@ class DataPlaneEventDetailsEventType(Enum): class DataSecurityMode(Enum): """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -2865,6 +3011,9 @@ class DataSecurityMode(Enum): Passthrough on standard clusters. * `LEGACY_SINGLE_USER_STANDARD`: This mode provides a way that doesn’t have UC nor passthrough enabled.""" + DATA_SECURITY_MODE_AUTO = 'DATA_SECURITY_MODE_AUTO' + DATA_SECURITY_MODE_DEDICATED = 'DATA_SECURITY_MODE_DEDICATED' + DATA_SECURITY_MODE_STANDARD = 'DATA_SECURITY_MODE_STANDARD' LEGACY_PASSTHROUGH = 'LEGACY_PASSTHROUGH' LEGACY_SINGLE_USER = 'LEGACY_SINGLE_USER' LEGACY_SINGLE_USER_STANDARD = 'LEGACY_SINGLE_USER_STANDARD' @@ -3306,13 +3455,19 @@ class EditCluster: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -3353,6 +3508,20 @@ class EditCluster: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + + kind: Optional[Kind] = None + """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`.""" + node_type_id: Optional[str] = None """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 @@ -3407,6 +3576,12 @@ class EditCluster: private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -3434,6 +3609,8 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind.value if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -3443,6 +3620,7 @@ def as_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = [v for v in self.ssh_public_keys] + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -3471,6 +3649,8 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -3480,6 +3660,7 @@ def as_shallow_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = self.ssh_public_keys + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -3504,6 +3685,8 @@ def from_dict(cls, d: Dict[str, any]) -> EditCluster: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), + kind=_enum(d, 'kind', Kind), node_type_id=d.get('node_type_id', None), num_workers=d.get('num_workers', None), policy_id=d.get('policy_id', None), @@ -3513,6 +3696,7 @@ def from_dict(cls, d: Dict[str, any]) -> EditCluster: spark_env_vars=d.get('spark_env_vars', None), spark_version=d.get('spark_version', None), ssh_public_keys=d.get('ssh_public_keys', None), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -5642,6 +5826,17 @@ def from_dict(cls, d: Dict[str, any]) -> InstanceProfile: is_meta_instance_profile=d.get('is_meta_instance_profile', None)) +class Kind(Enum): + """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`.""" + + CLASSIC_PREVIEW = 'CLASSIC_PREVIEW' + + class Language(Enum): PYTHON = 'python' @@ -7560,13 +7755,19 @@ class UpdateClusterResource: data_security_mode: Optional[DataSecurityMode] = None """Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -7607,6 +7808,20 @@ class UpdateClusterResource: instance_pool_id: Optional[str] = None """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`. + + When set to true, Databricks will automatically set single node related `custom_tags`, + `spark_conf`, and `num_workers`""" + + kind: Optional[Kind] = None + """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`.""" + node_type_id: Optional[str] = None """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 @@ -7665,6 +7880,12 @@ class UpdateClusterResource: private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be specified.""" + use_ml_runtime: Optional[bool] = None + """This field can only be used with `kind`. + + `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.""" + workload_type: Optional[WorkloadType] = None def as_dict(self) -> dict: @@ -7689,6 +7910,8 @@ def as_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes.as_dict() if self.init_scripts: body['init_scripts'] = [v.as_dict() for v in self.init_scripts] if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind.value if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -7698,6 +7921,7 @@ def as_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = [v for v in self.ssh_public_keys] + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type.as_dict() return body @@ -7723,6 +7947,8 @@ def as_shallow_dict(self) -> dict: if self.gcp_attributes: body['gcp_attributes'] = self.gcp_attributes if self.init_scripts: body['init_scripts'] = self.init_scripts if self.instance_pool_id is not None: body['instance_pool_id'] = self.instance_pool_id + if self.is_single_node is not None: body['is_single_node'] = self.is_single_node + if self.kind is not None: body['kind'] = self.kind if self.node_type_id is not None: body['node_type_id'] = self.node_type_id if self.num_workers is not None: body['num_workers'] = self.num_workers if self.policy_id is not None: body['policy_id'] = self.policy_id @@ -7732,6 +7958,7 @@ def as_shallow_dict(self) -> dict: if self.spark_env_vars: body['spark_env_vars'] = self.spark_env_vars if self.spark_version is not None: body['spark_version'] = self.spark_version if self.ssh_public_keys: body['ssh_public_keys'] = self.ssh_public_keys + if self.use_ml_runtime is not None: body['use_ml_runtime'] = self.use_ml_runtime if self.workload_type: body['workload_type'] = self.workload_type return body @@ -7754,6 +7981,8 @@ def from_dict(cls, d: Dict[str, any]) -> UpdateClusterResource: gcp_attributes=_from_dict(d, 'gcp_attributes', GcpAttributes), init_scripts=_repeated_dict(d, 'init_scripts', InitScriptInfo), instance_pool_id=d.get('instance_pool_id', None), + is_single_node=d.get('is_single_node', None), + kind=_enum(d, 'kind', Kind), node_type_id=d.get('node_type_id', None), num_workers=d.get('num_workers', None), policy_id=d.get('policy_id', None), @@ -7763,6 +7992,7 @@ def from_dict(cls, d: Dict[str, any]) -> UpdateClusterResource: spark_env_vars=d.get('spark_env_vars', None), spark_version=d.get('spark_version', None), ssh_public_keys=d.get('ssh_public_keys', None), + use_ml_runtime=d.get('use_ml_runtime', None), workload_type=_from_dict(d, 'workload_type', WorkloadType)) @@ -8301,6 +8531,8 @@ def create(self, gcp_attributes: Optional[GcpAttributes] = None, init_scripts: Optional[List[InitScriptInfo]] = None, instance_pool_id: Optional[str] = None, + is_single_node: Optional[bool] = None, + kind: Optional[Kind] = None, node_type_id: Optional[str] = None, num_workers: Optional[int] = None, policy_id: Optional[str] = None, @@ -8309,6 +8541,7 @@ def create(self, spark_conf: Optional[Dict[str, str]] = None, spark_env_vars: Optional[Dict[str, str]] = None, ssh_public_keys: Optional[List[str]] = None, + use_ml_runtime: Optional[bool] = None, workload_type: Optional[WorkloadType] = None) -> Wait[ClusterDetails]: """Create new cluster. @@ -8364,13 +8597,19 @@ def create(self, :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -8402,6 +8641,17 @@ def create(self, logs are sent to `//init_scripts`. :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`. + + 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`. :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 @@ -8448,6 +8698,11 @@ def create(self, SSH public key contents that will be added to each Spark node in this cluster. The corresponding 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`. + + `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: @@ -8475,6 +8730,8 @@ def create(self, if gcp_attributes is not None: body['gcp_attributes'] = gcp_attributes.as_dict() if init_scripts is not None: body['init_scripts'] = [v.as_dict() for v in init_scripts] if instance_pool_id is not None: body['instance_pool_id'] = instance_pool_id + if is_single_node is not None: body['is_single_node'] = is_single_node + if kind is not None: body['kind'] = kind.value if node_type_id is not None: body['node_type_id'] = node_type_id if num_workers is not None: body['num_workers'] = num_workers if policy_id is not None: body['policy_id'] = policy_id @@ -8484,6 +8741,7 @@ def create(self, if spark_env_vars is not None: body['spark_env_vars'] = spark_env_vars if spark_version is not None: body['spark_version'] = spark_version if ssh_public_keys is not None: body['ssh_public_keys'] = [v for v in ssh_public_keys] + if use_ml_runtime is not None: body['use_ml_runtime'] = use_ml_runtime if workload_type is not None: body['workload_type'] = workload_type.as_dict() headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } @@ -8514,6 +8772,8 @@ def create_and_wait( gcp_attributes: Optional[GcpAttributes] = None, init_scripts: Optional[List[InitScriptInfo]] = None, instance_pool_id: Optional[str] = None, + is_single_node: Optional[bool] = None, + kind: Optional[Kind] = None, node_type_id: Optional[str] = None, num_workers: Optional[int] = None, policy_id: Optional[str] = None, @@ -8522,6 +8782,7 @@ def create_and_wait( spark_conf: Optional[Dict[str, str]] = None, spark_env_vars: Optional[Dict[str, str]] = None, ssh_public_keys: Optional[List[str]] = None, + use_ml_runtime: Optional[bool] = None, workload_type: Optional[WorkloadType] = None, timeout=timedelta(minutes=20)) -> ClusterDetails: return self.create(apply_policy_default_values=apply_policy_default_values, @@ -8542,6 +8803,8 @@ def create_and_wait( gcp_attributes=gcp_attributes, init_scripts=init_scripts, instance_pool_id=instance_pool_id, + is_single_node=is_single_node, + kind=kind, node_type_id=node_type_id, num_workers=num_workers, policy_id=policy_id, @@ -8551,6 +8814,7 @@ def create_and_wait( spark_env_vars=spark_env_vars, spark_version=spark_version, ssh_public_keys=ssh_public_keys, + use_ml_runtime=use_ml_runtime, workload_type=workload_type).result(timeout=timeout) def delete(self, cluster_id: str) -> Wait[ClusterDetails]: @@ -8600,6 +8864,8 @@ def edit(self, gcp_attributes: Optional[GcpAttributes] = None, init_scripts: Optional[List[InitScriptInfo]] = None, instance_pool_id: Optional[str] = None, + is_single_node: Optional[bool] = None, + kind: Optional[Kind] = None, node_type_id: Optional[str] = None, num_workers: Optional[int] = None, policy_id: Optional[str] = None, @@ -8608,6 +8874,7 @@ def edit(self, spark_conf: Optional[Dict[str, str]] = None, spark_env_vars: Optional[Dict[str, str]] = None, ssh_public_keys: Optional[List[str]] = None, + use_ml_runtime: Optional[bool] = None, workload_type: Optional[WorkloadType] = None) -> Wait[ClusterDetails]: """Update cluster configuration. @@ -8663,13 +8930,19 @@ def edit(self, :param data_security_mode: :class:`DataSecurityMode` (optional) Data security mode decides what data governance model to use when accessing data from a cluster. - * `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 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 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: @@ -8701,6 +8974,17 @@ def edit(self, logs are sent to `//init_scripts`. :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`. + + 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`. :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 @@ -8747,6 +9031,11 @@ def edit(self, SSH public key contents that will be added to each Spark node in this cluster. The corresponding 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`. + + `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: @@ -8774,6 +9063,8 @@ def edit(self, if gcp_attributes is not None: body['gcp_attributes'] = gcp_attributes.as_dict() if init_scripts is not None: body['init_scripts'] = [v.as_dict() for v in init_scripts] if instance_pool_id is not None: body['instance_pool_id'] = instance_pool_id + if is_single_node is not None: body['is_single_node'] = is_single_node + if kind is not None: body['kind'] = kind.value if node_type_id is not None: body['node_type_id'] = node_type_id if num_workers is not None: body['num_workers'] = num_workers if policy_id is not None: body['policy_id'] = policy_id @@ -8783,6 +9074,7 @@ def edit(self, if spark_env_vars is not None: body['spark_env_vars'] = spark_env_vars if spark_version is not None: body['spark_version'] = spark_version if ssh_public_keys is not None: body['ssh_public_keys'] = [v for v in ssh_public_keys] + if use_ml_runtime is not None: body['use_ml_runtime'] = use_ml_runtime if workload_type is not None: body['workload_type'] = workload_type.as_dict() headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } @@ -8813,6 +9105,8 @@ def edit_and_wait( gcp_attributes: Optional[GcpAttributes] = None, init_scripts: Optional[List[InitScriptInfo]] = None, instance_pool_id: Optional[str] = None, + is_single_node: Optional[bool] = None, + kind: Optional[Kind] = None, node_type_id: Optional[str] = None, num_workers: Optional[int] = None, policy_id: Optional[str] = None, @@ -8821,6 +9115,7 @@ def edit_and_wait( spark_conf: Optional[Dict[str, str]] = None, spark_env_vars: Optional[Dict[str, str]] = None, ssh_public_keys: Optional[List[str]] = None, + use_ml_runtime: Optional[bool] = None, workload_type: Optional[WorkloadType] = None, timeout=timedelta(minutes=20)) -> ClusterDetails: return self.edit(apply_policy_default_values=apply_policy_default_values, @@ -8841,6 +9136,8 @@ def edit_and_wait( gcp_attributes=gcp_attributes, init_scripts=init_scripts, instance_pool_id=instance_pool_id, + is_single_node=is_single_node, + kind=kind, node_type_id=node_type_id, num_workers=num_workers, policy_id=policy_id, @@ -8850,6 +9147,7 @@ def edit_and_wait( spark_env_vars=spark_env_vars, spark_version=spark_version, ssh_public_keys=ssh_public_keys, + use_ml_runtime=use_ml_runtime, workload_type=workload_type).result(timeout=timeout) def events(self, diff --git a/databricks/sdk/service/dashboards.py b/databricks/sdk/service/dashboards.py index da908cb2d..34bd58995 100755 --- a/databricks/sdk/service/dashboards.py +++ b/databricks/sdk/service/dashboards.py @@ -711,12 +711,18 @@ class MigrateDashboardRequest: parent_path: Optional[str] = None """The workspace path of the folder to contain the migrated Lakeview dashboard.""" + update_parameter_syntax: Optional[bool] = None + """Flag to indicate if mustache parameter syntax ({{ param }}) should be auto-updated to named + syntax (:param) when converting datasets in the dashboard.""" + def as_dict(self) -> dict: """Serializes the MigrateDashboardRequest into a dictionary suitable for use as a JSON request body.""" body = {} if self.display_name is not None: body['display_name'] = self.display_name if self.parent_path is not None: body['parent_path'] = self.parent_path if self.source_dashboard_id is not None: body['source_dashboard_id'] = self.source_dashboard_id + if self.update_parameter_syntax is not None: + body['update_parameter_syntax'] = self.update_parameter_syntax return body def as_shallow_dict(self) -> dict: @@ -725,6 +731,8 @@ def as_shallow_dict(self) -> dict: if self.display_name is not None: body['display_name'] = self.display_name if self.parent_path is not None: body['parent_path'] = self.parent_path if self.source_dashboard_id is not None: body['source_dashboard_id'] = self.source_dashboard_id + if self.update_parameter_syntax is not None: + body['update_parameter_syntax'] = self.update_parameter_syntax return body @classmethod @@ -732,7 +740,8 @@ def from_dict(cls, d: Dict[str, any]) -> MigrateDashboardRequest: """Deserializes the MigrateDashboardRequest from a dictionary.""" return cls(display_name=d.get('display_name', None), parent_path=d.get('parent_path', None), - source_dashboard_id=d.get('source_dashboard_id', None)) + source_dashboard_id=d.get('source_dashboard_id', None), + update_parameter_syntax=d.get('update_parameter_syntax', None)) @dataclass @@ -1759,7 +1768,8 @@ def migrate(self, source_dashboard_id: str, *, display_name: Optional[str] = None, - parent_path: Optional[str] = None) -> Dashboard: + parent_path: Optional[str] = None, + update_parameter_syntax: Optional[bool] = None) -> Dashboard: """Migrate dashboard. Migrates a classic SQL dashboard to Lakeview. @@ -1770,6 +1780,9 @@ def migrate(self, Display name for the new Lakeview dashboard. :param parent_path: str (optional) The workspace path of the folder to contain the migrated Lakeview dashboard. + :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` """ @@ -1777,6 +1790,7 @@ def migrate(self, if display_name is not None: body['display_name'] = display_name if parent_path is not None: body['parent_path'] = parent_path if source_dashboard_id is not None: body['source_dashboard_id'] = source_dashboard_id + if update_parameter_syntax is not None: body['update_parameter_syntax'] = update_parameter_syntax headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } res = self._api.do('POST', '/api/2.0/lakeview/dashboards/migrate', body=body, headers=headers) diff --git a/databricks/sdk/service/jobs.py b/databricks/sdk/service/jobs.py index a991c7c50..105c7cd22 100755 --- a/databricks/sdk/service/jobs.py +++ b/databricks/sdk/service/jobs.py @@ -209,7 +209,8 @@ class BaseRun: previously failed run. This occurs when you request to re-run the job in case of failures. * `RUN_JOB_TASK`: Indicates a run that is triggered using a Run Job task. * `FILE_ARRIVAL`: Indicates a run that is triggered by a file arrival. * `TABLE`: Indicates a run that is - triggered by a table update.""" + triggered by a table update. * `CONTINUOUS_RESTART`: Indicates a run created by user to manually + restart a continuous job run.""" trigger_info: Optional[TriggerInfo] = None """Additional details about what triggered the run""" @@ -449,7 +450,7 @@ class CleanRoomTaskRunResultState(Enum): @dataclass class CleanRoomTaskRunState: - """Stores the run state of the clean room notebook V1 task.""" + """Stores the run state of the clean rooms notebook task.""" life_cycle_state: Optional[CleanRoomTaskRunLifeCycleState] = None """A value indicating the run's current lifecycle state. This field is always available in the @@ -479,6 +480,48 @@ def from_dict(cls, d: Dict[str, any]) -> CleanRoomTaskRunState: result_state=_enum(d, 'result_state', CleanRoomTaskRunResultState)) +@dataclass +class CleanRoomsNotebookTask: + clean_room_name: str + """The clean room that the notebook belongs to.""" + + notebook_name: str + """Name of the notebook being run.""" + + etag: Optional[str] = None + """Checksum to validate the freshness of the notebook resource (i.e. the notebook being run is the + latest version). It can be fetched by calling the :method:cleanroomassets/get API.""" + + notebook_base_parameters: Optional[Dict[str, str]] = None + """Base parameters to be used for the clean room notebook job.""" + + def as_dict(self) -> dict: + """Serializes the CleanRoomsNotebookTask into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.clean_room_name is not None: body['clean_room_name'] = self.clean_room_name + if self.etag is not None: body['etag'] = self.etag + if self.notebook_base_parameters: body['notebook_base_parameters'] = self.notebook_base_parameters + if self.notebook_name is not None: body['notebook_name'] = self.notebook_name + return body + + def as_shallow_dict(self) -> dict: + """Serializes the CleanRoomsNotebookTask into a shallow dictionary of its immediate attributes.""" + body = {} + if self.clean_room_name is not None: body['clean_room_name'] = self.clean_room_name + if self.etag is not None: body['etag'] = self.etag + if self.notebook_base_parameters: body['notebook_base_parameters'] = self.notebook_base_parameters + if self.notebook_name is not None: body['notebook_name'] = self.notebook_name + return body + + @classmethod + def from_dict(cls, d: Dict[str, any]) -> CleanRoomsNotebookTask: + """Deserializes the CleanRoomsNotebookTask from a dictionary.""" + return cls(clean_room_name=d.get('clean_room_name', None), + etag=d.get('etag', None), + notebook_base_parameters=d.get('notebook_base_parameters', None), + notebook_name=d.get('notebook_name', None)) + + @dataclass class ClusterInstance: cluster_id: Optional[str] = None @@ -2526,11 +2569,11 @@ class JobsHealthMetric(Enum): * `RUN_DURATION_SECONDS`: Expected total time for a run in seconds. * `STREAMING_BACKLOG_BYTES`: An estimate of the maximum bytes of data waiting to be consumed across all streams. This metric - is in Private Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag - across all streams. This metric is in Private Preview. * `STREAMING_BACKLOG_SECONDS`: An - estimate of the maximum consumer delay across all streams. This metric is in Private Preview. * + is in Public Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag + across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_SECONDS`: An estimate + of the maximum consumer delay across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_FILES`: An estimate of the maximum number of outstanding files across all - streams. This metric is in Private Preview.""" + streams. This metric is in Public Preview.""" RUN_DURATION_SECONDS = 'RUN_DURATION_SECONDS' STREAMING_BACKLOG_BYTES = 'STREAMING_BACKLOG_BYTES' @@ -2552,11 +2595,11 @@ class JobsHealthRule: * `RUN_DURATION_SECONDS`: Expected total time for a run in seconds. * `STREAMING_BACKLOG_BYTES`: An estimate of the maximum bytes of data waiting to be consumed across all streams. This metric - is in Private Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag - across all streams. This metric is in Private Preview. * `STREAMING_BACKLOG_SECONDS`: An - estimate of the maximum consumer delay across all streams. This metric is in Private Preview. * + is in Public Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag + across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_SECONDS`: An estimate + of the maximum consumer delay across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_FILES`: An estimate of the maximum number of outstanding files across all - streams. This metric is in Private Preview.""" + streams. This metric is in Public Preview.""" op: JobsHealthOperator """Specifies the operator used to compare the health metric value with the specified threshold.""" @@ -3711,7 +3754,8 @@ class Run: previously failed run. This occurs when you request to re-run the job in case of failures. * `RUN_JOB_TASK`: Indicates a run that is triggered using a Run Job task. * `FILE_ARRIVAL`: Indicates a run that is triggered by a file arrival. * `TABLE`: Indicates a run that is - triggered by a table update.""" + triggered by a table update. * `CONTINUOUS_RESTART`: Indicates a run created by user to manually + restart a continuous job run.""" trigger_info: Optional[TriggerInfo] = None """Additional details about what triggered the run""" @@ -4653,6 +4697,11 @@ class RunTask: original attempt’s ID and an incrementing `attempt_number`. Runs are retried only until they succeed, and the maximum `attempt_number` is the same as the `max_retries` value for the job.""" + clean_rooms_notebook_task: Optional[CleanRoomsNotebookTask] = None + """The task runs a [clean rooms] notebook when the `clean_rooms_notebook_task` field is present. + + [clean rooms]: https://docs.databricks.com/en/clean-rooms/index.html""" + cleanup_duration: Optional[int] = None """The time in milliseconds it took to terminate the cluster and clean up any associated artifacts. The duration of a task run is the sum of the `setup_duration`, `execution_duration`, and the @@ -4820,6 +4869,8 @@ def as_dict(self) -> dict: """Serializes the RunTask into a dictionary suitable for use as a JSON request body.""" body = {} if self.attempt_number is not None: body['attempt_number'] = self.attempt_number + if self.clean_rooms_notebook_task: + body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task.as_dict() if self.cleanup_duration is not None: body['cleanup_duration'] = self.cleanup_duration if self.cluster_instance: body['cluster_instance'] = self.cluster_instance.as_dict() if self.condition_task: body['condition_task'] = self.condition_task.as_dict() @@ -4864,6 +4915,7 @@ def as_shallow_dict(self) -> dict: """Serializes the RunTask into a shallow dictionary of its immediate attributes.""" body = {} if self.attempt_number is not None: body['attempt_number'] = self.attempt_number + if self.clean_rooms_notebook_task: body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task if self.cleanup_duration is not None: body['cleanup_duration'] = self.cleanup_duration if self.cluster_instance: body['cluster_instance'] = self.cluster_instance if self.condition_task: body['condition_task'] = self.condition_task @@ -4908,6 +4960,8 @@ def as_shallow_dict(self) -> dict: def from_dict(cls, d: Dict[str, any]) -> RunTask: """Deserializes the RunTask from a dictionary.""" return cls(attempt_number=d.get('attempt_number', None), + clean_rooms_notebook_task=_from_dict(d, 'clean_rooms_notebook_task', + CleanRoomsNotebookTask), cleanup_duration=d.get('cleanup_duration', None), cluster_instance=_from_dict(d, 'cluster_instance', ClusterInstance), condition_task=_from_dict(d, 'condition_task', RunConditionTask), @@ -5753,6 +5807,11 @@ class SubmitTask: field is required and must be unique within its parent job. On Update or Reset, this field is used to reference the tasks to be updated or reset.""" + clean_rooms_notebook_task: Optional[CleanRoomsNotebookTask] = None + """The task runs a [clean rooms] notebook when the `clean_rooms_notebook_task` field is present. + + [clean rooms]: https://docs.databricks.com/en/clean-rooms/index.html""" + condition_task: Optional[ConditionTask] = None """The task evaluates a condition that can be used to control the execution of other tasks when the `condition_task` field is present. The condition task does not require a cluster to execute and @@ -5857,6 +5916,8 @@ class SubmitTask: def as_dict(self) -> dict: """Serializes the SubmitTask into a dictionary suitable for use as a JSON request body.""" body = {} + if self.clean_rooms_notebook_task: + body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task.as_dict() if self.condition_task: body['condition_task'] = self.condition_task.as_dict() if self.dbt_task: body['dbt_task'] = self.dbt_task.as_dict() if self.depends_on: body['depends_on'] = [v.as_dict() for v in self.depends_on] @@ -5886,6 +5947,7 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the SubmitTask into a shallow dictionary of its immediate attributes.""" body = {} + if self.clean_rooms_notebook_task: body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task if self.condition_task: body['condition_task'] = self.condition_task if self.dbt_task: body['dbt_task'] = self.dbt_task if self.depends_on: body['depends_on'] = self.depends_on @@ -5915,7 +5977,9 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, any]) -> SubmitTask: """Deserializes the SubmitTask from a dictionary.""" - return cls(condition_task=_from_dict(d, 'condition_task', ConditionTask), + return cls(clean_rooms_notebook_task=_from_dict(d, 'clean_rooms_notebook_task', + CleanRoomsNotebookTask), + condition_task=_from_dict(d, 'condition_task', ConditionTask), dbt_task=_from_dict(d, 'dbt_task', DbtTask), depends_on=_repeated_dict(d, 'depends_on', TaskDependency), description=d.get('description', None), @@ -5997,6 +6061,11 @@ class Task: field is required and must be unique within its parent job. On Update or Reset, this field is used to reference the tasks to be updated or reset.""" + clean_rooms_notebook_task: Optional[CleanRoomsNotebookTask] = None + """The task runs a [clean rooms] notebook when the `clean_rooms_notebook_task` field is present. + + [clean rooms]: https://docs.databricks.com/en/clean-rooms/index.html""" + condition_task: Optional[ConditionTask] = None """The task evaluates a condition that can be used to control the execution of other tasks when the `condition_task` field is present. The condition task does not require a cluster to execute and @@ -6126,6 +6195,8 @@ class Task: def as_dict(self) -> dict: """Serializes the Task into a dictionary suitable for use as a JSON request body.""" body = {} + if self.clean_rooms_notebook_task: + body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task.as_dict() if self.condition_task: body['condition_task'] = self.condition_task.as_dict() if self.dbt_task: body['dbt_task'] = self.dbt_task.as_dict() if self.depends_on: body['depends_on'] = [v.as_dict() for v in self.depends_on] @@ -6162,6 +6233,7 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the Task into a shallow dictionary of its immediate attributes.""" body = {} + if self.clean_rooms_notebook_task: body['clean_rooms_notebook_task'] = self.clean_rooms_notebook_task if self.condition_task: body['condition_task'] = self.condition_task if self.dbt_task: body['dbt_task'] = self.dbt_task if self.depends_on: body['depends_on'] = self.depends_on @@ -6198,7 +6270,9 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, any]) -> Task: """Deserializes the Task from a dictionary.""" - return cls(condition_task=_from_dict(d, 'condition_task', ConditionTask), + return cls(clean_rooms_notebook_task=_from_dict(d, 'clean_rooms_notebook_task', + CleanRoomsNotebookTask), + condition_task=_from_dict(d, 'condition_task', ConditionTask), dbt_task=_from_dict(d, 'dbt_task', DbtTask), depends_on=_repeated_dict(d, 'depends_on', TaskDependency), description=d.get('description', None), @@ -6610,7 +6684,8 @@ class TriggerType(Enum): previously failed run. This occurs when you request to re-run the job in case of failures. * `RUN_JOB_TASK`: Indicates a run that is triggered using a Run Job task. * `FILE_ARRIVAL`: Indicates a run that is triggered by a file arrival. * `TABLE`: Indicates a run that is - triggered by a table update.""" + triggered by a table update. * `CONTINUOUS_RESTART`: Indicates a run created by user to manually + restart a continuous job run.""" FILE_ARRIVAL = 'FILE_ARRIVAL' ONE_TIME = 'ONE_TIME' diff --git a/databricks/sdk/service/oauth2.py b/databricks/sdk/service/oauth2.py index 11a83b3ab..f7df5a25e 100755 --- a/databricks/sdk/service/oauth2.py +++ b/databricks/sdk/service/oauth2.py @@ -288,6 +288,60 @@ def from_dict(cls, d: Dict[str, any]) -> DeleteResponse: return cls() +@dataclass +class FederationPolicy: + create_time: Optional[str] = None + """Creation time of the federation policy.""" + + description: Optional[str] = None + """Description of the federation policy.""" + + name: Optional[str] = None + """Name of the federation policy. The name must contain only lowercase alphanumeric characters, + numbers, and hyphens. It must be unique within the account.""" + + oidc_policy: Optional[OidcFederationPolicy] = None + """Specifies the policy to use for validating OIDC claims in your federated tokens.""" + + uid: Optional[str] = None + """Unique, immutable id of the federation policy.""" + + update_time: Optional[str] = None + """Last update time of the federation policy.""" + + def as_dict(self) -> dict: + """Serializes the FederationPolicy into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.create_time is not None: body['create_time'] = self.create_time + if self.description is not None: body['description'] = self.description + if self.name is not None: body['name'] = self.name + if self.oidc_policy: body['oidc_policy'] = self.oidc_policy.as_dict() + if self.uid is not None: body['uid'] = self.uid + if self.update_time is not None: body['update_time'] = self.update_time + return body + + def as_shallow_dict(self) -> dict: + """Serializes the FederationPolicy into a shallow dictionary of its immediate attributes.""" + body = {} + if self.create_time is not None: body['create_time'] = self.create_time + if self.description is not None: body['description'] = self.description + if self.name is not None: body['name'] = self.name + if self.oidc_policy: body['oidc_policy'] = self.oidc_policy + if self.uid is not None: body['uid'] = self.uid + if self.update_time is not None: body['update_time'] = self.update_time + return body + + @classmethod + def from_dict(cls, d: Dict[str, any]) -> FederationPolicy: + """Deserializes the FederationPolicy from a dictionary.""" + return cls(create_time=d.get('create_time', None), + description=d.get('description', None), + name=d.get('name', None), + oidc_policy=_from_dict(d, 'oidc_policy', OidcFederationPolicy), + uid=d.get('uid', None), + update_time=d.get('update_time', None)) + + @dataclass class GetCustomAppIntegrationOutput: client_id: Optional[str] = None @@ -498,6 +552,33 @@ def from_dict(cls, d: Dict[str, any]) -> GetPublishedAppsOutput: next_page_token=d.get('next_page_token', None)) +@dataclass +class ListFederationPoliciesResponse: + next_page_token: Optional[str] = None + + policies: Optional[List[FederationPolicy]] = None + + def as_dict(self) -> dict: + """Serializes the ListFederationPoliciesResponse 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.policies: body['policies'] = [v.as_dict() for v in self.policies] + return body + + def as_shallow_dict(self) -> dict: + """Serializes the ListFederationPoliciesResponse 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.policies: body['policies'] = self.policies + return body + + @classmethod + def from_dict(cls, d: Dict[str, any]) -> ListFederationPoliciesResponse: + """Deserializes the ListFederationPoliciesResponse from a dictionary.""" + return cls(next_page_token=d.get('next_page_token', None), + policies=_repeated_dict(d, 'policies', FederationPolicy)) + + @dataclass class ListServicePrincipalSecretsResponse: next_page_token: Optional[str] = None @@ -527,6 +608,64 @@ def from_dict(cls, d: Dict[str, any]) -> ListServicePrincipalSecretsResponse: secrets=_repeated_dict(d, 'secrets', SecretInfo)) +@dataclass +class OidcFederationPolicy: + """Specifies the policy to use for validating OIDC claims in your federated tokens.""" + + audiences: Optional[List[str]] = None + """The allowed token audiences, as specified in the 'aud' claim of federated tokens. The audience + identifier is intended to represent the recipient of the token. Can be any non-empty string + value. As long as the audience in the token matches at least one audience in the policy, the + token is considered a match. If audiences is unspecified, defaults to your Databricks account + id.""" + + issuer: Optional[str] = None + """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.""" + + subject: Optional[str] = None + """The required token subject, as specified in the subject claim of federated tokens. Must be + specified for service principal federation policies. Must not be specified for account + federation policies.""" + + subject_claim: Optional[str] = None + """The claim that contains the subject of the token. If unspecified, the default value is 'sub'.""" + + def as_dict(self) -> dict: + """Serializes the OidcFederationPolicy into a dictionary suitable for use as a JSON request body.""" + body = {} + if self.audiences: body['audiences'] = [v for v in self.audiences] + if self.issuer is not None: body['issuer'] = self.issuer + if self.jwks_json is not None: body['jwks_json'] = self.jwks_json + if self.subject is not None: body['subject'] = self.subject + if self.subject_claim is not None: body['subject_claim'] = self.subject_claim + return body + + def as_shallow_dict(self) -> dict: + """Serializes the OidcFederationPolicy into a shallow dictionary of its immediate attributes.""" + body = {} + if self.audiences: body['audiences'] = self.audiences + if self.issuer is not None: body['issuer'] = self.issuer + if self.jwks_json is not None: body['jwks_json'] = self.jwks_json + if self.subject is not None: body['subject'] = self.subject + if self.subject_claim is not None: body['subject_claim'] = self.subject_claim + return body + + @classmethod + def from_dict(cls, d: Dict[str, any]) -> OidcFederationPolicy: + """Deserializes the OidcFederationPolicy from a dictionary.""" + return cls(audiences=d.get('audiences', None), + issuer=d.get('issuer', None), + jwks_json=d.get('jwks_json', None), + subject=d.get('subject', None), + subject_claim=d.get('subject_claim', None)) + + @dataclass class PublishedAppOutput: app_id: Optional[str] = None @@ -769,6 +908,158 @@ def from_dict(cls, d: Dict[str, any]) -> UpdatePublishedAppIntegrationOutput: return cls() +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 + represent the recipient of the token. As long as the audience in the token matches at least one audience + in the policy, the token is considered a match. If unspecified, the default value is your Databricks + account id. * The __subject claim__, which indicates which token claim contains the Databricks username of + the user the token was issued for. If unspecified, the default value is “sub”. * Optionally, the + 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""" + + def __init__(self, api_client): + self._api = api_client + + def create(self, + *, + policy: Optional[FederationPolicy] = None, + policy_id: Optional[str] = None) -> FederationPolicy: + """Create account federation policy. + + :param policy: :class:`FederationPolicy` (optional) + :param policy_id: str (optional) + The identifier for the federation policy. If unspecified, the id will be assigned by Databricks. + + :returns: :class:`FederationPolicy` + """ + body = policy.as_dict() + headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } + + res = self._api.do('POST', + f'/api/2.0/accounts/{self._api.account_id}/federationPolicies', + query=query, + body=body, + headers=headers) + return FederationPolicy.from_dict(res) + + def delete(self, policy_id: str): + """Delete account federation policy. + + :param policy_id: str + + + """ + + headers = {'Accept': 'application/json', } + + self._api.do('DELETE', + f'/api/2.0/accounts/{self._api.account_id}/federationPolicies/{policy_id}', + headers=headers) + + def get(self, policy_id: str) -> FederationPolicy: + """Get account federation policy. + + :param policy_id: str + + :returns: :class:`FederationPolicy` + """ + + headers = {'Accept': 'application/json', } + + res = self._api.do('GET', + f'/api/2.0/accounts/{self._api.account_id}/federationPolicies/{policy_id}', + headers=headers) + return FederationPolicy.from_dict(res) + + def list(self, + *, + page_size: Optional[int] = None, + page_token: Optional[str] = None) -> Iterator[FederationPolicy]: + """List account federation policies. + + :param page_size: int (optional) + :param page_token: str (optional) + + :returns: Iterator over :class:`FederationPolicy` + """ + + query = {} + if page_size is not None: query['page_size'] = page_size + if page_token is not None: query['page_token'] = page_token + headers = {'Accept': 'application/json', } + + while True: + json = self._api.do('GET', + f'/api/2.0/accounts/{self._api.account_id}/federationPolicies', + query=query, + headers=headers) + if 'policies' in json: + for v in json['policies']: + yield FederationPolicy.from_dict(v) + if 'next_page_token' not in json or not json['next_page_token']: + return + query['page_token'] = json['next_page_token'] + + def update(self, + policy_id: str, + update_mask: str, + *, + policy: Optional[FederationPolicy] = None) -> FederationPolicy: + """Update account federation policy. + + :param policy_id: str + :param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + :param policy: :class:`FederationPolicy` (optional) + + :returns: :class:`FederationPolicy` + """ + body = policy.as_dict() + headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } + + res = self._api.do('PATCH', + f'/api/2.0/accounts/{self._api.account_id}/federationPolicies/{policy_id}', + query=query, + body=body, + headers=headers) + return FederationPolicy.from_dict(res) + + class CustomAppIntegrationAPI: """These APIs enable administrators to manage custom OAuth app integrations, which is required for adding/using Custom OAuth App Integration like Tableau Cloud for Databricks in AWS cloud.""" @@ -1086,6 +1377,176 @@ def update(self, integration_id: str, *, token_access_policy: Optional[TokenAcce headers=headers) +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 + workload identity tokens. The subject uniquely identifies the workload in the workload runtime + environment. * The allowed token __audiences__, as specified in the “aud” claim of workload identity + tokens. The audience is intended to represent the recipient of the token. As long as the audience in the + token matches at least one audience in the policy, the token is considered a match. If unspecified, the + default value is your Databricks account id. * Optionally, the public keys used to validate the signature + 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.""" + + def __init__(self, api_client): + self._api = api_client + + def create(self, + service_principal_id: int, + *, + policy: Optional[FederationPolicy] = None, + policy_id: Optional[str] = None) -> 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. If unspecified, the id will be assigned by Databricks. + + :returns: :class:`FederationPolicy` + """ + body = policy.as_dict() + 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}/federationPolicies', + query=query, + body=body, + headers=headers) + return FederationPolicy.from_dict(res) + + def delete(self, 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 + + + """ + + headers = {'Accept': 'application/json', } + + self._api.do( + 'DELETE', + f'/api/2.0/accounts/{self._api.account_id}/servicePrincipals/{service_principal_id}/federationPolicies/{policy_id}', + headers=headers) + + def get(self, 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 + + :returns: :class:`FederationPolicy` + """ + + headers = {'Accept': 'application/json', } + + res = self._api.do( + 'GET', + f'/api/2.0/accounts/{self._api.account_id}/servicePrincipals/{service_principal_id}/federationPolicies/{policy_id}', + headers=headers) + return FederationPolicy.from_dict(res) + + def list(self, + service_principal_id: int, + *, + page_size: Optional[int] = None, + page_token: Optional[str] = None) -> 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` + """ + + query = {} + if page_size is not None: query['page_size'] = page_size + if page_token is not None: query['page_token'] = page_token + headers = {'Accept': 'application/json', } + + while True: + json = self._api.do( + 'GET', + f'/api/2.0/accounts/{self._api.account_id}/servicePrincipals/{service_principal_id}/federationPolicies', + query=query, + headers=headers) + if 'policies' in json: + for v in json['policies']: + yield FederationPolicy.from_dict(v) + if 'next_page_token' not in json or not json['next_page_token']: + return + query['page_token'] = json['next_page_token'] + + def update(self, + service_principal_id: int, + policy_id: str, + update_mask: str, + *, + policy: Optional[FederationPolicy] = None) -> FederationPolicy: + """Update service principal federation policy. + + :param service_principal_id: int + The service principal id for the federation policy. + :param policy_id: str + :param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + :param policy: :class:`FederationPolicy` (optional) + + :returns: :class:`FederationPolicy` + """ + body = policy.as_dict() + headers = {'Accept': 'application/json', 'Content-Type': 'application/json', } + + res = self._api.do( + 'PATCH', + f'/api/2.0/accounts/{self._api.account_id}/servicePrincipals/{service_principal_id}/federationPolicies/{policy_id}', + query=query, + body=body, + headers=headers) + return FederationPolicy.from_dict(res) + + class ServicePrincipalSecretsAPI: """These APIs enable administrators to manage service principal secrets. diff --git a/databricks/sdk/service/pipelines.py b/databricks/sdk/service/pipelines.py index 0ded4a83b..8f8b015c5 100755 --- a/databricks/sdk/service/pipelines.py +++ b/databricks/sdk/service/pipelines.py @@ -11,7 +11,7 @@ from typing import Callable, Dict, Iterator, List, Optional from ..errors import OperationFailed -from ._internal import Wait, _enum, _from_dict, _repeated_dict +from ._internal import Wait, _enum, _from_dict, _repeated_dict, _repeated_enum _LOG = logging.getLogger('databricks.sdk') @@ -2105,7 +2105,7 @@ class RestartWindow: """An integer between 0 and 23 denoting the start hour for the restart window in the 24-hour day. Continuous pipeline restart is triggered only within a five-hour window starting at this hour.""" - days_of_week: Optional[RestartWindowDaysOfWeek] = None + days_of_week: Optional[List[RestartWindowDaysOfWeek]] = None """Days of week in which the restart is allowed to happen (within a five-hour window starting at start_hour). If not specified all days of the week will be used.""" @@ -2117,7 +2117,7 @@ class RestartWindow: def as_dict(self) -> dict: """Serializes the RestartWindow into a dictionary suitable for use as a JSON request body.""" body = {} - if self.days_of_week is not None: body['days_of_week'] = self.days_of_week.value + if self.days_of_week: body['days_of_week'] = [v.value for v in self.days_of_week] if self.start_hour is not None: body['start_hour'] = self.start_hour if self.time_zone_id is not None: body['time_zone_id'] = self.time_zone_id return body @@ -2125,7 +2125,7 @@ def as_dict(self) -> dict: def as_shallow_dict(self) -> dict: """Serializes the RestartWindow into a shallow dictionary of its immediate attributes.""" body = {} - if self.days_of_week is not None: body['days_of_week'] = self.days_of_week + if self.days_of_week: body['days_of_week'] = self.days_of_week if self.start_hour is not None: body['start_hour'] = self.start_hour if self.time_zone_id is not None: body['time_zone_id'] = self.time_zone_id return body @@ -2133,7 +2133,7 @@ def as_shallow_dict(self) -> dict: @classmethod def from_dict(cls, d: Dict[str, any]) -> RestartWindow: """Deserializes the RestartWindow from a dictionary.""" - return cls(days_of_week=_enum(d, 'days_of_week', RestartWindowDaysOfWeek), + return cls(days_of_week=_repeated_enum(d, 'days_of_week', RestartWindowDaysOfWeek), start_hour=d.get('start_hour', None), time_zone_id=d.get('time_zone_id', None)) diff --git a/databricks/sdk/version.py b/databricks/sdk/version.py index 31a9ee722..eb9b6f12e 100644 --- a/databricks/sdk/version.py +++ b/databricks/sdk/version.py @@ -1 +1 @@ -__version__ = '0.39.0' +__version__ = '0.40.0' diff --git a/docs/account/billing/billable_usage.rst b/docs/account/billing/billable_usage.rst index 181b91cc3..95a584e56 100644 --- a/docs/account/billing/billable_usage.rst +++ b/docs/account/billing/billable_usage.rst @@ -5,7 +5,7 @@ .. py:class:: BillableUsageAPI This API allows you to download billable usage logs for the specified account and date range. This feature - works with all account types. +works with all account types. .. py:method:: download(start_month: str, end_month: str [, personal_data: Optional[bool]]) -> DownloadResponse @@ -21,24 +21,23 @@ 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 - Format: `YYYY-MM`. Last month to return billable usage logs for. This field is required. - :param personal_data: bool (optional) - 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 + +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 + Format: `YYYY-MM`. Last month to return billable usage logs for. This field is required. +:param personal_data: bool (optional) + 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` diff --git a/docs/account/billing/budgets.rst b/docs/account/billing/budgets.rst index 43c77d00b..9acd2288a 100644 --- a/docs/account/billing/budgets.rst +++ b/docs/account/billing/budgets.rst @@ -5,8 +5,8 @@ .. py:class:: BudgetsAPI These APIs manage budget configurations for this account. Budgets enable you to monitor usage across your - account. You can set up budgets to either track account-wide spending, or apply filters to track the - spending of specific teams, projects, or workspaces. +account. You can set up budgets to either track account-wide spending, or apply filters to track the +spending of specific teams, projects, or workspaces. .. py:method:: create(budget: CreateBudgetConfigurationBudget) -> CreateBudgetConfigurationResponse @@ -47,28 +47,28 @@ 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` - + +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. - - - + +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 @@ -111,14 +111,14 @@ 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` - + +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` + .. py:method:: list( [, page_token: Optional[str]]) -> Iterator[BudgetConfiguration] @@ -135,15 +135,15 @@ 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` - + +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` + .. py:method:: update(budget_id: str, budget: UpdateBudgetConfigurationBudget) -> UpdateBudgetConfigurationResponse @@ -205,14 +205,13 @@ 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 + +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` diff --git a/docs/account/billing/log_delivery.rst b/docs/account/billing/log_delivery.rst index 04ef4e349..e8143a711 100644 --- a/docs/account/billing/log_delivery.rst +++ b/docs/account/billing/log_delivery.rst @@ -5,51 +5,51 @@ .. py:class:: LogDeliveryAPI 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 - full details, including the required IAM role policies and trust relationship, see [Billable usage log - delivery]. Using Databricks APIs, call the Account API to create a [credential configuration - object](:method:Credentials/Create) that uses the IAM role"s ARN. 3. **Create log delivery - configuration**: Using Databricks APIs, call the Account API to [create a log delivery - configuration](:method:LogDelivery/Create) that uses the credential and storage configuration objects from - previous steps. You can specify if the logs should include all events of that log type in your account - (_Account level_ delivery) or only events for a specific set of workspaces (_workspace level_ delivery). - 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 - prefix you set up during log delivery configuration. Files are named - `workspaceId=-usageMonth=.csv`. * All billable usage logs apply to specific - 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`. - Files may get overwritten with the same content multiple times to achieve exactly-once delivery. * If the - audit log delivery configuration included specific workspace IDs, only _workspace-level_ audit logs for - those workspaces are delivered. If the log delivery configuration applies to the entire account (_account - 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 - [create a new AWS S3 bucket]: https://docs.databricks.com/administration-guide/account-api/aws-storage.html +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 +full details, including the required IAM role policies and trust relationship, see [Billable usage log +delivery]. Using Databricks APIs, call the Account API to create a [credential configuration +object](:method:Credentials/Create) that uses the IAM role"s ARN. 3. **Create log delivery +configuration**: Using Databricks APIs, call the Account API to [create a log delivery +configuration](:method:LogDelivery/Create) that uses the credential and storage configuration objects from +previous steps. You can specify if the logs should include all events of that log type in your account +(_Account level_ delivery) or only events for a specific set of workspaces (_workspace level_ delivery). +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 +prefix you set up during log delivery configuration. Files are named +`workspaceId=-usageMonth=.csv`. * All billable usage logs apply to specific +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`. +Files may get overwritten with the same content multiple times to achieve exactly-once delivery. * If the +audit log delivery configuration included specific workspace IDs, only _workspace-level_ audit logs for +those workspaces are delivered. If the log delivery configuration applies to the entire account (_account +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 +[create a new AWS S3 bucket]: https://docs.databricks.com/administration-guide/account-api/aws-storage.html .. py:method:: create( [, log_delivery_configuration: Optional[CreateLogDeliveryConfigurationParams]]) -> WrappedLogDeliveryConfiguration @@ -88,32 +88,32 @@ 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` - + +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` + .. py:method:: get(log_delivery_configuration_id: str) -> WrappedLogDeliveryConfiguration @@ -154,14 +154,14 @@ 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` - + +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` + .. py:method:: list( [, credentials_id: Optional[str], status: Optional[LogDeliveryConfigStatus], storage_configuration_id: Optional[str]]) -> Iterator[LogDeliveryConfiguration] @@ -178,35 +178,34 @@ 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` - + +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` - Status of log delivery configuration. Set to `ENABLED` (enabled) or `DISABLED` (disabled). Defaults - 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 + +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` + Status of log delivery configuration. Set to `ENABLED` (enabled) or `DISABLED` (disabled). Defaults + 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. + + diff --git a/docs/account/billing/usage_dashboards.rst b/docs/account/billing/usage_dashboards.rst index 350ef1f08..44a1c35eb 100644 --- a/docs/account/billing/usage_dashboards.rst +++ b/docs/account/billing/usage_dashboards.rst @@ -5,35 +5,34 @@ .. py:class:: UsageDashboardsAPI These APIs manage usage dashboards for this account. Usage dashboards enable you to gain insights into - your usage with pre-built dashboards: visualize breakdowns, analyze tag attributions, and identify cost - drivers. +your usage with pre-built dashboards: visualize breakdowns, analyze tag attributions, and identify cost +drivers. .. 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` - + +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 + +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` diff --git a/docs/account/catalog/metastore_assignments.rst b/docs/account/catalog/metastore_assignments.rst index f5b00c6b3..00ea12a65 100644 --- a/docs/account/catalog/metastore_assignments.rst +++ b/docs/account/catalog/metastore_assignments.rst @@ -9,45 +9,45 @@ .. 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) - - - + +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 - - - + +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` - + +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` + .. py:method:: list(metastore_id: str) -> Iterator[int] @@ -65,27 +65,26 @@ 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 - + +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 + +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) + + diff --git a/docs/account/catalog/metastores.rst b/docs/account/catalog/metastores.rst index 15f39060d..4a7b66ed6 100644 --- a/docs/account/catalog/metastores.rst +++ b/docs/account/catalog/metastores.rst @@ -5,63 +5,62 @@ .. py:class:: AccountMetastoresAPI These APIs manage Unity Catalog metastores for an account. A metastore contains catalogs that can be - associated with workspaces +associated with workspaces .. py:method:: create( [, metastore_info: Optional[CreateMetastore]]) -> AccountsMetastoreInfo Create metastore. - - Creates a Unity Catalog metastore. - - :param metastore_info: :class:`CreateMetastore` (optional) - - :returns: :class:`AccountsMetastoreInfo` - + +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. - - - + +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` - + +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` - + +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 + +Updates an existing Unity Catalog metastore. + +:param metastore_id: str + Unity Catalog metastore ID +:param metastore_info: :class:`UpdateMetastore` (optional) + +:returns: :class:`AccountsMetastoreInfo` diff --git a/docs/account/catalog/storage_credentials.rst b/docs/account/catalog/storage_credentials.rst index 453b3a1eb..65271efcf 100644 --- a/docs/account/catalog/storage_credentials.rst +++ b/docs/account/catalog/storage_credentials.rst @@ -9,78 +9,77 @@ .. 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` - + +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. - - - + +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` - + +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` - + +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 + +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` diff --git a/docs/account/iam/access_control.rst b/docs/account/iam/access_control.rst index 2537e262c..80ab61361 100644 --- a/docs/account/iam/access_control.rst +++ b/docs/account/iam/access_control.rst @@ -5,52 +5,51 @@ .. py:class:: AccountAccessControlAPI These APIs manage access rules on resources in an account. Currently, only grant rules are supported. A - grant rule specifies a role assigned to a set of principals. A list of rules attached to a resource is - called a rule set. +grant rule specifies a role assigned to a set of principals. A list of rules attached to a resource is +called a rule set. .. 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` - + +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 - Etag used for versioning. The response is at least as fresh as the eTag provided. Etag is used for - optimistic concurrency control as a way to help prevent simultaneous updates of a rule set from - overwriting each other. It is strongly suggested that systems make use of the etag in the read -> - 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` - + +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 + Etag used for versioning. The response is at least as fresh as the eTag provided. Etag is used for + optimistic concurrency control as a way to help prevent simultaneous updates of a rule set from + overwriting each other. It is strongly suggested that systems make use of the etag in the read -> + 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 + +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` diff --git a/docs/account/iam/groups.rst b/docs/account/iam/groups.rst index a9a4afeac..e7c243fe5 100644 --- a/docs/account/iam/groups.rst +++ b/docs/account/iam/groups.rst @@ -5,132 +5,131 @@ .. py:class:: AccountGroupsAPI 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. +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. .. 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) - :param id: str (optional) - Databricks group ID - :param members: List[:class:`ComplexValue`] (optional) - :param meta: :class:`ResourceMeta` (optional) - Container for the group identifier. Workspace local versus account. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`GroupSchema`] (optional) - The schema of the group. - - :returns: :class:`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) +:param id: str (optional) + Databricks group ID +:param members: List[:class:`ComplexValue`] (optional) +:param meta: :class:`ResourceMeta` (optional) + Container for the group identifier. Workspace local versus account. +:param roles: List[:class:`ComplexValue`] (optional) + 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. - - - + +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` - + +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) - Desired number of results per page. Default is 10000. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. Default is 10000. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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. +:param sort_order: :class:`ListSortOrder` (optional) + 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"]. - - - + +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) - 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) - :param members: List[:class:`ComplexValue`] (optional) - :param meta: :class:`ResourceMeta` (optional) - Container for the group identifier. Workspace local versus account. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`GroupSchema`] (optional) - The schema of the group. - - - \ No newline at end of file + +Updates the details of a group by replacing the entire group entity. + +:param id: str + Databricks group ID +: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) +:param members: List[:class:`ComplexValue`] (optional) +:param meta: :class:`ResourceMeta` (optional) + Container for the group identifier. Workspace local versus account. +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`GroupSchema`] (optional) + The schema of the group. + + diff --git a/docs/account/iam/service_principals.rst b/docs/account/iam/service_principals.rst index 0631386a1..0f2f5b156 100644 --- a/docs/account/iam/service_principals.rst +++ b/docs/account/iam/service_principals.rst @@ -5,10 +5,10 @@ .. py:class:: AccountServicePrincipalsAPI Identities for use with jobs, automated tools, and systems such as scripts, apps, and CI/CD platforms. - Databricks recommends creating service principals to run production jobs or modify production data. If all - processes that act on production data run with service principals, interactive users do not need any - write, delete, or modify privileges in production. This eliminates the risk of a user overwriting - production data by accident. +Databricks recommends creating service principals to run production jobs or modify production data. If all +processes that act on production data run with service principals, interactive users do not need any +write, delete, or modify privileges in production. This eliminates the risk of a user overwriting +production data by accident. .. py:method:: create( [, active: Optional[bool], application_id: Optional[str], display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], roles: Optional[List[ComplexValue]], schemas: Optional[List[ServicePrincipalSchema]]]) -> ServicePrincipal @@ -29,43 +29,43 @@ 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) - UUID relating to the service principal - :param display_name: str (optional) - String that represents a concatenation of given and family names. - :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) - :param id: str (optional) - Databricks service principal ID. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`ServicePrincipalSchema`] (optional) - The schema of the List response. - - :returns: :class:`ServicePrincipal` - + +Creates a new service principal in the Databricks account. + +:param active: bool (optional) + If this user is active +:param application_id: str (optional) + UUID relating to the service principal +:param display_name: str (optional) + String that represents a concatenation of given and family names. +: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) +:param id: str (optional) + Databricks service principal ID. +:param roles: List[:class:`ComplexValue`] (optional) + 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. - - - + +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 @@ -88,14 +88,14 @@ 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` - + +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` + .. 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[ServicePrincipal] @@ -120,31 +120,31 @@ 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) - Desired number of results per page. Default is 10000. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. Default is 10000. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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. +:param sort_order: :class:`ListSortOrder` (optional) + 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` + .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]]) @@ -172,17 +172,17 @@ 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"]. - - - + +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]]]) @@ -207,30 +207,29 @@ 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) - If this user is active - :param application_id: str (optional) - UUID relating to the service principal - :param display_name: str (optional) - String that represents a concatenation of given and family names. - :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) - :param roles: List[:class:`ComplexValue`] (optional) - 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 + +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) + If this user is active +:param application_id: str (optional) + UUID relating to the service principal +:param display_name: str (optional) + String that represents a concatenation of given and family names. +: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) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`ServicePrincipalSchema`] (optional) + The schema of the List response. + + diff --git a/docs/account/iam/users.rst b/docs/account/iam/users.rst index 4b8b5bb08..77c96d67c 100644 --- a/docs/account/iam/users.rst +++ b/docs/account/iam/users.rst @@ -5,14 +5,14 @@ .. 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 - access. When a user leaves your organization or no longer needs access to Databricks account, admins can - terminate the user in your identity provider and that user’s account will also be removed from - Databricks account. This ensures a consistent offboarding process and prevents unauthorized users from - accessing sensitive data. + +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 +access. When a user leaves your organization or no longer needs access to Databricks account, admins can +terminate the user in your identity provider and that user’s account will also be removed from +Databricks account. This ensures a consistent offboarding process and prevents unauthorized users from +accessing sensitive data. .. py:method:: create( [, active: Optional[bool], display_name: Optional[str], emails: Optional[List[ComplexValue]], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], name: Optional[Name], roles: Optional[List[ComplexValue]], schemas: Optional[List[UserSchema]], user_name: Optional[str]]) -> User @@ -33,40 +33,40 @@ 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. - :param groups: List[:class:`ComplexValue`] (optional) - :param id: str (optional) - Databricks user ID. This is automatically set by Databricks. Any value provided by the client will - be ignored. - :param name: :class:`Name` (optional) - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`UserSchema`] (optional) - The schema of the user. - :param user_name: str (optional) - Email address of the Databricks user. - - :returns: :class:`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. +:param groups: List[:class:`ComplexValue`] (optional) +:param id: str (optional) + Databricks user ID. This is automatically set by Databricks. Any value provided by the client will + be ignored. +:param name: :class:`Name` (optional) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`UserSchema`] (optional) + The schema of the user. +:param user_name: str (optional) + Email address of the Databricks user. + +:returns: :class:`User` + .. py:method:: delete(id: str) @@ -86,15 +86,15 @@ 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. - - - + +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 @@ -117,64 +117,64 @@ 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) - Comma-separated list of attributes to return in response. - :param count: int (optional) - Desired number of results per page. Default is 10000. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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`, - `name.givenName`, and `emails`. - :param sort_order: :class:`GetSortOrder` (optional) - 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` - + +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) + Comma-separated list of attributes to return in response. +:param count: int (optional) + Desired number of results per page. Default is 10000. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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`, + `name.givenName`, and `emails`. +:param sort_order: :class:`GetSortOrder` (optional) + 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) - Desired number of results per page. Default is 10000. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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`, - `name.givenName`, and `emails`. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. Default is 10000. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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`, + `name.givenName`, and `emails`. +:param sort_order: :class:`ListSortOrder` (optional) + 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` + .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]]) @@ -203,51 +203,50 @@ 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"]. - - - + +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. - :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. - :param groups: List[:class:`ComplexValue`] (optional) - :param name: :class:`Name` (optional) - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`UserSchema`] (optional) - The schema of the user. - :param user_name: str (optional) - Email address of the Databricks user. - - - \ No newline at end of file + +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. +: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. +:param groups: List[:class:`ComplexValue`] (optional) +:param name: :class:`Name` (optional) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`UserSchema`] (optional) + The schema of the user. +:param user_name: str (optional) + Email address of the Databricks user. + + diff --git a/docs/account/iam/workspace_assignment.rst b/docs/account/iam/workspace_assignment.rst index 697f0a5da..a6e912d93 100644 --- a/docs/account/iam/workspace_assignment.rst +++ b/docs/account/iam/workspace_assignment.rst @@ -5,34 +5,34 @@ .. py:class:: WorkspaceAssignmentAPI The Workspace Permission Assignment API allows you to manage workspace permissions for principals in your - account. +account. .. 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. - - - + +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` - + +Get an array of workspace permissions for the specified account and workspace. + +:param workspace_id: int + The workspace ID. + +:returns: :class:`WorkspacePermissions` + .. py:method:: list(workspace_id: int) -> Iterator[PermissionAssignment] @@ -52,14 +52,14 @@ 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` - + +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` + .. py:method:: update(workspace_id: int, principal_id: int [, permissions: Optional[List[WorkspacePermission]]]) -> PermissionAssignment @@ -87,20 +87,19 @@ 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 - The ID of the user, service principal, or group. - :param permissions: List[:class:`WorkspacePermission`] (optional) - Array of permissions assignments to update on the workspace. Valid values are "USER" and "ADMIN" - (case-sensitive). If both "USER" and "ADMIN" are provided, "ADMIN" takes precedence. Other values - 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 + +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 + The ID of the user, service principal, or group. +:param permissions: List[:class:`WorkspacePermission`] (optional) + Array of permissions assignments to update on the workspace. Valid values are "USER" and "ADMIN" + (case-sensitive). If both "USER" and "ADMIN" are provided, "ADMIN" takes precedence. Other values + 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` diff --git a/docs/account/oauth2/custom_app_integration.rst b/docs/account/oauth2/custom_app_integration.rst index 4192b2109..062dcfdda 100644 --- a/docs/account/oauth2/custom_app_integration.rst +++ b/docs/account/oauth2/custom_app_integration.rst @@ -5,80 +5,79 @@ .. py:class:: CustomAppIntegrationAPI These APIs enable administrators to manage custom OAuth app integrations, which is required for - adding/using Custom OAuth App Integration like Tableau Cloud for Databricks in AWS cloud. +adding/using Custom OAuth App Integration like Tableau Cloud for Databricks in AWS cloud. .. py:method:: create( [, confidential: Optional[bool], name: Optional[str], redirect_urls: Optional[List[str]], scopes: Optional[List[str]], token_access_policy: Optional[TokenAccessPolicy]]) -> 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) - Name of the custom OAuth app - :param redirect_urls: List[str] (optional) - List of OAuth redirect urls - :param scopes: List[str] (optional) - OAuth scopes granted to the application. Supported scopes: all-apis, sql, offline_access, openid, - profile, email. - :param token_access_policy: :class:`TokenAccessPolicy` (optional) - Token access policy - - :returns: :class:`CreateCustomAppIntegrationOutput` - + +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) + Name of the custom OAuth app +:param redirect_urls: List[str] (optional) + List of OAuth redirect urls +:param scopes: List[str] (optional) + OAuth scopes granted to the application. Supported scopes: all-apis, sql, offline_access, openid, + profile, email. +:param token_access_policy: :class:`TokenAccessPolicy` (optional) + Token access policy + +: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 - - - + +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` - + +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` - + +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]], token_access_policy: Optional[TokenAccessPolicy]]) 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 - :param token_access_policy: :class:`TokenAccessPolicy` (optional) - Token access policy to be updated in the custom OAuth app integration - - - \ No newline at end of file + +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 +:param token_access_policy: :class:`TokenAccessPolicy` (optional) + Token access policy to be updated in the custom OAuth app integration + + diff --git a/docs/account/oauth2/federation_policy.rst b/docs/account/oauth2/federation_policy.rst new file mode 100644 index 000000000..31b8ecde6 --- /dev/null +++ b/docs/account/oauth2/federation_policy.rst @@ -0,0 +1,98 @@ +``a.federation_policy``: Account Federation Policies +==================================================== +.. currentmodule:: databricks.sdk.service.oauth2 + +.. 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 +represent the recipient of the token. As long as the audience in the token matches at least one audience +in the policy, the token is considered a match. If unspecified, the default value is your Databricks +account id. * The __subject claim__, which indicates which token claim contains the Databricks username of +the user the token was issued for. If unspecified, the default value is “sub”. * Optionally, the +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. 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 + + + + + .. py:method:: get(policy_id: str) -> FederationPolicy + + Get account federation policy. + +:param policy_id: str + +: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, update_mask: str [, policy: Optional[FederationPolicy]]) -> FederationPolicy + + Update account federation policy. + +:param policy_id: str +:param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). +:param policy: :class:`FederationPolicy` (optional) + +:returns: :class:`FederationPolicy` diff --git a/docs/account/oauth2/index.rst b/docs/account/oauth2/index.rst index a4663ef6b..745a3e721 100644 --- a/docs/account/oauth2/index.rst +++ b/docs/account/oauth2/index.rst @@ -8,6 +8,8 @@ Configure OAuth 2.0 application registrations for Databricks :maxdepth: 1 custom_app_integration + federation_policy o_auth_published_apps published_app_integration + service_principal_federation_policy service_principal_secrets \ 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..e0dc2e303 100644 --- a/docs/account/oauth2/o_auth_published_apps.rst +++ b/docs/account/oauth2/o_auth_published_apps.rst @@ -5,19 +5,18 @@ .. py:class:: OAuthPublishedAppsAPI These APIs enable administrators to view all the available published OAuth applications in Databricks. - Administrators can add the published OAuth applications to their account through the OAuth Published App - Integration APIs. +Administrators can add the published OAuth applications to their account through the OAuth Published App +Integration APIs. .. 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 + +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` diff --git a/docs/account/oauth2/published_app_integration.rst b/docs/account/oauth2/published_app_integration.rst index f59f2c4aa..11135e341 100644 --- a/docs/account/oauth2/published_app_integration.rst +++ b/docs/account/oauth2/published_app_integration.rst @@ -5,69 +5,68 @@ .. py:class:: PublishedAppIntegrationAPI These APIs enable administrators to manage published OAuth app integrations, which is required for - adding/using Published OAuth App Integration like Tableau Desktop for Databricks in AWS cloud. +adding/using Published OAuth App Integration like Tableau Desktop for Databricks in AWS cloud. .. 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` - + +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 - - - + +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` - + +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` - + +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 + +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 + + diff --git a/docs/account/oauth2/service_principal_federation_policy.rst b/docs/account/oauth2/service_principal_federation_policy.rst new file mode 100644 index 000000000..922ec4863 --- /dev/null +++ b/docs/account/oauth2/service_principal_federation_policy.rst @@ -0,0 +1,108 @@ +``a.service_principal_federation_policy``: Service Principal Federation Policies +================================================================================ +.. currentmodule:: databricks.sdk.service.oauth2 + +.. 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 +workload identity tokens. The subject uniquely identifies the workload in the workload runtime +environment. * The allowed token __audiences__, as specified in the “aud” claim of workload identity +tokens. The audience is intended to represent the recipient of the token. As long as the audience in the +token matches at least one audience in the policy, the token is considered a match. If unspecified, the +default value is your Databricks account id. * Optionally, the public keys used to validate the signature +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. 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 + + + + + .. 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 + +: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, update_mask: str [, policy: Optional[FederationPolicy]]) -> FederationPolicy + + Update service principal federation policy. + +:param service_principal_id: int + The service principal id for the federation policy. +:param policy_id: str +:param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). +:param policy: :class:`FederationPolicy` (optional) + +:returns: :class:`FederationPolicy` diff --git a/docs/account/oauth2/service_principal_secrets.rst b/docs/account/oauth2/service_principal_secrets.rst index 955d6da53..3e0bb9b74 100644 --- a/docs/account/oauth2/service_principal_secrets.rst +++ b/docs/account/oauth2/service_principal_secrets.rst @@ -5,59 +5,58 @@ .. 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 + +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 Create service principal secret. - - Create a secret for the given service principal. - - :param service_principal_id: int - The service principal ID. - - :returns: :class:`CreateServicePrincipalSecretResponse` - + +Create a secret for the given service principal. + +:param service_principal_id: int + The service principal ID. + +: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. - - - + +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) - An opaque page token which was the `next_page_token` in the response of the previous request to list - the secrets for this service principal. Provide this token to retrieve the next page of secret - entries. When providing a `page_token`, all other parameters provided to the request must match the - 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 + +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) + An opaque page token which was the `next_page_token` in the response of the previous request to list + the secrets for this service principal. Provide this token to retrieve the next page of secret + entries. When providing a `page_token`, all other parameters provided to the request must match the + 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` diff --git a/docs/account/provisioning/credentials.rst b/docs/account/provisioning/credentials.rst index 5255a6a29..a411febab 100644 --- a/docs/account/provisioning/credentials.rst +++ b/docs/account/provisioning/credentials.rst @@ -5,9 +5,9 @@ .. py:class:: CredentialsAPI These APIs manage credential configurations for this workspace. Databricks needs access to a cross-account - service IAM role in your AWS account so that Databricks can deploy clusters in the appropriate VPC for the - new workspace. A credential configuration encapsulates this role information, and its ID is used when - creating a new workspace. +service IAM role in your AWS account so that Databricks can deploy clusters in the appropriate VPC for the +new workspace. A credential configuration encapsulates this role information, and its ID is used when +creating a new workspace. .. py:method:: create(credentials_name: str, aws_credentials: CreateCredentialAwsCredentials) -> Credential @@ -33,39 +33,39 @@ 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` - + +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 - - - + +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 @@ -93,14 +93,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[Credential] @@ -116,8 +116,7 @@ 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 + +Gets all Databricks credential configurations associated with an account specified by ID. + +:returns: Iterator over :class:`Credential` diff --git a/docs/account/provisioning/encryption_keys.rst b/docs/account/provisioning/encryption_keys.rst index c711727c5..ad26bb033 100644 --- a/docs/account/provisioning/encryption_keys.rst +++ b/docs/account/provisioning/encryption_keys.rst @@ -5,18 +5,18 @@ .. py:class:: EncryptionKeysAPI 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 - have an older workspace, it might not be on the E2 version of the platform. If you are not sure, contact - your Databricks representative. +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 +have an older workspace, it might not be on the E2 version of the platform. If you are not sure, contact +your Databricks representative. .. py:method:: create(use_cases: List[KeyUseCase] [, aws_key_info: Optional[CreateAwsKeyInfo], gcp_key_info: Optional[CreateGcpKeyInfo]]) -> CustomerManagedKey @@ -40,41 +40,41 @@ 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 - and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is - 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` - + +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 +and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is +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. - - - + +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 @@ -100,25 +100,25 @@ 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 - and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is - 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` - + +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 +and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is +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` + .. py:method:: list() -> Iterator[CustomerManagedKey] @@ -134,17 +134,16 @@ 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 + +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` diff --git a/docs/account/provisioning/networks.rst b/docs/account/provisioning/networks.rst index e7491f202..bfe9abfd4 100644 --- a/docs/account/provisioning/networks.rst +++ b/docs/account/provisioning/networks.rst @@ -5,7 +5,7 @@ .. py:class:: NetworksAPI These APIs manage network configurations for customer-managed VPCs (optional). Its ID is used when - creating a new workspace if you use customer-managed VPCs. +creating a new workspace if you use customer-managed VPCs. .. py:method:: create(network_name: str [, gcp_network_info: Optional[GcpNetworkInfo], security_group_ids: Optional[List[str]], subnet_ids: Optional[List[str]], vpc_endpoints: Optional[NetworkVpcEndpoints], vpc_id: Optional[str]]) -> Network @@ -27,47 +27,47 @@ 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) - The Google Cloud specific information for this network (for example, the VPC ID, subnet ID, and - secondary IP ranges). - :param security_group_ids: List[str] (optional) - IDs of one to five security groups associated with this network. Security group IDs **cannot** be - used in multiple network configurations. - :param subnet_ids: List[str] (optional) - IDs of at least two subnets associated with this network. Subnet IDs **cannot** be used in multiple - network configurations. - :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` - + +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) + The Google Cloud specific information for this network (for example, the VPC ID, subnet ID, and + secondary IP ranges). +:param security_group_ids: List[str] (optional) + IDs of one to five security groups associated with this network. Security group IDs **cannot** be + used in multiple network configurations. +:param subnet_ids: List[str] (optional) + IDs of at least two subnets associated with this network. Subnet IDs **cannot** be used in multiple + network configurations. +: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. - - - + +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 @@ -91,14 +91,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[Network] @@ -114,10 +114,9 @@ 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 + +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` diff --git a/docs/account/provisioning/private_access.rst b/docs/account/provisioning/private_access.rst index 10022068e..c51b7567f 100644 --- a/docs/account/provisioning/private_access.rst +++ b/docs/account/provisioning/private_access.rst @@ -27,68 +27,68 @@ 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 - The cloud region for workspaces associated with this private access settings object. - :param allowed_vpc_endpoint_ids: List[str] (optional) - 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 - that attaches this private access settings object. * `ACCOUNT` level access (the default) allows - only VPC endpoints that are registered in your Databricks account connect to your workspace. * - `ENDPOINT` level access allows only specified VPC endpoints connect to your workspace. For details, - see `allowed_vpc_endpoint_ids`. - :param public_access_enabled: bool (optional) - 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` - + +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 + The cloud region for workspaces associated with this private access settings object. +:param allowed_vpc_endpoint_ids: List[str] (optional) + 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 + that attaches this private access settings object. * `ACCOUNT` level access (the default) allows + only VPC endpoints that are registered in your Databricks account connect to your workspace. * + `ENDPOINT` level access allows only specified VPC endpoints connect to your workspace. For details, + see `allowed_vpc_endpoint_ids`. +:param public_access_enabled: bool (optional) + 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. - - - + +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 @@ -113,20 +113,20 @@ 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` - + +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` + .. py:method:: list() -> Iterator[PrivateAccessSettings] @@ -142,11 +142,11 @@ 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` - + +Gets a list of all private access settings objects for an account, specified by ID. + +:returns: Iterator over :class:`PrivateAccessSettings` + .. py:method:: replace(private_access_settings_id: str, private_access_settings_name: str, region: str [, allowed_vpc_endpoint_ids: Optional[List[str]], private_access_level: Optional[PrivateAccessLevel], public_access_enabled: Optional[bool]]) @@ -173,54 +173,53 @@ 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 - The human-readable name of the private access settings object. - :param region: str - The cloud region for workspaces associated with this private access settings object. - :param allowed_vpc_endpoint_ids: List[str] (optional) - 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 - that attaches this private access settings object. * `ACCOUNT` level access (the default) allows - only VPC endpoints that are registered in your Databricks account connect to your workspace. * - `ENDPOINT` level access allows only specified VPC endpoints connect to your workspace. For details, - see `allowed_vpc_endpoint_ids`. - :param public_access_enabled: bool (optional) - 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 + +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 + The human-readable name of the private access settings object. +:param region: str + The cloud region for workspaces associated with this private access settings object. +:param allowed_vpc_endpoint_ids: List[str] (optional) + 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 + that attaches this private access settings object. * `ACCOUNT` level access (the default) allows + only VPC endpoints that are registered in your Databricks account connect to your workspace. * + `ENDPOINT` level access allows only specified VPC endpoints connect to your workspace. For details, + see `allowed_vpc_endpoint_ids`. +:param public_access_enabled: bool (optional) + 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. + + diff --git a/docs/account/provisioning/storage.rst b/docs/account/provisioning/storage.rst index 611a8cdc6..c538ca1d7 100644 --- a/docs/account/provisioning/storage.rst +++ b/docs/account/provisioning/storage.rst @@ -5,9 +5,9 @@ .. py:class:: StorageAPI These APIs manage storage configurations for this workspace. A root storage S3 bucket in your account is - required to store objects like cluster logs, notebook revisions, and job results. You can also use the - root storage S3 bucket for storage of non-production DBFS data. A storage configuration encapsulates this - bucket information, and its ID is used when creating a new workspace. +required to store objects like cluster logs, notebook revisions, and job results. You can also use the +root storage S3 bucket for storage of non-production DBFS data. A storage configuration encapsulates this +bucket information, and its ID is used when creating a new workspace. .. py:method:: create(storage_configuration_name: str, root_bucket_info: RootBucketInfo) -> StorageConfiguration @@ -32,37 +32,37 @@ 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` - + +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. - - - + +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 @@ -84,14 +84,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[StorageConfiguration] @@ -107,8 +107,7 @@ 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 + +Gets a list of all Databricks storage configurations for your account, specified by ID. + +:returns: Iterator over :class:`StorageConfiguration` diff --git a/docs/account/provisioning/vpc_endpoints.rst b/docs/account/provisioning/vpc_endpoints.rst index d2622dc0f..2b9657b5e 100644 --- a/docs/account/provisioning/vpc_endpoints.rst +++ b/docs/account/provisioning/vpc_endpoints.rst @@ -28,50 +28,50 @@ 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) - The ID of the VPC endpoint object in AWS. - :param gcp_vpc_endpoint_info: :class:`GcpVpcEndpointInfo` (optional) - 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` - + +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) + The ID of the VPC endpoint object in AWS. +:param gcp_vpc_endpoint_info: :class:`GcpVpcEndpointInfo` (optional) + 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. - - - + +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 @@ -97,18 +97,18 @@ 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` - + +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` + .. py:method:: list() -> Iterator[VpcEndpoint] @@ -124,12 +124,11 @@ 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 + +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` diff --git a/docs/account/provisioning/workspaces.rst b/docs/account/provisioning/workspaces.rst index ad8a75942..3e312984a 100644 --- a/docs/account/provisioning/workspaces.rst +++ b/docs/account/provisioning/workspaces.rst @@ -5,11 +5,11 @@ .. py:class:: WorkspacesAPI 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. +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. .. py:method:: create(workspace_name: str [, aws_region: Optional[str], cloud: Optional[str], cloud_resource_container: Optional[CloudResourceContainer], credentials_id: Optional[str], custom_tags: Optional[Dict[str, str]], deployment_name: Optional[str], gcp_managed_network_config: Optional[GcpManagedNetworkConfig], gke_config: Optional[GkeConfig], is_no_public_ip_enabled: Optional[bool], location: Optional[str], managed_services_customer_managed_key_id: Optional[str], network_id: Optional[str], pricing_tier: Optional[PricingTier], private_access_settings_id: Optional[str], storage_configuration_id: Optional[str], storage_customer_managed_key_id: Optional[str]]) -> Wait[Workspace] @@ -46,109 +46,109 @@ 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) - The AWS region of the workspace's data plane. - :param cloud: str (optional) - The cloud provider which the workspace uses. For Google Cloud workspaces, always set this field to - `gcp`. - :param cloud_resource_container: :class:`CloudResourceContainer` (optional) - The general workspace configurations that are specific to cloud providers. - :param credentials_id: str (optional) - ID of the workspace's credential configuration object. - :param custom_tags: Dict[str,str] (optional) - The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string - of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The - key can be of maximum length of 127 characters, and cannot be empty. - :param deployment_name: str (optional) - The deployment name defines part of the subdomain for the workspace. The workspace URL for the web - application and REST APIs is `.cloud.databricks.com`. For example, if the - 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) - The network settings for the workspace. The configurations are only for Databricks-managed VPCs. It - 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. - :param is_no_public_ip_enabled: bool (optional) - Whether no public IP is enabled for the workspace. - :param location: str (optional) - The Google Cloud region of the workspace data plane in your Google account. For example, `us-east4`. - :param managed_services_customer_managed_key_id: str (optional) - The ID of the workspace's managed services encryption key configuration object. This is used to help - protect and control access to the workspace's notebooks, secrets, Databricks SQL queries, and query - history. The provided key configuration object property `use_cases` must contain `MANAGED_SERVICES`. - :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) - The ID of the workspace's storage configuration object. - :param storage_customer_managed_key_id: str (optional) - 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. - + +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) + The AWS region of the workspace's data plane. +:param cloud: str (optional) + The cloud provider which the workspace uses. For Google Cloud workspaces, always set this field to + `gcp`. +:param cloud_resource_container: :class:`CloudResourceContainer` (optional) + The general workspace configurations that are specific to cloud providers. +:param credentials_id: str (optional) + ID of the workspace's credential configuration object. +:param custom_tags: Dict[str,str] (optional) + The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string + of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The + key can be of maximum length of 127 characters, and cannot be empty. +:param deployment_name: str (optional) + The deployment name defines part of the subdomain for the workspace. The workspace URL for the web + application and REST APIs is `.cloud.databricks.com`. For example, if the + 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) + The network settings for the workspace. The configurations are only for Databricks-managed VPCs. It + 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. +:param is_no_public_ip_enabled: bool (optional) + Whether no public IP is enabled for the workspace. +:param location: str (optional) + The Google Cloud region of the workspace data plane in your Google account. For example, `us-east4`. +:param managed_services_customer_managed_key_id: str (optional) + The ID of the workspace's managed services encryption key configuration object. This is used to help + protect and control access to the workspace's notebooks, secrets, Databricks SQL queries, and query + history. The provided key configuration object property `use_cases` must contain `MANAGED_SERVICES`. +: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) + The ID of the workspace's storage configuration object. +:param storage_customer_managed_key_id: str (optional) + 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. + .. py:method:: create_and_wait(workspace_name: str [, aws_region: Optional[str], cloud: Optional[str], cloud_resource_container: Optional[CloudResourceContainer], credentials_id: Optional[str], custom_tags: Optional[Dict[str, str]], deployment_name: Optional[str], gcp_managed_network_config: Optional[GcpManagedNetworkConfig], gke_config: Optional[GkeConfig], is_no_public_ip_enabled: Optional[bool], location: Optional[str], managed_services_customer_managed_key_id: Optional[str], network_id: Optional[str], pricing_tier: Optional[PricingTier], private_access_settings_id: Optional[str], storage_configuration_id: Optional[str], storage_customer_managed_key_id: Optional[str], timeout: datetime.timedelta = 0:20:00]) -> Workspace @@ -156,19 +156,19 @@ .. 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. - - - + +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,25 +186,25 @@ 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` - + +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` + .. py:method:: list() -> Iterator[Workspace] @@ -220,14 +220,14 @@ 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` - + +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` + .. py:method:: update(workspace_id: int [, aws_region: Optional[str], credentials_id: Optional[str], custom_tags: Optional[Dict[str, str]], managed_services_customer_managed_key_id: Optional[str], network_connectivity_config_id: Optional[str], network_id: Optional[str], private_access_settings_id: Optional[str], storage_configuration_id: Optional[str], storage_customer_managed_key_id: Optional[str]]) -> Wait[Workspace] @@ -257,135 +257,135 @@ 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 - configuration ID. Used only to add or change a network configuration for a customer-managed VPC. For a - failed workspace only, you can convert a workspace with Databricks-managed VPC to use a - customer-managed VPC by adding this ID. You cannot downgrade a workspace with a customer-managed VPC - to be a Databricks-managed VPC. You can update the network configuration for a failed or running - workspace to add PrivateLink support, though you must also add a private access settings object. - Key - configuration ID for managed services (control plane storage, such as notebook source and Databricks - SQL queries). Used only if you use customer-managed keys for managed services. - Key configuration ID - for workspace storage (root S3 bucket and, optionally, EBS volumes). Used only if you use - customer-managed keys for workspace storage. **Important**: If the workspace was ever in the running - state, even if briefly before becoming a failed workspace, you cannot add a new key configuration ID - for workspace storage. - Private access settings ID to add PrivateLink support. You can add or update - the private access settings ID to upgrade a workspace to add support for front-end, back-end, or both - types of connectivity. You cannot remove (downgrade) any existing front-end or back-end PrivateLink - support on a workspace. - Custom tags. Given you provide an empty custom tags, the update would not be - applied. - Network connectivity configuration ID to add serverless stable IP support. You can add or - 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 - only if you already use a customer-managed VPC. You cannot convert a running workspace from a - Databricks-managed VPC to a customer-managed VPC. You can use a network configuration update in this - API for a failed or running workspace to add support for PrivateLink, although you also need to add a - private access settings object. - Key configuration ID for managed services (control plane storage, - such as notebook source and Databricks SQL queries). Databricks does not directly encrypt the data - with the customer-managed key (CMK). Databricks uses both the CMK and the Databricks managed key (DMK) - that is unique to your workspace to encrypt the Data Encryption Key (DEK). Databricks uses the DEK to - encrypt your workspace's managed services persisted data. If the workspace does not already have a CMK - for managed services, adding this ID enables managed services encryption for new or updated data. - Existing managed services data that existed before adding the key remains not encrypted with the DEK - until it is modified. If the workspace already has customer-managed keys for managed services, this - request rotates (changes) the CMK keys and the DEK is re-encrypted with the DMK and the new CMK. - Key - configuration ID for workspace storage (root S3 bucket and, optionally, EBS volumes). You can set this - only if the workspace does not already have a customer-managed key configuration for workspace - storage. - Private access settings ID to add PrivateLink support. You can add or update the private - access settings ID to upgrade a workspace to add support for front-end, back-end, or both types of - connectivity. You cannot remove (downgrade) any existing front-end or back-end PrivateLink support on - a workspace. - Custom tags. Given you provide an empty custom tags, the update would not be applied. - - Network connectivity configuration ID to add serverless stable IP support. You can add or 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. - - **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 - `PROVISIONING` temporarily (typically under 20 minutes). If the workspace update is successful, the - workspace status changes to `RUNNING`. Note that you can also check the workspace status in the - [Account Console]. However, you cannot use or create clusters for another 20 minutes after that status - change. This results in a total of up to 40 minutes in which you cannot create clusters. If you create - or use clusters before this time interval elapses, clusters do not launch successfully, fail, or could - cause other unexpected behavior. * For workspaces with a customer-managed VPC, the workspace status - stays at status `RUNNING` and the VPC change happens immediately. A change to the storage - customer-managed key configuration ID might take a few minutes to update, so continue to check the - workspace until you observe that it has been updated. If the update fails, the workspace might revert - 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) - The AWS region of the workspace's data plane (for example, `us-west-2`). This parameter is available - only for updating failed workspaces. - :param credentials_id: str (optional) - ID of the workspace's credential configuration object. This parameter is available for updating both - failed and running workspaces. - :param custom_tags: Dict[str,str] (optional) - The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string - of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The - key can be of maximum length of 127 characters, and cannot be empty. - :param managed_services_customer_managed_key_id: str (optional) - The ID of the workspace's managed services encryption key configuration object. This parameter is - available only for updating failed workspaces. - :param network_connectivity_config_id: str (optional) - :param network_id: str (optional) - The ID of the workspace's network configuration object. Used only if you already use a - customer-managed VPC. For failed workspaces only, you can switch from a Databricks-managed VPC to a - customer-managed VPC by updating the workspace to add a network configuration ID. - :param private_access_settings_id: str (optional) - The ID of the workspace's private access settings configuration object. This parameter is available - only for updating failed workspaces. - :param storage_configuration_id: str (optional) - The ID of the workspace's storage configuration object. This parameter is available only for - updating failed workspaces. - :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. - + +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 +configuration ID. Used only to add or change a network configuration for a customer-managed VPC. For a +failed workspace only, you can convert a workspace with Databricks-managed VPC to use a +customer-managed VPC by adding this ID. You cannot downgrade a workspace with a customer-managed VPC +to be a Databricks-managed VPC. You can update the network configuration for a failed or running +workspace to add PrivateLink support, though you must also add a private access settings object. - Key +configuration ID for managed services (control plane storage, such as notebook source and Databricks +SQL queries). Used only if you use customer-managed keys for managed services. - Key configuration ID +for workspace storage (root S3 bucket and, optionally, EBS volumes). Used only if you use +customer-managed keys for workspace storage. **Important**: If the workspace was ever in the running +state, even if briefly before becoming a failed workspace, you cannot add a new key configuration ID +for workspace storage. - Private access settings ID to add PrivateLink support. You can add or update +the private access settings ID to upgrade a workspace to add support for front-end, back-end, or both +types of connectivity. You cannot remove (downgrade) any existing front-end or back-end PrivateLink +support on a workspace. - Custom tags. Given you provide an empty custom tags, the update would not be +applied. - Network connectivity configuration ID to add serverless stable IP support. You can add or +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 +only if you already use a customer-managed VPC. You cannot convert a running workspace from a +Databricks-managed VPC to a customer-managed VPC. You can use a network configuration update in this +API for a failed or running workspace to add support for PrivateLink, although you also need to add a +private access settings object. - Key configuration ID for managed services (control plane storage, +such as notebook source and Databricks SQL queries). Databricks does not directly encrypt the data +with the customer-managed key (CMK). Databricks uses both the CMK and the Databricks managed key (DMK) +that is unique to your workspace to encrypt the Data Encryption Key (DEK). Databricks uses the DEK to +encrypt your workspace's managed services persisted data. If the workspace does not already have a CMK +for managed services, adding this ID enables managed services encryption for new or updated data. +Existing managed services data that existed before adding the key remains not encrypted with the DEK +until it is modified. If the workspace already has customer-managed keys for managed services, this +request rotates (changes) the CMK keys and the DEK is re-encrypted with the DMK and the new CMK. - Key +configuration ID for workspace storage (root S3 bucket and, optionally, EBS volumes). You can set this +only if the workspace does not already have a customer-managed key configuration for workspace +storage. - Private access settings ID to add PrivateLink support. You can add or update the private +access settings ID to upgrade a workspace to add support for front-end, back-end, or both types of +connectivity. You cannot remove (downgrade) any existing front-end or back-end PrivateLink support on +a workspace. - Custom tags. Given you provide an empty custom tags, the update would not be applied. - +Network connectivity configuration ID to add serverless stable IP support. You can add or 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. + +**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 +`PROVISIONING` temporarily (typically under 20 minutes). If the workspace update is successful, the +workspace status changes to `RUNNING`. Note that you can also check the workspace status in the +[Account Console]. However, you cannot use or create clusters for another 20 minutes after that status +change. This results in a total of up to 40 minutes in which you cannot create clusters. If you create +or use clusters before this time interval elapses, clusters do not launch successfully, fail, or could +cause other unexpected behavior. * For workspaces with a customer-managed VPC, the workspace status +stays at status `RUNNING` and the VPC change happens immediately. A change to the storage +customer-managed key configuration ID might take a few minutes to update, so continue to check the +workspace until you observe that it has been updated. If the update fails, the workspace might revert +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) + The AWS region of the workspace's data plane (for example, `us-west-2`). This parameter is available + only for updating failed workspaces. +:param credentials_id: str (optional) + ID of the workspace's credential configuration object. This parameter is available for updating both + failed and running workspaces. +:param custom_tags: Dict[str,str] (optional) + The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string + of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The + key can be of maximum length of 127 characters, and cannot be empty. +:param managed_services_customer_managed_key_id: str (optional) + The ID of the workspace's managed services encryption key configuration object. This parameter is + available only for updating failed workspaces. +:param network_connectivity_config_id: str (optional) +:param network_id: str (optional) + The ID of the workspace's network configuration object. Used only if you already use a + customer-managed VPC. For failed workspaces only, you can switch from a Databricks-managed VPC to a + customer-managed VPC by updating the workspace to add a network configuration ID. +:param private_access_settings_id: str (optional) + The ID of the workspace's private access settings configuration object. This parameter is available + only for updating failed workspaces. +:param storage_configuration_id: str (optional) + The ID of the workspace's storage configuration object. This parameter is available only for + updating failed workspaces. +: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. + .. py:method:: update_and_wait(workspace_id: int [, aws_region: Optional[str], credentials_id: Optional[str], custom_tags: Optional[Dict[str, str]], managed_services_customer_managed_key_id: Optional[str], network_connectivity_config_id: Optional[str], network_id: Optional[str], private_access_settings_id: Optional[str], storage_configuration_id: Optional[str], storage_customer_managed_key_id: Optional[str], timeout: datetime.timedelta = 0:20:00]) -> Workspace diff --git a/docs/account/settings/csp_enablement_account.rst b/docs/account/settings/csp_enablement_account.rst index b6fec691c..da40096a7 100644 --- a/docs/account/settings/csp_enablement_account.rst +++ b/docs/account/settings/csp_enablement_account.rst @@ -5,41 +5,40 @@ .. py:class:: CspEnablementAccountAPI 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. +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`CspEnablementAccountSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`CspEnablementAccountSetting` diff --git a/docs/account/settings/disable_legacy_features.rst b/docs/account/settings/disable_legacy_features.rst index d7f1db9d3..da837ab44 100644 --- a/docs/account/settings/disable_legacy_features.rst +++ b/docs/account/settings/disable_legacy_features.rst @@ -5,56 +5,55 @@ .. 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. + +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. .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`DisableLegacyFeatures` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`DisableLegacyFeatures` diff --git a/docs/account/settings/esm_enablement_account.rst b/docs/account/settings/esm_enablement_account.rst index 59376793b..5f9db5724 100644 --- a/docs/account/settings/esm_enablement_account.rst +++ b/docs/account/settings/esm_enablement_account.rst @@ -5,38 +5,37 @@ .. py:class:: EsmEnablementAccountAPI The enhanced security monitoring setting at the account level controls whether to enable the feature on - new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace - creation, account admins can enable enhanced security monitoring individually for each workspace. +new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace +creation, account admins can enable enhanced security monitoring individually for each workspace. .. 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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`EsmEnablementAccountSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`EsmEnablementAccountSetting` diff --git a/docs/account/settings/ip_access_lists.rst b/docs/account/settings/ip_access_lists.rst index 7718d0c54..b3b2a0aa4 100644 --- a/docs/account/settings/ip_access_lists.rst +++ b/docs/account/settings/ip_access_lists.rst @@ -5,147 +5,146 @@ .. py:class:: AccountIpAccessListsAPI 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. +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` - + +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 - - - + +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` - + +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` - + +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 - CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value - `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) - - - + +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 +CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value +`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) - Specifies whether this IP access list is enabled. - :param ip_addresses: List[str] (optional) - :param label: str (optional) - 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 + +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) + Specifies whether this IP access list is enabled. +:param ip_addresses: List[str] (optional) +:param label: str (optional) + 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. + + diff --git a/docs/account/settings/network_connectivity.rst b/docs/account/settings/network_connectivity.rst index 30b50abcb..d073fc1da 100644 --- a/docs/account/settings/network_connectivity.rst +++ b/docs/account/settings/network_connectivity.rst @@ -5,125 +5,124 @@ .. py:class:: NetworkConnectivityAPI These APIs provide configurations for the network connectivity of your workspaces for serverless compute - resources. +resources. .. 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 - regular expression `^[0-9a-zA-Z-_]{3,30}$`. - :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` - + +: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 + regular expression `^[0-9a-zA-Z-_]{3,30}$`. +: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 - The Azure resource ID of the target resource. - :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` - + +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 + The Azure resource ID of the target resource. +: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. - - - + +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` - + +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` - + +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` - + +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` - + +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 + +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` diff --git a/docs/account/settings/personal_compute.rst b/docs/account/settings/personal_compute.rst index 00ccf3012..2da832478 100644 --- a/docs/account/settings/personal_compute.rst +++ b/docs/account/settings/personal_compute.rst @@ -5,58 +5,57 @@ .. py:class:: PersonalComputeAPI 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. +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. .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`PersonalComputeSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`PersonalComputeSetting` diff --git a/docs/account/settings/settings.rst b/docs/account/settings/settings.rst index 3df647279..faa165f8c 100644 --- a/docs/account/settings/settings.rst +++ b/docs/account/settings/settings.rst @@ -10,35 +10,35 @@ :type: CspEnablementAccountAPI 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. + 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:property:: disable_legacy_features :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. + + 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. .. py:property:: esm_enablement_account :type: EsmEnablementAccountAPI The enhanced security monitoring setting at the account level controls whether to enable the feature on - new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace - creation, account admins can enable enhanced security monitoring individually for each workspace. + new workspaces. By default, this account-level setting is disabled for new workspaces. After workspace + creation, account admins can enable enhanced security monitoring individually for each workspace. .. py:property:: personal_compute :type: PersonalComputeAPI 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 + 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 5b5fbb379..84f3c9867 100644 --- a/docs/dbdataclasses/catalog.rst +++ b/docs/dbdataclasses/catalog.rst @@ -745,12 +745,12 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: CATALOG :value: "CATALOG" + .. py:attribute:: CREDENTIAL + :value: "CREDENTIAL" + .. py:attribute:: EXTERNAL_LOCATION :value: "EXTERNAL_LOCATION" - .. py:attribute:: SERVICE_CREDENTIAL - :value: "SERVICE_CREDENTIAL" - .. py:attribute:: STORAGE_CREDENTIAL :value: "STORAGE_CREDENTIAL" @@ -1460,12 +1460,12 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:attribute:: CATALOG :value: "CATALOG" + .. py:attribute:: CREDENTIAL + :value: "CREDENTIAL" + .. py:attribute:: EXTERNAL_LOCATION :value: "EXTERNAL_LOCATION" - .. py:attribute:: SERVICE_CREDENTIAL - :value: "SERVICE_CREDENTIAL" - .. py:attribute:: STORAGE_CREDENTIAL :value: "STORAGE_CREDENTIAL" diff --git a/docs/dbdataclasses/compute.rst b/docs/dbdataclasses/compute.rst index 0066f0374..9c628c476 100644 --- a/docs/dbdataclasses/compute.rst +++ b/docs/dbdataclasses/compute.rst @@ -316,10 +316,20 @@ 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. - * `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 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 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. + .. py:attribute:: DATA_SECURITY_MODE_AUTO + :value: "DATA_SECURITY_MODE_AUTO" + + .. py:attribute:: DATA_SECURITY_MODE_DEDICATED + :value: "DATA_SECURITY_MODE_DEDICATED" + + .. py:attribute:: DATA_SECURITY_MODE_STANDARD + :value: "DATA_SECURITY_MODE_STANDARD" + .. py:attribute:: LEGACY_PASSTHROUGH :value: "LEGACY_PASSTHROUGH" @@ -782,6 +792,15 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. py:class:: Kind + + 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`. + + .. py:attribute:: CLASSIC_PREVIEW + :value: "CLASSIC_PREVIEW" + .. py:class:: Language .. py:attribute:: PYTHON diff --git a/docs/dbdataclasses/jobs.rst b/docs/dbdataclasses/jobs.rst index 374c48351..cbb4059a1 100644 --- a/docs/dbdataclasses/jobs.rst +++ b/docs/dbdataclasses/jobs.rst @@ -103,6 +103,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: CleanRoomsNotebookTask + :members: + :undoc-members: + .. autoclass:: ClusterInstance :members: :undoc-members: @@ -392,7 +396,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: JobsHealthMetric Specifies the health metric that is being evaluated for a particular health rule. - * `RUN_DURATION_SECONDS`: Expected total time for a run in seconds. * `STREAMING_BACKLOG_BYTES`: An estimate of the maximum bytes of data waiting to be consumed across all streams. This metric is in Private Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag across all streams. This metric is in Private Preview. * `STREAMING_BACKLOG_SECONDS`: An estimate of the maximum consumer delay across all streams. This metric is in Private Preview. * `STREAMING_BACKLOG_FILES`: An estimate of the maximum number of outstanding files across all streams. This metric is in Private Preview. + * `RUN_DURATION_SECONDS`: Expected total time for a run in seconds. * `STREAMING_BACKLOG_BYTES`: An estimate of the maximum bytes of data waiting to be consumed across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_RECORDS`: An estimate of the maximum offset lag across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_SECONDS`: An estimate of the maximum consumer delay across all streams. This metric is in Public Preview. * `STREAMING_BACKLOG_FILES`: An estimate of the maximum number of outstanding files across all streams. This metric is in Public Preview. .. py:attribute:: RUN_DURATION_SECONDS :value: "RUN_DURATION_SECONDS" @@ -975,7 +979,7 @@ These dataclasses are used in the SDK to represent API requests and responses fo .. py:class:: TriggerType The type of trigger that fired this run. - * `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler. * `ONE_TIME`: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API. * `RETRY`: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures. * `RUN_JOB_TASK`: Indicates a run that is triggered using a Run Job task. * `FILE_ARRIVAL`: Indicates a run that is triggered by a file arrival. * `TABLE`: Indicates a run that is triggered by a table update. + * `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler. * `ONE_TIME`: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API. * `RETRY`: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures. * `RUN_JOB_TASK`: Indicates a run that is triggered using a Run Job task. * `FILE_ARRIVAL`: Indicates a run that is triggered by a file arrival. * `TABLE`: Indicates a run that is triggered by a table update. * `CONTINUOUS_RESTART`: Indicates a run created by user to manually restart a continuous job run. .. py:attribute:: FILE_ARRIVAL :value: "FILE_ARRIVAL" diff --git a/docs/dbdataclasses/oauth2.rst b/docs/dbdataclasses/oauth2.rst index 6265f6648..70e09ab05 100644 --- a/docs/dbdataclasses/oauth2.rst +++ b/docs/dbdataclasses/oauth2.rst @@ -40,6 +40,10 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: FederationPolicy + :members: + :undoc-members: + .. autoclass:: GetCustomAppIntegrationOutput :members: :undoc-members: @@ -60,10 +64,18 @@ These dataclasses are used in the SDK to represent API requests and responses fo :members: :undoc-members: +.. autoclass:: ListFederationPoliciesResponse + :members: + :undoc-members: + .. autoclass:: ListServicePrincipalSecretsResponse :members: :undoc-members: +.. autoclass:: OidcFederationPolicy + :members: + :undoc-members: + .. autoclass:: PublishedAppOutput :members: :undoc-members: diff --git a/docs/workspace/apps/apps.rst b/docs/workspace/apps/apps.rst index 40791a143..1b9bd6c75 100644 --- a/docs/workspace/apps/apps.rst +++ b/docs/workspace/apps/apps.rst @@ -5,20 +5,20 @@ .. py:class:: AppsAPI Apps run directly on a customer’s Databricks instance, integrate with their data, use and extend - Databricks services, and enable users to interact through single sign-on. +Databricks services, and enable users to interact through single sign-on. .. py:method:: create( [, app: Optional[App]]) -> Wait[App] Create an app. - - Creates a new app. - - :param app: :class:`App` (optional) - - :returns: - Long-running operation waiter for :class:`App`. - See :method:wait_get_app_active for more details. - + +Creates a new app. + +:param app: :class:`App` (optional) + +:returns: + Long-running operation waiter for :class:`App`. + See :method:wait_get_app_active for more details. + .. py:method:: create_and_wait( [, app: Optional[App], timeout: datetime.timedelta = 0:20:00]) -> App @@ -26,29 +26,29 @@ .. py:method:: delete(name: str) -> App Delete an app. - - Deletes an app. - - :param name: str - The name of the app. - - :returns: :class:`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. - + +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. + .. py:method:: deploy_and_wait(app_name: str [, app_deployment: Optional[AppDeployment], timeout: datetime.timedelta = 0:20:00]) -> AppDeployment @@ -56,110 +56,110 @@ .. 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` - + +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` - + +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` - + +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` - + +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` - + +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` - + +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` - + +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. - + +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. + .. py:method:: start_and_wait(name: str, timeout: datetime.timedelta = 0:20:00) -> App @@ -167,16 +167,16 @@ .. 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. - + +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. + .. py:method:: stop_and_wait(name: str, timeout: datetime.timedelta = 0:20:00) -> App @@ -184,29 +184,29 @@ .. 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` - + +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` - + +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` + .. py:method:: wait_get_app_active(name: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[App], None]]) -> App diff --git a/docs/workspace/catalog/artifact_allowlists.rst b/docs/workspace/catalog/artifact_allowlists.rst index 349bbbd0f..9f22ed335 100644 --- a/docs/workspace/catalog/artifact_allowlists.rst +++ b/docs/workspace/catalog/artifact_allowlists.rst @@ -5,33 +5,32 @@ .. py:class:: ArtifactAllowlistsAPI In Databricks Runtime 13.3 and above, you can add libraries and init scripts to the `allowlist` in UC so - that users can leverage these artifacts on compute configured with shared access mode. +that users can leverage these artifacts on compute configured with shared access mode. .. 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` - + +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 + +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` diff --git a/docs/workspace/catalog/catalogs.rst b/docs/workspace/catalog/catalogs.rst index 200168ee6..a05fe8815 100644 --- a/docs/workspace/catalog/catalogs.rst +++ b/docs/workspace/catalog/catalogs.rst @@ -5,11 +5,11 @@ .. py:class:: CatalogsAPI 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. +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. .. py:method:: create(name: str [, comment: Optional[str], connection_name: Optional[str], options: Optional[Dict[str, str]], properties: Optional[Dict[str, str]], provider_name: Optional[str], share_name: Optional[str], storage_root: Optional[str]]) -> CatalogInfo @@ -30,46 +30,46 @@ 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) - User-provided free-form text description. - :param connection_name: str (optional) - The name of the connection to an external data source. - :param options: Dict[str,str] (optional) - A map of key-value properties attached to the securable. - :param properties: Dict[str,str] (optional) - 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` - + +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) + User-provided free-form text description. +:param connection_name: str (optional) + The name of the connection to an external data source. +:param options: Dict[str,str] (optional) + A map of key-value properties attached to the securable. +:param properties: Dict[str,str] (optional) + 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. - - - + +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 @@ -92,18 +92,18 @@ 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` - + +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` + .. py:method:: list( [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[CatalogInfo] @@ -120,28 +120,28 @@ 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 - :param max_results: int (optional) - Maximum number of catalogs 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 catalogs are returned (not recommended). - Note: The number of - returned catalogs might be less than the specified max_results size, even zero. The only definitive - indication that no further catalogs 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: Iterator over :class:`CatalogInfo` - + +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 +:param max_results: int (optional) + Maximum number of catalogs 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 catalogs are returned (not recommended). - Note: The number of + returned catalogs might be less than the specified max_results size, even zero. The only definitive + indication that no further catalogs 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: Iterator over :class:`CatalogInfo` + .. py:method:: update(name: str [, comment: Optional[str], enable_predictive_optimization: Optional[EnablePredictiveOptimization], isolation_mode: Optional[CatalogIsolationMode], new_name: Optional[str], owner: Optional[str], properties: Optional[Dict[str, str]]]) -> CatalogInfo @@ -164,24 +164,23 @@ 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) - User-provided free-form text description. - :param enable_predictive_optimization: :class:`EnablePredictiveOptimization` (optional) - Whether predictive optimization should be enabled for this object and objects under it. - :param isolation_mode: :class:`CatalogIsolationMode` (optional) - Whether the current securable is accessible from all workspaces or a specific set of workspaces. - :param new_name: str (optional) - New name for the catalog. - :param owner: str (optional) - 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 + +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) + User-provided free-form text description. +:param enable_predictive_optimization: :class:`EnablePredictiveOptimization` (optional) + Whether predictive optimization should be enabled for this object and objects under it. +:param isolation_mode: :class:`CatalogIsolationMode` (optional) + Whether the current securable is accessible from all workspaces or a specific set of workspaces. +:param new_name: str (optional) + New name for the catalog. +:param owner: str (optional) + 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` diff --git a/docs/workspace/catalog/connections.rst b/docs/workspace/catalog/connections.rst index b2637c2d0..32105ff61 100644 --- a/docs/workspace/catalog/connections.rst +++ b/docs/workspace/catalog/connections.rst @@ -5,13 +5,13 @@ .. 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 - objects derived from a connection can be written to or read from similar to other Unity Catalog data - objects based on cloud storage. Users may create different types of connections with each connection - having a unique set of configuration options to support credential management and other settings. + +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 +objects derived from a connection can be written to or read from similar to other Unity Catalog data +objects based on cloud storage. Users may create different types of connections with each connection +having a unique set of configuration options to support credential management and other settings. .. py:method:: create(name: str, connection_type: ConnectionType, options: Dict[str, str] [, comment: Optional[str], properties: Optional[Dict[str, str]], read_only: Optional[bool]]) -> ConnectionInfo @@ -43,39 +43,39 @@ 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` - The type of connection. - :param options: Dict[str,str] - A map of key-value properties attached to the securable. - :param comment: str (optional) - User-provided free-form text description. - :param properties: Dict[str,str] (optional) - 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` - + +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` + The type of connection. +:param options: Dict[str,str] + A map of key-value properties attached to the securable. +:param comment: str (optional) + User-provided free-form text description. +:param properties: Dict[str,str] (optional) + 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. - - - + +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 @@ -119,14 +119,14 @@ 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` - + +Gets a connection from it's name. + +:param name: str + Name of the connection. + +:returns: :class:`ConnectionInfo` + .. py:method:: list( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ConnectionInfo] @@ -143,19 +143,19 @@ 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 - a server configured value; - when set to 0, the page length is set to a server configured 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:`ConnectionInfo` - + +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 + a server configured value; - when set to 0, the page length is set to a server configured 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:`ConnectionInfo` + .. py:method:: update(name: str, options: Dict[str, str] [, new_name: Optional[str], owner: Optional[str]]) -> ConnectionInfo @@ -197,17 +197,16 @@ 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] - A map of key-value properties attached to the securable. - :param new_name: str (optional) - 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 + +Updates the connection that matches the supplied name. + +:param name: str + Name of the connection. +:param options: Dict[str,str] + A map of key-value properties attached to the securable. +:param new_name: str (optional) + New name for the connection. +:param owner: str (optional) + Username of current owner of the connection. + +:returns: :class:`ConnectionInfo` diff --git a/docs/workspace/catalog/external_locations.rst b/docs/workspace/catalog/external_locations.rst index fc60b18f6..13e4a90f0 100644 --- a/docs/workspace/catalog/external_locations.rst +++ b/docs/workspace/catalog/external_locations.rst @@ -5,15 +5,15 @@ .. py:class:: ExternalLocationsAPI An external location is an object that combines a cloud storage path with a storage credential that - authorizes access to the cloud storage path. Each external location is subject to Unity Catalog - 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. +authorizes access to the cloud storage path. Each external location is subject to Unity Catalog +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. .. py:method:: create(name: str, url: str, credential_name: str [, access_point: Optional[str], comment: Optional[str], encryption_details: Optional[EncryptionDetails], fallback: Optional[bool], read_only: Optional[bool], skip_validation: Optional[bool]]) -> ExternalLocationInfo @@ -46,49 +46,49 @@ 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 - Path URL of the external location. - :param credential_name: str - Name of the storage credential used with this location. - :param access_point: str (optional) - The AWS access point to use when accesing s3 for this external location. - :param comment: str (optional) - User-provided free-form text description. - :param encryption_details: :class:`EncryptionDetails` (optional) - Encryption options that apply to clients connecting to cloud storage. - :param fallback: bool (optional) - Indicates whether fallback mode is enabled for this external location. When fallback mode is - enabled, the access to the location falls back to cluster credentials if UC credentials are not - sufficient. - :param read_only: bool (optional) - 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` - + +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 + Path URL of the external location. +:param credential_name: str + Name of the storage credential used with this location. +:param access_point: str (optional) + The AWS access point to use when accesing s3 for this external location. +:param comment: str (optional) + User-provided free-form text description. +:param encryption_details: :class:`EncryptionDetails` (optional) + Encryption options that apply to clients connecting to cloud storage. +:param fallback: bool (optional) + Indicates whether fallback mode is enabled for this external location. When fallback mode is + enabled, the access to the location falls back to cluster credentials if UC credentials are not + sufficient. +:param read_only: bool (optional) + 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. - - - + +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 @@ -120,18 +120,18 @@ 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` - + +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` + .. py:method:: list( [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ExternalLocationInfo] @@ -148,24 +148,24 @@ 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 - :param max_results: int (optional) - Maximum number of external locations to return. If not set, all the external locations are returned - (not 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 0, the page length is set to a server configured - 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` - + +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 +:param max_results: int (optional) + Maximum number of external locations to return. If not set, all the external locations are returned + (not 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 0, the page length is set to a server configured + 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` + .. py:method:: update(name: str [, access_point: Optional[str], comment: Optional[str], credential_name: Optional[str], encryption_details: Optional[EncryptionDetails], fallback: Optional[bool], force: Optional[bool], isolation_mode: Optional[IsolationMode], new_name: Optional[str], owner: Optional[str], read_only: Optional[bool], skip_validation: Optional[bool], url: Optional[str]]) -> ExternalLocationInfo @@ -199,38 +199,37 @@ 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) - The AWS access point to use when accesing s3 for this external location. - :param comment: str (optional) - User-provided free-form text description. - :param credential_name: str (optional) - Name of the storage credential used with this location. - :param encryption_details: :class:`EncryptionDetails` (optional) - Encryption options that apply to clients connecting to cloud storage. - :param fallback: bool (optional) - Indicates whether fallback mode is enabled for this external location. When fallback mode is - enabled, the access to the location falls back to cluster credentials if UC credentials are not - sufficient. - :param force: bool (optional) - Force update even if changing url invalidates dependent external tables or mounts. - :param isolation_mode: :class:`IsolationMode` (optional) - :param new_name: str (optional) - New name for the external location. - :param owner: str (optional) - The owner of the external location. - :param read_only: bool (optional) - Indicates whether the external location is read-only. - :param skip_validation: bool (optional) - 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 + +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) + The AWS access point to use when accesing s3 for this external location. +:param comment: str (optional) + User-provided free-form text description. +:param credential_name: str (optional) + Name of the storage credential used with this location. +:param encryption_details: :class:`EncryptionDetails` (optional) + Encryption options that apply to clients connecting to cloud storage. +:param fallback: bool (optional) + Indicates whether fallback mode is enabled for this external location. When fallback mode is + enabled, the access to the location falls back to cluster credentials if UC credentials are not + sufficient. +:param force: bool (optional) + Force update even if changing url invalidates dependent external tables or mounts. +:param isolation_mode: :class:`IsolationMode` (optional) +:param new_name: str (optional) + New name for the external location. +:param owner: str (optional) + The owner of the external location. +:param read_only: bool (optional) + Indicates whether the external location is read-only. +:param skip_validation: bool (optional) + Skips validation of the storage credential associated with the external location. +:param url: str (optional) + Path URL of the external location. + +:returns: :class:`ExternalLocationInfo` diff --git a/docs/workspace/catalog/functions.rst b/docs/workspace/catalog/functions.rst index 646488074..61537556b 100644 --- a/docs/workspace/catalog/functions.rst +++ b/docs/workspace/catalog/functions.rst @@ -5,113 +5,112 @@ .. 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__. + +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__. .. 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` - + +**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. - - - + +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` - + +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 - Parent schema of functions. - :param include_browse: bool (optional) - Whether to include functions in the response for which the principal can only access selective - metadata for - :param max_results: int (optional) - Maximum number of functions to return. If not set, all the functions are returned (not 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 0, the page length is set to a server configured 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:`FunctionInfo` - + +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 + Parent schema of functions. +:param include_browse: bool (optional) + Whether to include functions in the response for which the principal can only access selective + metadata for +:param max_results: int (optional) + Maximum number of functions to return. If not set, all the functions are returned (not 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 0, the page length is set to a server configured 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:`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 + +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` diff --git a/docs/workspace/catalog/grants.rst b/docs/workspace/catalog/grants.rst index 8def7ff83..20c63fc27 100644 --- a/docs/workspace/catalog/grants.rst +++ b/docs/workspace/catalog/grants.rst @@ -5,14 +5,14 @@ .. py:class:: GrantsAPI In Unity Catalog, data is secure by default. Initially, users have no access to data in a metastore. - 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 - objects within that schema. +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 +objects within that schema. .. py:method:: get(securable_type: SecurableType, full_name: str [, principal: Optional[str]]) -> PermissionsList @@ -52,18 +52,18 @@ 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` - + +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` + .. py:method:: get_effective(securable_type: SecurableType, full_name: str [, principal: Optional[str]]) -> EffectivePermissionsList @@ -103,19 +103,19 @@ 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 - Full name of securable. - :param principal: str (optional) - If provided, only the effective permissions for the specified principal (user or group) are - returned. - - :returns: :class:`EffectivePermissionsList` - + +Gets the effective 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 effective permissions for the specified principal (user or group) are + returned. + +:returns: :class:`EffectivePermissionsList` + .. py:method:: update(securable_type: SecurableType, full_name: str [, changes: Optional[List[PermissionsChange]]]) -> PermissionsList @@ -162,15 +162,14 @@ 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 + +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` diff --git a/docs/workspace/catalog/metastores.rst b/docs/workspace/catalog/metastores.rst index 01a936e0b..f1ab5ff61 100644 --- a/docs/workspace/catalog/metastores.rst +++ b/docs/workspace/catalog/metastores.rst @@ -5,16 +5,16 @@ .. py:class:: MetastoresAPI A metastore is the top-level container of objects in Unity Catalog. It stores data assets (tables and - 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. +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. .. py:method:: assign(workspace_id: int, metastore_id: str, default_catalog_name: str) @@ -42,21 +42,21 @@ 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 - The unique ID of the metastore. - :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. - - - + +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 + The unique ID of the metastore. +: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 @@ -80,23 +80,23 @@ 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) - Cloud region which the metastore serves (e.g., `us-west-2`, `westus`). The field can be omitted in - the __workspace-level__ __API__ but not in the __account-level__ __API__. If this field is omitted, - 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` - + +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) + Cloud region which the metastore serves (e.g., `us-west-2`, `westus`). The field can be omitted in + the __workspace-level__ __API__ but not in the __account-level__ __API__. If this field is omitted, + 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` + .. py:method:: current() -> MetastoreAssignment @@ -112,25 +112,25 @@ current_metastore = w.metastores.current() Get metastore assignment for workspace. - - Gets the metastore assignment for the workspace being accessed. - - :returns: :class:`MetastoreAssignment` - + +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. - - - + +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 @@ -156,15 +156,15 @@ 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` - + +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` + .. py:method:: list() -> Iterator[MetastoreInfo] @@ -180,12 +180,12 @@ 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` - + +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` + .. py:method:: summary() -> GetMetastoreSummaryResponse @@ -201,12 +201,12 @@ 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` - + +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` + .. py:method:: unassign(workspace_id: int, metastore_id: str) @@ -234,16 +234,16 @@ 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. - - - + +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 @@ -269,47 +269,46 @@ 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) - The organization name of a Delta Sharing entity, to be used in Databricks-to-Databricks Delta - Sharing as the official name. - :param delta_sharing_recipient_token_lifetime_in_seconds: int (optional) - The lifetime of delta sharing recipient token in seconds. - :param delta_sharing_scope: :class:`UpdateMetastoreDeltaSharingScope` (optional) - The scope of Delta Sharing enabled for the metastore. - :param new_name: str (optional) - New name for the metastore. - :param owner: str (optional) - The owner of the metastore. - :param privilege_model_version: str (optional) - 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` - + +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) + The organization name of a Delta Sharing entity, to be used in Databricks-to-Databricks Delta + Sharing as the official name. +:param delta_sharing_recipient_token_lifetime_in_seconds: int (optional) + The lifetime of delta sharing recipient token in seconds. +:param delta_sharing_scope: :class:`UpdateMetastoreDeltaSharingScope` (optional) + The scope of Delta Sharing enabled for the metastore. +:param new_name: str (optional) + New name for the metastore. +:param owner: str (optional) + The owner of the metastore. +:param privilege_model_version: str (optional) + 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) - 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. - :param metastore_id: str (optional) - The unique ID of the metastore. - - - \ No newline at end of file + +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) + 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. +:param metastore_id: str (optional) + The unique ID of the metastore. + + diff --git a/docs/workspace/catalog/model_versions.rst b/docs/workspace/catalog/model_versions.rst index bae6f25f8..018379273 100644 --- a/docs/workspace/catalog/model_versions.rst +++ b/docs/workspace/catalog/model_versions.rst @@ -5,125 +5,124 @@ .. py:class:: ModelVersionsAPI 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). +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 - - - + +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 - The integer version number of the model version - :param include_aliases: bool (optional) - Whether to include aliases associated with the model version in the response - :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` - + +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 + The integer version number of the model version +:param include_aliases: bool (optional) + Whether to include aliases associated with the model version in the response +: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` - + +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) - Whether to include model versions in the response for which the principal can only access selective - metadata for - :param max_results: int (optional) - Maximum number of model versions to return. If not set, the page length is set to a server - configured value (100, as of 1/3/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 1/3/2024); - when set to 0, the page - length is set to a server configured value (100, as of 1/3/2024) (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:`ModelVersionInfo` - + +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) + Whether to include model versions in the response for which the principal can only access selective + metadata for +:param max_results: int (optional) + Maximum number of model versions to return. If not set, the page length is set to a server + configured value (100, as of 1/3/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 1/3/2024); - when set to 0, the page + length is set to a server configured value (100, as of 1/3/2024) (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:`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 + +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` diff --git a/docs/workspace/catalog/online_tables.rst b/docs/workspace/catalog/online_tables.rst index d0119657f..fe4cee905 100644 --- a/docs/workspace/catalog/online_tables.rst +++ b/docs/workspace/catalog/online_tables.rst @@ -9,16 +9,16 @@ .. 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. - + +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. + .. py:method:: create_and_wait( [, table: Optional[OnlineTable], timeout: datetime.timedelta = 0:20:00]) -> OnlineTable @@ -26,27 +26,27 @@ .. 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. - - - + +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` - + +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` + .. py:method:: wait_get_online_table_active(name: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[OnlineTable], None]]) -> OnlineTable diff --git a/docs/workspace/catalog/quality_monitors.rst b/docs/workspace/catalog/quality_monitors.rst index 93f05b69a..8e71050f2 100644 --- a/docs/workspace/catalog/quality_monitors.rst +++ b/docs/workspace/catalog/quality_monitors.rst @@ -5,255 +5,254 @@ .. py:class:: QualityMonitorsAPI 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**). +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**). .. 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. - - - + +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 - The directory to store monitoring assets (e.g. dashboard, metric tables). - :param output_schema_name: str - Schema where output metric tables are created. - :param baseline_table_name: str (optional) - Name of the baseline table from which drift metrics are computed from. Columns in the monitored - table should also be present in the baseline table. - :param custom_metrics: List[:class:`MonitorMetric`] (optional) - Custom metrics to compute on the monitored table. These can be aggregate metrics, derived metrics - (from already computed aggregate metrics), or drift metrics (comparing metrics across time windows). - :param data_classification_config: :class:`MonitorDataClassificationConfig` (optional) - The data classification config for the monitor. - :param inference_log: :class:`MonitorInferenceLog` (optional) - Configuration for monitoring inference logs. - :param notifications: :class:`MonitorNotifications` (optional) - The notification settings for the monitor. - :param schedule: :class:`MonitorCronSchedule` (optional) - The schedule for automatically updating and refreshing metric tables. - :param skip_builtin_dashboard: bool (optional) - Whether to skip creating a default dashboard summarizing data quality metrics. - :param slicing_exprs: List[str] (optional) - List of column expressions to slice data with for targeted analysis. The data is grouped by each - expression independently, resulting in a separate slice for each predicate and its complements. For - high-cardinality columns, only the top 100 unique values by frequency will generate slices. - :param snapshot: :class:`MonitorSnapshot` (optional) - Configuration for monitoring snapshot tables. - :param time_series: :class:`MonitorTimeSeries` (optional) - Configuration for monitoring time series tables. - :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` - + +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 + The directory to store monitoring assets (e.g. dashboard, metric tables). +:param output_schema_name: str + Schema where output metric tables are created. +:param baseline_table_name: str (optional) + Name of the baseline table from which drift metrics are computed from. Columns in the monitored + table should also be present in the baseline table. +:param custom_metrics: List[:class:`MonitorMetric`] (optional) + Custom metrics to compute on the monitored table. These can be aggregate metrics, derived metrics + (from already computed aggregate metrics), or drift metrics (comparing metrics across time windows). +:param data_classification_config: :class:`MonitorDataClassificationConfig` (optional) + The data classification config for the monitor. +:param inference_log: :class:`MonitorInferenceLog` (optional) + Configuration for monitoring inference logs. +:param notifications: :class:`MonitorNotifications` (optional) + The notification settings for the monitor. +:param schedule: :class:`MonitorCronSchedule` (optional) + The schedule for automatically updating and refreshing metric tables. +:param skip_builtin_dashboard: bool (optional) + Whether to skip creating a default dashboard summarizing data quality metrics. +:param slicing_exprs: List[str] (optional) + List of column expressions to slice data with for targeted analysis. The data is grouped by each + expression independently, resulting in a separate slice for each predicate and its complements. For + high-cardinality columns, only the top 100 unique values by frequency will generate slices. +:param snapshot: :class:`MonitorSnapshot` (optional) + Configuration for monitoring snapshot tables. +:param time_series: :class:`MonitorTimeSeries` (optional) + Configuration for monitoring time series tables. +: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. - - - + +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` - + +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` - + +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` - + +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` - + +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` - + +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 - Schema where output metric tables are created. - :param baseline_table_name: str (optional) - Name of the baseline table from which drift metrics are computed from. Columns in the monitored - table should also be present in the baseline table. - :param custom_metrics: List[:class:`MonitorMetric`] (optional) - Custom metrics to compute on the monitored table. These can be aggregate metrics, derived metrics - (from already computed aggregate metrics), or drift metrics (comparing metrics across time windows). - :param dashboard_id: str (optional) - Id of dashboard that visualizes the computed metrics. This can be empty if the monitor is in PENDING - state. - :param data_classification_config: :class:`MonitorDataClassificationConfig` (optional) - The data classification config for the monitor. - :param inference_log: :class:`MonitorInferenceLog` (optional) - Configuration for monitoring inference logs. - :param notifications: :class:`MonitorNotifications` (optional) - The notification settings for the monitor. - :param schedule: :class:`MonitorCronSchedule` (optional) - The schedule for automatically updating and refreshing metric tables. - :param slicing_exprs: List[str] (optional) - List of column expressions to slice data with for targeted analysis. The data is grouped by each - expression independently, resulting in a separate slice for each predicate and its complements. For - high-cardinality columns, only the top 100 unique values by frequency will generate slices. - :param snapshot: :class:`MonitorSnapshot` (optional) - 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 + +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 + Schema where output metric tables are created. +:param baseline_table_name: str (optional) + Name of the baseline table from which drift metrics are computed from. Columns in the monitored + table should also be present in the baseline table. +:param custom_metrics: List[:class:`MonitorMetric`] (optional) + Custom metrics to compute on the monitored table. These can be aggregate metrics, derived metrics + (from already computed aggregate metrics), or drift metrics (comparing metrics across time windows). +:param dashboard_id: str (optional) + Id of dashboard that visualizes the computed metrics. This can be empty if the monitor is in PENDING + state. +:param data_classification_config: :class:`MonitorDataClassificationConfig` (optional) + The data classification config for the monitor. +:param inference_log: :class:`MonitorInferenceLog` (optional) + Configuration for monitoring inference logs. +:param notifications: :class:`MonitorNotifications` (optional) + The notification settings for the monitor. +:param schedule: :class:`MonitorCronSchedule` (optional) + The schedule for automatically updating and refreshing metric tables. +:param slicing_exprs: List[str] (optional) + List of column expressions to slice data with for targeted analysis. The data is grouped by each + expression independently, resulting in a separate slice for each predicate and its complements. For + high-cardinality columns, only the top 100 unique values by frequency will generate slices. +:param snapshot: :class:`MonitorSnapshot` (optional) + Configuration for monitoring snapshot tables. +:param time_series: :class:`MonitorTimeSeries` (optional) + Configuration for monitoring time series tables. + +:returns: :class:`MonitorInfo` diff --git a/docs/workspace/catalog/registered_models.rst b/docs/workspace/catalog/registered_models.rst index b05a702b5..cba3cbc96 100644 --- a/docs/workspace/catalog/registered_models.rst +++ b/docs/workspace/catalog/registered_models.rst @@ -5,197 +5,196 @@ .. py:class:: RegisteredModelsAPI 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 - registered model or model version tags, users must additionally have APPLY TAG permissions on the - 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. +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 +registered model or model version tags, users must additionally have APPLY TAG permissions on the +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 - The name of the schema where the registered model resides - :param name: str - The name of the registered model - :param comment: str (optional) - 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` - + +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 + The name of the schema where the registered model resides +:param name: str + The name of the registered model +:param comment: str (optional) + 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 - - - + +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 - - - + +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) - Whether to include registered model aliases in the response - :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` - + +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) + Whether to include registered model aliases in the response +: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. - :param include_browse: bool (optional) - Whether to include registered models in the response for which the principal can only access - 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); - - when set to 0, the page length is set to a server configured value (100, as of 4/2/2024); - when set - to a value less than 0, an invalid parameter error is returned; - :param page_token: str (optional) - Opaque token to send for the next page of results (pagination). - :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` - + +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. +:param include_browse: bool (optional) + Whether to include registered models in the response for which the principal can only access + 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); - + when set to 0, the page length is set to a server configured value (100, as of 4/2/2024); - when set + to a value less than 0, an invalid parameter error is returned; +:param page_token: str (optional) + Opaque token to send for the next page of results (pagination). +: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` - + +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) - The comment attached to the registered model - :param new_name: str (optional) - 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 + +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) + The comment attached to the registered model +:param new_name: str (optional) + New name for the registered model. +:param owner: str (optional) + The identifier of the user who owns the registered model + +:returns: :class:`RegisteredModelInfo` diff --git a/docs/workspace/catalog/resource_quotas.rst b/docs/workspace/catalog/resource_quotas.rst index 3396011f0..22f50f0f1 100644 --- a/docs/workspace/catalog/resource_quotas.rst +++ b/docs/workspace/catalog/resource_quotas.rst @@ -5,41 +5,40 @@ .. py:class:: ResourceQuotasAPI Unity Catalog enforces resource quotas on all securable objects, which limits the number of resources that - 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 +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` - + +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 + +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` diff --git a/docs/workspace/catalog/schemas.rst b/docs/workspace/catalog/schemas.rst index feaf7c7a0..a3c9d2096 100644 --- a/docs/workspace/catalog/schemas.rst +++ b/docs/workspace/catalog/schemas.rst @@ -5,9 +5,9 @@ .. py:class:: SchemasAPI A schema (also called a database) is the second layer of Unity Catalog’s three-level namespace. A schema - organizes tables, views and functions. To access (or list) a table or view in a schema, users must have - the USE_SCHEMA data permission on the schema and its parent catalog, and they must have the SELECT - permission on the table or view. +organizes tables, views and functions. To access (or list) a table or view in a schema, users must have +the USE_SCHEMA data permission on the schema and its parent catalog, and they must have the SELECT +permission on the table or view. .. py:method:: create(name: str, catalog_name: str [, comment: Optional[str], properties: Optional[Dict[str, str]], storage_root: Optional[str]]) -> SchemaInfo @@ -31,38 +31,38 @@ 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 - Name of parent catalog. - :param comment: str (optional) - User-provided free-form text description. - :param properties: Dict[str,str] (optional) - 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` - + +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 + Name of parent catalog. +:param comment: str (optional) + User-provided free-form text description. +:param properties: Dict[str,str] (optional) + 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. - - - + +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 @@ -88,18 +88,18 @@ 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` - + +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` + .. py:method:: list(catalog_name: str [, include_browse: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[SchemaInfo] @@ -122,27 +122,27 @@ 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) - Whether to include schemas in the response for which the principal can only access selective - metadata for - :param max_results: int (optional) - Maximum number of schemas to return. If not set, all the schemas are returned (not 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 0, the page length is set to a server configured 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:`SchemaInfo` - + +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) + Whether to include schemas in the response for which the principal can only access selective + metadata for +:param max_results: int (optional) + Maximum number of schemas to return. If not set, all the schemas are returned (not 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 0, the page length is set to a server configured 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:`SchemaInfo` + .. py:method:: update(full_name: str [, comment: Optional[str], enable_predictive_optimization: Optional[EnablePredictiveOptimization], new_name: Optional[str], owner: Optional[str], properties: Optional[Dict[str, str]]]) -> SchemaInfo @@ -168,24 +168,23 @@ 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) - User-provided free-form text description. - :param enable_predictive_optimization: :class:`EnablePredictiveOptimization` (optional) - Whether predictive optimization should be enabled for this object and objects under it. - :param new_name: str (optional) - New name for the schema. - :param owner: str (optional) - 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 + +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) + User-provided free-form text description. +:param enable_predictive_optimization: :class:`EnablePredictiveOptimization` (optional) + Whether predictive optimization should be enabled for this object and objects under it. +:param new_name: str (optional) + New name for the schema. +:param owner: str (optional) + 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` diff --git a/docs/workspace/catalog/storage_credentials.rst b/docs/workspace/catalog/storage_credentials.rst index cac70a944..80cee7900 100644 --- a/docs/workspace/catalog/storage_credentials.rst +++ b/docs/workspace/catalog/storage_credentials.rst @@ -5,15 +5,15 @@ .. py:class:: StorageCredentialsAPI A storage credential represents an authentication and authorization mechanism for accessing data stored on - your cloud tenant. Each storage credential is subject to Unity Catalog access-control policies that - 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. +your cloud tenant. Each storage credential is subject to Unity Catalog access-control policies that +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. .. py:method:: create(name: str [, aws_iam_role: Optional[AwsIamRoleRequest], azure_managed_identity: Optional[AzureManagedIdentityRequest], azure_service_principal: Optional[AzureServicePrincipal], cloudflare_api_token: Optional[CloudflareApiToken], comment: Optional[str], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccountRequest], read_only: Optional[bool], skip_validation: Optional[bool]]) -> StorageCredentialInfo @@ -38,45 +38,45 @@ 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) - The AWS IAM role configuration. - :param azure_managed_identity: :class:`AzureManagedIdentityRequest` (optional) - The Azure managed identity configuration. - :param azure_service_principal: :class:`AzureServicePrincipal` (optional) - The Azure service principal configuration. - :param cloudflare_api_token: :class:`CloudflareApiToken` (optional) - The Cloudflare API token configuration. - :param comment: str (optional) - Comment associated with the credential. - :param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) - The Databricks managed GCP service account configuration. - :param read_only: bool (optional) - 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` - + +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) + The AWS IAM role configuration. +:param azure_managed_identity: :class:`AzureManagedIdentityRequest` (optional) + The Azure managed identity configuration. +:param azure_service_principal: :class:`AzureServicePrincipal` (optional) + The Azure service principal configuration. +:param cloudflare_api_token: :class:`CloudflareApiToken` (optional) + The Cloudflare API token configuration. +:param comment: str (optional) + Comment associated with the credential. +:param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) + The Databricks managed GCP service account configuration. +:param read_only: bool (optional) + 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. - - - + +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 @@ -103,15 +103,15 @@ 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` - + +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` + .. py:method:: list( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[StorageCredentialInfo] @@ -127,23 +127,23 @@ 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 - this value and a server configured value; - when set to 0, the page length is set to a server - configured 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:`StorageCredentialInfo` - + +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 + this value and a server configured value; - when set to 0, the page length is set to a server + configured 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:`StorageCredentialInfo` + .. py:method:: update(name: str [, aws_iam_role: Optional[AwsIamRoleRequest], azure_managed_identity: Optional[AzureManagedIdentityResponse], azure_service_principal: Optional[AzureServicePrincipal], cloudflare_api_token: Optional[CloudflareApiToken], comment: Optional[str], databricks_gcp_service_account: Optional[DatabricksGcpServiceAccountRequest], force: Optional[bool], isolation_mode: Optional[IsolationMode], new_name: Optional[str], owner: Optional[str], read_only: Optional[bool], skip_validation: Optional[bool]]) -> StorageCredentialInfo @@ -173,70 +173,69 @@ 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) - The AWS IAM role configuration. - :param azure_managed_identity: :class:`AzureManagedIdentityResponse` (optional) - The Azure managed identity configuration. - :param azure_service_principal: :class:`AzureServicePrincipal` (optional) - The Azure service principal configuration. - :param cloudflare_api_token: :class:`CloudflareApiToken` (optional) - The Cloudflare API token configuration. - :param comment: str (optional) - Comment associated with the credential. - :param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) - The Databricks managed GCP service account configuration. - :param force: bool (optional) - Force update even if there are dependent external locations or external tables. - :param isolation_mode: :class:`IsolationMode` (optional) - :param new_name: str (optional) - New name for the storage credential. - :param owner: str (optional) - Username of current owner of credential. - :param read_only: bool (optional) - 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` - + +Updates a storage credential on the metastore. + +:param name: str + Name of the storage credential. +:param aws_iam_role: :class:`AwsIamRoleRequest` (optional) + The AWS IAM role configuration. +:param azure_managed_identity: :class:`AzureManagedIdentityResponse` (optional) + The Azure managed identity configuration. +:param azure_service_principal: :class:`AzureServicePrincipal` (optional) + The Azure service principal configuration. +:param cloudflare_api_token: :class:`CloudflareApiToken` (optional) + The Cloudflare API token configuration. +:param comment: str (optional) + Comment associated with the credential. +:param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) + The Databricks managed GCP service account configuration. +:param force: bool (optional) + Force update even if there are dependent external locations or external tables. +:param isolation_mode: :class:`IsolationMode` (optional) +:param new_name: str (optional) + New name for the storage credential. +:param owner: str (optional) + Username of current owner of credential. +:param read_only: bool (optional) + 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) - The Azure managed identity configuration. - :param azure_service_principal: :class:`AzureServicePrincipal` (optional) - The Azure service principal configuration. - :param cloudflare_api_token: :class:`CloudflareApiToken` (optional) - The Cloudflare API token configuration. - :param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) - The Databricks created GCP service account configuration. - :param external_location_name: str (optional) - The name of an existing external location to validate. - :param read_only: bool (optional) - Whether the storage credential is only usable for read operations. - :param storage_credential_name: str (optional) - 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 + +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) + The Azure managed identity configuration. +:param azure_service_principal: :class:`AzureServicePrincipal` (optional) + The Azure service principal configuration. +:param cloudflare_api_token: :class:`CloudflareApiToken` (optional) + The Cloudflare API token configuration. +:param databricks_gcp_service_account: :class:`DatabricksGcpServiceAccountRequest` (optional) + The Databricks created GCP service account configuration. +:param external_location_name: str (optional) + The name of an existing external location to validate. +:param read_only: bool (optional) + Whether the storage credential is only usable for read operations. +:param storage_credential_name: str (optional) + The name of the storage credential to validate. +:param url: str (optional) + The external location url to validate. + +:returns: :class:`ValidateStorageCredentialResponse` diff --git a/docs/workspace/catalog/system_schemas.rst b/docs/workspace/catalog/system_schemas.rst index 2028a3623..91e82ca57 100644 --- a/docs/workspace/catalog/system_schemas.rst +++ b/docs/workspace/catalog/system_schemas.rst @@ -5,54 +5,53 @@ .. py:class:: SystemSchemasAPI A system schema is a schema that lives within the system catalog. A system schema may contain information - about customer usage of Unity Catalog such as audit-logs, billing-logs, lineage information, etc. +about customer usage of Unity Catalog such as audit-logs, billing-logs, lineage information, etc. .. 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. - - - + +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. - - - + +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) - Maximum number of schemas 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 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 + +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) + Maximum number of schemas 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 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` diff --git a/docs/workspace/catalog/table_constraints.rst b/docs/workspace/catalog/table_constraints.rst index dd46c42f3..0b631408f 100644 --- a/docs/workspace/catalog/table_constraints.rst +++ b/docs/workspace/catalog/table_constraints.rst @@ -5,58 +5,57 @@ .. 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. + +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` - + +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 - The name of the constraint to delete. - :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 + +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 + The name of the constraint to delete. +: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. + + diff --git a/docs/workspace/catalog/tables.rst b/docs/workspace/catalog/tables.rst index 15cfb1cac..3fa411272 100644 --- a/docs/workspace/catalog/tables.rst +++ b/docs/workspace/catalog/tables.rst @@ -5,45 +5,45 @@ .. py:class:: TablesAPI A table resides in the third layer of Unity Catalog’s three-level namespace. It contains rows of data. - To create a table, users must have CREATE_TABLE and USE_SCHEMA permissions on the schema, and they must - 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). +To create a table, users must have CREATE_TABLE and USE_SCHEMA permissions on the schema, and they must +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. - - - + +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` - + +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` + .. py:method:: get(full_name: str [, include_browse: Optional[bool], include_delta_metadata: Optional[bool], include_manifest_capabilities: Optional[bool]]) -> TableInfo @@ -80,25 +80,25 @@ 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) - Whether to include tables in the response for which the principal can only access selective metadata - for - :param include_delta_metadata: bool (optional) - 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` - + +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) + Whether to include tables in the response for which the principal can only access selective metadata + for +:param include_delta_metadata: bool (optional) + 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` + .. py:method:: list(catalog_name: str, schema_name: str [, include_browse: Optional[bool], include_delta_metadata: Optional[bool], include_manifest_capabilities: Optional[bool], max_results: Optional[int], omit_columns: Optional[bool], omit_properties: Optional[bool], omit_username: Optional[bool], page_token: Optional[str]]) -> Iterator[TableInfo] @@ -124,41 +124,41 @@ 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 - Parent schema of tables. - :param include_browse: bool (optional) - Whether to include tables in the response for which the principal can only access selective metadata - for - :param include_delta_metadata: bool (optional) - 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. - :param max_results: int (optional) - Maximum number of tables to return. If not set, all the tables are returned (not 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 0, the page length is set to a server configured value - (recommended); - when set to a value less than 0, an invalid parameter error is returned; - :param omit_columns: bool (optional) - Whether to omit the columns of the table from the response or not. - :param omit_properties: bool (optional) - Whether to omit the properties of the table from the response or not. - :param omit_username: bool (optional) - Whether to omit the username of the table (e.g. owner, updated_by, created_by) from the response or - not. - :param page_token: str (optional) - Opaque token to send for the next page of results (pagination). - - :returns: Iterator over :class:`TableInfo` - + +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 + Parent schema of tables. +:param include_browse: bool (optional) + Whether to include tables in the response for which the principal can only access selective metadata + for +:param include_delta_metadata: bool (optional) + 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. +:param max_results: int (optional) + Maximum number of tables to return. If not set, all the tables are returned (not 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 0, the page length is set to a server configured value + (recommended); - when set to a value less than 0, an invalid parameter error is returned; +:param omit_columns: bool (optional) + Whether to omit the columns of the table from the response or not. +:param omit_properties: bool (optional) + Whether to omit the properties of the table from the response or not. +:param omit_username: bool (optional) + Whether to omit the username of the table (e.g. owner, updated_by, created_by) from the response or + not. +:param page_token: str (optional) + Opaque token to send for the next page of results (pagination). + +:returns: Iterator over :class:`TableInfo` + .. py:method:: list_summaries(catalog_name: str [, include_manifest_capabilities: Optional[bool], max_results: Optional[int], page_token: Optional[str], schema_name_pattern: Optional[str], table_name_pattern: Optional[str]]) -> Iterator[TableSummary] @@ -185,50 +185,49 @@ 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) - Whether to include a manifest containing capabilities the table has. - :param max_results: int (optional) - Maximum number of summaries for tables to return. If not set, the page length is set to a server - configured value (10000, as of 1/5/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/5/2024); - when set to 0, - the page length is set to a server configured value (10000, as of 1/5/2024) (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. - :param schema_name_pattern: str (optional) - 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` - + +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) + Whether to include a manifest containing capabilities the table has. +:param max_results: int (optional) + Maximum number of summaries for tables to return. If not set, the page length is set to a server + configured value (10000, as of 1/5/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/5/2024); - when set to 0, + the page length is set to a server configured value (10000, as of 1/5/2024) (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. +:param schema_name_pattern: str (optional) + 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 + +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) + + diff --git a/docs/workspace/catalog/temporary_table_credentials.rst b/docs/workspace/catalog/temporary_table_credentials.rst index 1acd462b7..9898af1ba 100644 --- a/docs/workspace/catalog/temporary_table_credentials.rst +++ b/docs/workspace/catalog/temporary_table_credentials.rst @@ -5,32 +5,31 @@ .. py:class:: TemporaryTableCredentialsAPI Temporary Table Credentials refer to short-lived, downscoped credentials used to access cloud storage - locationswhere table data is stored in Databricks. These credentials are employed to provide secure and - time-limitedaccess to data in cloud environments such as AWS, Azure, and Google Cloud. Each cloud provider - has its own typeof credentials: AWS uses temporary session tokens via AWS Security Token Service (STS), - Azure utilizesShared Access Signatures (SAS) for its data storage services, and Google Cloud supports - temporary credentialsthrough OAuth 2.0.Temporary table credentials ensure that data access is limited in - scope and duration, reducing the risk ofunauthorized access or misuse. To use the temporary table - credentials API, a metastore admin needs to enable the external_access_enabled flag (off by default) at - the metastore level, and user needs to be granted the EXTERNAL USE SCHEMA permission at the schema level - by catalog admin. Note that EXTERNAL USE SCHEMA is a schema level permission that can only be granted by - catalog admin explicitly and is not included in schema ownership or ALL PRIVILEGES on the schema for - security reason. +locationswhere table data is stored in Databricks. These credentials are employed to provide secure and +time-limitedaccess to data in cloud environments such as AWS, Azure, and Google Cloud. Each cloud provider +has its own typeof credentials: AWS uses temporary session tokens via AWS Security Token Service (STS), +Azure utilizesShared Access Signatures (SAS) for its data storage services, and Google Cloud supports +temporary credentialsthrough OAuth 2.0.Temporary table credentials ensure that data access is limited in +scope and duration, reducing the risk ofunauthorized access or misuse. To use the temporary table +credentials API, a metastore admin needs to enable the external_access_enabled flag (off by default) at +the metastore level, and user needs to be granted the EXTERNAL USE SCHEMA permission at the schema level +by catalog admin. Note that EXTERNAL USE SCHEMA is a schema level permission that can only be granted by +catalog admin explicitly and is not included in schema ownership or ALL PRIVILEGES on the schema for +security reason. .. 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 + +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` diff --git a/docs/workspace/catalog/volumes.rst b/docs/workspace/catalog/volumes.rst index 76e7c6c33..62d23b88b 100644 --- a/docs/workspace/catalog/volumes.rst +++ b/docs/workspace/catalog/volumes.rst @@ -5,11 +5,11 @@ .. py:class:: VolumesAPI Volumes are a Unity Catalog (UC) capability for accessing, storing, governing, organizing and processing - files. Use cases include running machine learning on unstructured data such as image, audio, video, or PDF - files, organizing data sets during the data exploration stages in data science, working with libraries - that require access to the local file system on cluster machines, storing library and config files of - arbitrary formats such as .whl or .txt centrally and providing secure access across workspaces to it, or - transforming and querying non-tabular data files in ETL. +files. Use cases include running machine learning on unstructured data such as image, audio, video, or PDF +files, organizing data sets during the data exploration stages in data science, working with libraries +that require access to the local file system on cluster machines, storing library and config files of +arbitrary formats such as .whl or .txt centrally and providing secure access across workspaces to it, or +transforming and querying non-tabular data files in ETL. .. py:method:: create(catalog_name: str, schema_name: str, name: str, volume_type: VolumeType [, comment: Optional[str], storage_location: Optional[str]]) -> VolumeInfo @@ -55,53 +55,53 @@ 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 - The name of the schema where the volume is - :param name: str - The name of the volume - :param volume_type: :class:`VolumeType` - :param comment: str (optional) - The comment attached to the volume - :param storage_location: str (optional) - The storage location on the cloud - - :returns: :class:`VolumeInfo` - + +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 + The name of the schema where the volume is +:param name: str + The name of the volume +:param volume_type: :class:`VolumeType` +:param comment: str (optional) + 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 - - - + +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] @@ -127,42 +127,42 @@ 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 - The identifier of the schema - :param include_browse: bool (optional) - Whether to include volumes in the response for which the principal can only access selective - 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` - + +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 + The identifier of the schema +:param include_browse: bool (optional) + Whether to include volumes in the response for which the principal can only access selective + 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` + .. py:method:: read(name: str [, include_browse: Optional[bool]]) -> VolumeInfo @@ -210,21 +210,21 @@ 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` - + +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` + .. py:method:: update(name: str [, comment: Optional[str], new_name: Optional[str], owner: Optional[str]]) -> VolumeInfo @@ -274,23 +274,22 @@ 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) - The comment attached to the volume - :param new_name: str (optional) - 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 + +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) + The comment attached to the volume +:param new_name: str (optional) + New name for the volume. +:param owner: str (optional) + The identifier of the user who owns the volume + +:returns: :class:`VolumeInfo` diff --git a/docs/workspace/catalog/workspace_bindings.rst b/docs/workspace/catalog/workspace_bindings.rst index 08a74b29e..32f218d00 100644 --- a/docs/workspace/catalog/workspace_bindings.rst +++ b/docs/workspace/catalog/workspace_bindings.rst @@ -5,19 +5,19 @@ .. py:class:: WorkspaceBindingsAPI 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 +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 @@ -40,37 +40,37 @@ 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` - + +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 - The name of the securable. - :param max_results: int (optional) - Maximum number of workspace bindings 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 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` - + +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 + The name of the securable. +:param max_results: int (optional) + Maximum number of workspace bindings 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 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` + .. py:method:: update(name: str [, assign_workspaces: Optional[List[int]], unassign_workspaces: Optional[List[int]]]) -> CurrentWorkspaceBindings @@ -96,35 +96,34 @@ 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` - + +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 - The name of the securable. - :param add: List[:class:`WorkspaceBinding`] (optional) - List of workspace bindings - :param remove: List[:class:`WorkspaceBinding`] (optional) - List of workspace bindings - - :returns: :class:`WorkspaceBindingsResponse` - \ No newline at end of file + +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 + The name of the securable. +:param add: List[:class:`WorkspaceBinding`] (optional) + List of workspace bindings +:param remove: List[:class:`WorkspaceBinding`] (optional) + List of workspace bindings + +:returns: :class:`WorkspaceBindingsResponse` diff --git a/docs/workspace/cleanrooms/clean_room_assets.rst b/docs/workspace/cleanrooms/clean_room_assets.rst index fe282543a..e58981eb9 100644 --- a/docs/workspace/cleanrooms/clean_room_assets.rst +++ b/docs/workspace/cleanrooms/clean_room_assets.rst @@ -5,90 +5,89 @@ .. py:class:: CleanRoomAssetsAPI Clean room assets are data and code objects — Tables, volumes, and notebooks that are shared with the - clean room. +clean room. .. 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` - + +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. - - - + +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` - + +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` - + +: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` - The type of the asset. - :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 + +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` + The type of the asset. +: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` diff --git a/docs/workspace/cleanrooms/clean_room_task_runs.rst b/docs/workspace/cleanrooms/clean_room_task_runs.rst index dcf59037c..f8c421231 100644 --- a/docs/workspace/cleanrooms/clean_room_task_runs.rst +++ b/docs/workspace/cleanrooms/clean_room_task_runs.rst @@ -9,17 +9,16 @@ .. 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 - :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 + +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 +:param page_token: str (optional) + Opaque pagination token to go to next page based on previous query. + +:returns: Iterator over :class:`CleanRoomNotebookTaskRun` diff --git a/docs/workspace/cleanrooms/clean_rooms.rst b/docs/workspace/cleanrooms/clean_rooms.rst index 0d1468399..8a8878a13 100644 --- a/docs/workspace/cleanrooms/clean_rooms.rst +++ b/docs/workspace/cleanrooms/clean_rooms.rst @@ -5,90 +5,89 @@ .. py:class:: CleanRoomsAPI A clean room uses Delta Sharing and serverless compute to provide a secure and privacy-protecting - environment where multiple parties can work together on sensitive enterprise data without direct access to - each other’s data. +environment where multiple parties can work together on sensitive enterprise data without direct access to +each other’s data. .. 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 cluster will be in a PROVISIONING state. - The cluster 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` - + +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 cluster will be in a PROVISIONING state. +The cluster 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` - + +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. - - - + +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` - + +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` - + +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 + +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` diff --git a/docs/workspace/compute/cluster_policies.rst b/docs/workspace/compute/cluster_policies.rst index 65066964c..0ea0dc1fa 100644 --- a/docs/workspace/compute/cluster_policies.rst +++ b/docs/workspace/compute/cluster_policies.rst @@ -5,22 +5,22 @@ .. py:class:: ClusterPoliciesAPI 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. +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. .. py:method:: create( [, 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]]) -> CreatePolicyResponse @@ -48,53 +48,53 @@ 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. - :param libraries: List[:class:`Library`] (optional) - A list of libraries to be installed on the next cluster restart that uses this policy. The maximum - number of libraries is 500. - :param max_clusters_per_user: int (optional) - Max number of clusters per user that can be active using this policy. If not present, there is no - max limit. - :param name: str (optional) - Cluster Policy name requested by the user. This has to be unique. Length must be between 1 and 100 - characters. - :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` - + +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. +:param libraries: List[:class:`Library`] (optional) + A list of libraries to be installed on the next cluster restart that uses this policy. The maximum + number of libraries is 500. +:param max_clusters_per_user: int (optional) + Max number of clusters per user that can be active using this policy. If not present, there is no + max limit. +:param name: str (optional) + Cluster Policy name requested by the user. This has to be unique. Length must be between 1 and 100 + characters. +: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. - - - + +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]]) @@ -134,44 +134,44 @@ 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. - :param libraries: List[:class:`Library`] (optional) - A list of libraries to be installed on the next cluster restart that uses this policy. The maximum - number of libraries is 500. - :param max_clusters_per_user: int (optional) - Max number of clusters per user that can be active using this policy. If not present, there is no - max limit. - :param name: str (optional) - Cluster Policy name requested by the user. This has to be unique. Length must be between 1 and 100 - characters. - :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. - - - + +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. +:param libraries: List[:class:`Library`] (optional) + A list of libraries to be installed on the next cluster restart that uses this policy. The maximum + number of libraries is 500. +:param max_clusters_per_user: int (optional) + Max number of clusters per user that can be active using this policy. If not present, there is no + max limit. +:param name: str (optional) + Cluster Policy name requested by the user. This has to be unique. Length must be between 1 and 100 + characters. +: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 @@ -201,39 +201,39 @@ 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` - + +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` - + +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` - + +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` + .. py:method:: list( [, sort_column: Optional[ListSortColumn], sort_order: Optional[ListSortOrder]]) -> Iterator[Policy] @@ -250,43 +250,42 @@ 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` - + +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` - + +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 + +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` diff --git a/docs/workspace/compute/clusters.rst b/docs/workspace/compute/clusters.rst index 24fe2d253..dbab6b79c 100644 --- a/docs/workspace/compute/clusters.rst +++ b/docs/workspace/compute/clusters.rst @@ -5,25 +5,25 @@ .. 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. + +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. .. py:method:: change_owner(cluster_id: str, owner_username: str) @@ -58,20 +58,20 @@ 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], 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]], workload_type: Optional[WorkloadType]]) -> Wait[ClusterDetails] + +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] Usage: @@ -99,151 +99,173 @@ 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. - :param apply_policy_default_values: bool (optional) - When set to true, fixed and default values from the policy will be used for fields that are omitted. - When set to false, only fixed values from the policy will be applied. - :param autoscale: :class:`AutoScale` (optional) - Parameters needed in order to automatically scale clusters up and down based on load. Note: - autoscaling works best with DB runtime versions 3.0 or later. - :param autotermination_minutes: int (optional) - Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this - cluster will not be automatically terminated. If specified, the threshold must be between 10 and - 10000 minutes. Users can also set this value to 0 to explicitly disable automatic termination. - :param aws_attributes: :class:`AwsAttributes` (optional) - Attributes related to clusters running on Amazon Web Services. If not specified at cluster creation, - a set of default values will be used. - :param azure_attributes: :class:`AzureAttributes` (optional) - Attributes related to clusters running on Microsoft Azure. If not specified at cluster creation, a - set of default values will be used. - :param clone_from: :class:`CloneCluster` (optional) - When specified, this clones libraries from a source cluster during the creation of a new cluster. - :param cluster_log_conf: :class:`ClusterLogConf` (optional) - The configuration for delivering spark logs to a long-term storage destination. Two kinds of - destinations (dbfs and s3) are supported. Only one destination can be specified for one cluster. If - the conf is given, the logs will be delivered to the destination every `5 mins`. The destination of - driver logs is `$destination/$clusterId/driver`, while the destination of executor logs is - `$destination/$clusterId/executor`. - :param cluster_name: str (optional) - Cluster name requested by the user. This doesn't have to be unique. If not specified at creation, - the cluster name will be an empty string. - :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. - - * `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. - :param docker_image: :class:`DockerImage` (optional) - :param driver_instance_pool_id: str (optional) - The optional ID of the instance pool for the driver of the cluster belongs. The pool cluster uses - the instance pool with id (instance_pool_id) if the driver pool is not assigned. - :param driver_node_type_id: str (optional) - The node type of the Spark driver. Note that this field is optional; if unset, the driver node type - will be set as the same value as `node_type_id` defined above. - :param enable_elastic_disk: bool (optional) - Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space - when its Spark workers are running low on disk space. This feature requires specific AWS permissions - to function correctly - refer to the User Guide for more details. - :param enable_local_disk_encryption: bool (optional) - Whether to enable LUKS on cluster VMs' local disks - :param gcp_attributes: :class:`GcpAttributes` (optional) - Attributes related to clusters running on Google Cloud Platform. If not specified at cluster - creation, a set of default values will be used. - :param init_scripts: List[:class:`InitScriptInfo`] (optional) - The configuration for storing init scripts. Any number of destinations can be specified. The scripts - are executed sequentially in the order provided. If `cluster_log_conf` is specified, init script - logs are sent to `//init_scripts`. - :param instance_pool_id: str (optional) - The optional ID of the instance pool to which the cluster belongs. - :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 - intensive workloads. A list of available node types can be retrieved by using the - :method:clusters/listNodeTypes API call. - :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. - :param policy_id: str (optional) - 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) - Single user name if data_security_mode is `SINGLE_USER` - :param spark_conf: Dict[str,str] (optional) - An object containing a set of optional, user-specified Spark configuration key-value pairs. Users - can also pass in a string of extra JVM options to the driver and the executors via - `spark.driver.extraJavaOptions` and `spark.executor.extraJavaOptions` respectively. - :param spark_env_vars: Dict[str,str] (optional) - 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"}` - :param ssh_public_keys: List[str] (optional) - SSH public key contents that will be added to each Spark node in this cluster. The corresponding - private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be - specified. - :param workload_type: :class:`WorkloadType` (optional) - - :returns: - Long-running operation waiter for :class:`ClusterDetails`. - See :method:wait_get_cluster_running for more details. - - - .. py:method:: create_and_wait(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], 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]], workload_type: Optional[WorkloadType], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails + +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. +:param apply_policy_default_values: bool (optional) + When set to true, fixed and default values from the policy will be used for fields that are omitted. + When set to false, only fixed values from the policy will be applied. +:param autoscale: :class:`AutoScale` (optional) + Parameters needed in order to automatically scale clusters up and down based on load. Note: + autoscaling works best with DB runtime versions 3.0 or later. +:param autotermination_minutes: int (optional) + Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this + cluster will not be automatically terminated. If specified, the threshold must be between 10 and + 10000 minutes. Users can also set this value to 0 to explicitly disable automatic termination. +:param aws_attributes: :class:`AwsAttributes` (optional) + Attributes related to clusters running on Amazon Web Services. If not specified at cluster creation, + a set of default values will be used. +:param azure_attributes: :class:`AzureAttributes` (optional) + Attributes related to clusters running on Microsoft Azure. If not specified at cluster creation, a + set of default values will be used. +:param clone_from: :class:`CloneCluster` (optional) + When specified, this clones libraries from a source cluster during the creation of a new cluster. +:param cluster_log_conf: :class:`ClusterLogConf` (optional) + The configuration for delivering spark logs to a long-term storage destination. Two kinds of + destinations (dbfs and s3) are supported. Only one destination can be specified for one cluster. If + the conf is given, the logs will be delivered to the destination every `5 mins`. The destination of + driver logs is `$destination/$clusterId/driver`, while the destination of executor logs is + `$destination/$clusterId/executor`. +:param cluster_name: str (optional) + Cluster name requested by the user. This doesn't have to be unique. If not specified at creation, + the cluster name will be an empty string. +: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. * + `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. +:param docker_image: :class:`DockerImage` (optional) +:param driver_instance_pool_id: str (optional) + The optional ID of the instance pool for the driver of the cluster belongs. The pool cluster uses + the instance pool with id (instance_pool_id) if the driver pool is not assigned. +:param driver_node_type_id: str (optional) + The node type of the Spark driver. Note that this field is optional; if unset, the driver node type + will be set as the same value as `node_type_id` defined above. +:param enable_elastic_disk: bool (optional) + Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space + when its Spark workers are running low on disk space. This feature requires specific AWS permissions + to function correctly - refer to the User Guide for more details. +:param enable_local_disk_encryption: bool (optional) + Whether to enable LUKS on cluster VMs' local disks +:param gcp_attributes: :class:`GcpAttributes` (optional) + Attributes related to clusters running on Google Cloud Platform. If not specified at cluster + creation, a set of default values will be used. +:param init_scripts: List[:class:`InitScriptInfo`] (optional) + The configuration for storing init scripts. Any number of destinations can be specified. The scripts + are executed sequentially in the order provided. If `cluster_log_conf` is specified, init script + logs are sent to `//init_scripts`. +: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`. + + 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`. +: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 + intensive workloads. A list of available node types can be retrieved by using the + :method:clusters/listNodeTypes API call. +: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. +:param policy_id: str (optional) + 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) + Single user name if data_security_mode is `SINGLE_USER` +:param spark_conf: Dict[str,str] (optional) + An object containing a set of optional, user-specified Spark configuration key-value pairs. Users + can also pass in a string of extra JVM options to the driver and the executors via + `spark.driver.extraJavaOptions` and `spark.executor.extraJavaOptions` respectively. +:param spark_env_vars: Dict[str,str] (optional) + 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"}` +:param ssh_public_keys: List[str] (optional) + SSH public key contents that will be added to each Spark node in this cluster. The corresponding + 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`. + + `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. + + + .. py:method:: create_and_wait(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], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails .. py:method:: delete(cluster_id: str) -> Wait[ClusterDetails] @@ -276,23 +298,23 @@ 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. - + +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. + .. py:method:: delete_and_wait(cluster_id: str, timeout: datetime.timedelta = 0:20:00) -> ClusterDetails - .. py:method:: edit(cluster_id: str, spark_version: str [, apply_policy_default_values: Optional[bool], autoscale: Optional[AutoScale], autotermination_minutes: Optional[int], aws_attributes: Optional[AwsAttributes], azure_attributes: Optional[AzureAttributes], 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], 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]], workload_type: Optional[WorkloadType]]) -> Wait[ClusterDetails] + .. py:method:: edit(cluster_id: str, spark_version: str [, apply_policy_default_values: Optional[bool], autoscale: Optional[AutoScale], autotermination_minutes: Optional[int], aws_attributes: Optional[AwsAttributes], azure_attributes: Optional[AzureAttributes], 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] Usage: @@ -327,151 +349,173 @@ 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 - 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. - :param apply_policy_default_values: bool (optional) - When set to true, fixed and default values from the policy will be used for fields that are omitted. - When set to false, only fixed values from the policy will be applied. - :param autoscale: :class:`AutoScale` (optional) - Parameters needed in order to automatically scale clusters up and down based on load. Note: - autoscaling works best with DB runtime versions 3.0 or later. - :param autotermination_minutes: int (optional) - Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this - cluster will not be automatically terminated. If specified, the threshold must be between 10 and - 10000 minutes. Users can also set this value to 0 to explicitly disable automatic termination. - :param aws_attributes: :class:`AwsAttributes` (optional) - Attributes related to clusters running on Amazon Web Services. If not specified at cluster creation, - a set of default values will be used. - :param azure_attributes: :class:`AzureAttributes` (optional) - Attributes related to clusters running on Microsoft Azure. If not specified at cluster creation, a - set of default values will be used. - :param cluster_log_conf: :class:`ClusterLogConf` (optional) - The configuration for delivering spark logs to a long-term storage destination. Two kinds of - destinations (dbfs and s3) are supported. Only one destination can be specified for one cluster. If - the conf is given, the logs will be delivered to the destination every `5 mins`. The destination of - driver logs is `$destination/$clusterId/driver`, while the destination of executor logs is - `$destination/$clusterId/executor`. - :param cluster_name: str (optional) - Cluster name requested by the user. This doesn't have to be unique. If not specified at creation, - the cluster name will be an empty string. - :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. - - * `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. - :param docker_image: :class:`DockerImage` (optional) - :param driver_instance_pool_id: str (optional) - The optional ID of the instance pool for the driver of the cluster belongs. The pool cluster uses - the instance pool with id (instance_pool_id) if the driver pool is not assigned. - :param driver_node_type_id: str (optional) - The node type of the Spark driver. Note that this field is optional; if unset, the driver node type - will be set as the same value as `node_type_id` defined above. - :param enable_elastic_disk: bool (optional) - Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space - when its Spark workers are running low on disk space. This feature requires specific AWS permissions - to function correctly - refer to the User Guide for more details. - :param enable_local_disk_encryption: bool (optional) - Whether to enable LUKS on cluster VMs' local disks - :param gcp_attributes: :class:`GcpAttributes` (optional) - Attributes related to clusters running on Google Cloud Platform. If not specified at cluster - creation, a set of default values will be used. - :param init_scripts: List[:class:`InitScriptInfo`] (optional) - The configuration for storing init scripts. Any number of destinations can be specified. The scripts - are executed sequentially in the order provided. If `cluster_log_conf` is specified, init script - logs are sent to `//init_scripts`. - :param instance_pool_id: str (optional) - The optional ID of the instance pool to which the cluster belongs. - :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 - intensive workloads. A list of available node types can be retrieved by using the - :method:clusters/listNodeTypes API call. - :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. - :param policy_id: str (optional) - 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) - Single user name if data_security_mode is `SINGLE_USER` - :param spark_conf: Dict[str,str] (optional) - An object containing a set of optional, user-specified Spark configuration key-value pairs. Users - can also pass in a string of extra JVM options to the driver and the executors via - `spark.driver.extraJavaOptions` and `spark.executor.extraJavaOptions` respectively. - :param spark_env_vars: Dict[str,str] (optional) - 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"}` - :param ssh_public_keys: List[str] (optional) - SSH public key contents that will be added to each Spark node in this cluster. The corresponding - private keys can be used to login with the user name `ubuntu` on port `2200`. Up to 10 keys can be - specified. - :param workload_type: :class:`WorkloadType` (optional) - - :returns: - Long-running operation waiter for :class:`ClusterDetails`. - See :method:wait_get_cluster_running for more details. - - - .. py:method:: edit_and_wait(cluster_id: str, spark_version: str [, apply_policy_default_values: Optional[bool], autoscale: Optional[AutoScale], autotermination_minutes: Optional[int], aws_attributes: Optional[AwsAttributes], azure_attributes: Optional[AzureAttributes], 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], 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]], workload_type: Optional[WorkloadType], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails + +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 + 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. +:param apply_policy_default_values: bool (optional) + When set to true, fixed and default values from the policy will be used for fields that are omitted. + When set to false, only fixed values from the policy will be applied. +:param autoscale: :class:`AutoScale` (optional) + Parameters needed in order to automatically scale clusters up and down based on load. Note: + autoscaling works best with DB runtime versions 3.0 or later. +:param autotermination_minutes: int (optional) + Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this + cluster will not be automatically terminated. If specified, the threshold must be between 10 and + 10000 minutes. Users can also set this value to 0 to explicitly disable automatic termination. +:param aws_attributes: :class:`AwsAttributes` (optional) + Attributes related to clusters running on Amazon Web Services. If not specified at cluster creation, + a set of default values will be used. +:param azure_attributes: :class:`AzureAttributes` (optional) + Attributes related to clusters running on Microsoft Azure. If not specified at cluster creation, a + set of default values will be used. +:param cluster_log_conf: :class:`ClusterLogConf` (optional) + The configuration for delivering spark logs to a long-term storage destination. Two kinds of + destinations (dbfs and s3) are supported. Only one destination can be specified for one cluster. If + the conf is given, the logs will be delivered to the destination every `5 mins`. The destination of + driver logs is `$destination/$clusterId/driver`, while the destination of executor logs is + `$destination/$clusterId/executor`. +:param cluster_name: str (optional) + Cluster name requested by the user. This doesn't have to be unique. If not specified at creation, + the cluster name will be an empty string. +: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. * + `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. +:param docker_image: :class:`DockerImage` (optional) +:param driver_instance_pool_id: str (optional) + The optional ID of the instance pool for the driver of the cluster belongs. The pool cluster uses + the instance pool with id (instance_pool_id) if the driver pool is not assigned. +:param driver_node_type_id: str (optional) + The node type of the Spark driver. Note that this field is optional; if unset, the driver node type + will be set as the same value as `node_type_id` defined above. +:param enable_elastic_disk: bool (optional) + Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space + when its Spark workers are running low on disk space. This feature requires specific AWS permissions + to function correctly - refer to the User Guide for more details. +:param enable_local_disk_encryption: bool (optional) + Whether to enable LUKS on cluster VMs' local disks +:param gcp_attributes: :class:`GcpAttributes` (optional) + Attributes related to clusters running on Google Cloud Platform. If not specified at cluster + creation, a set of default values will be used. +:param init_scripts: List[:class:`InitScriptInfo`] (optional) + The configuration for storing init scripts. Any number of destinations can be specified. The scripts + are executed sequentially in the order provided. If `cluster_log_conf` is specified, init script + logs are sent to `//init_scripts`. +: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`. + + 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`. +: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 + intensive workloads. A list of available node types can be retrieved by using the + :method:clusters/listNodeTypes API call. +: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. +:param policy_id: str (optional) + 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) + Single user name if data_security_mode is `SINGLE_USER` +:param spark_conf: Dict[str,str] (optional) + An object containing a set of optional, user-specified Spark configuration key-value pairs. Users + can also pass in a string of extra JVM options to the driver and the executors via + `spark.driver.extraJavaOptions` and `spark.executor.extraJavaOptions` respectively. +:param spark_env_vars: Dict[str,str] (optional) + 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"}` +:param ssh_public_keys: List[str] (optional) + SSH public key contents that will be added to each Spark node in this cluster. The corresponding + 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`. + + `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. + + + .. py:method:: edit_and_wait(cluster_id: str, spark_version: str [, apply_policy_default_values: Optional[bool], autoscale: Optional[AutoScale], autotermination_minutes: Optional[int], aws_attributes: Optional[AwsAttributes], azure_attributes: Optional[AzureAttributes], 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], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails .. py:method:: ensure_cluster_is_running(cluster_id: str) @@ -529,30 +573,30 @@ 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) - The end time in epoch milliseconds. If empty, returns events up to the current time. - :param event_types: List[:class:`EventType`] (optional) - An optional set of event types to filter on. If empty, all event types are returned. - :param limit: int (optional) - The maximum number of events to include in a page of events. Defaults to 50, and maximum allowed - value is 500. - :param offset: int (optional) - The offset in the result set. Defaults to 0 (no offset). When an offset is specified and the results - are requested in descending order, the end_time field is required. - :param order: :class:`GetEventsOrder` (optional) - 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` - + +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) + The end time in epoch milliseconds. If empty, returns events up to the current time. +:param event_types: List[:class:`EventType`] (optional) + An optional set of event types to filter on. If empty, all event types are returned. +:param limit: int (optional) + The maximum number of events to include in a page of events. Defaults to 50, and maximum allowed + value is 500. +:param offset: int (optional) + The offset in the result set. Defaults to 0 (no offset). When an offset is specified and the results + are requested in descending order, the end_time field is required. +:param order: :class:`GetEventsOrder` (optional) + 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` + .. py:method:: get(cluster_id: str) -> ClusterDetails @@ -584,39 +628,39 @@ 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` - + +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` - + +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` - + +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` + .. py:method:: list( [, filter_by: Optional[ListClustersFilterBy], page_size: Optional[int], page_token: Optional[str], sort_by: Optional[ListClustersSortBy]]) -> Iterator[ClusterDetails] @@ -633,23 +677,23 @@ 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) - Use this field to specify the maximum number of results to be returned by the server. The server may - further constrain the maximum number of results returned in a single page. - :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 clusters respectively. - :param sort_by: :class:`ListClustersSortBy` (optional) - Sort the list of clusters by a specific criteria. - - :returns: Iterator over :class:`ClusterDetails` - + +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) + Use this field to specify the maximum number of results to be returned by the server. The server may + further constrain the maximum number of results returned in a single page. +: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 clusters respectively. +:param sort_by: :class:`ListClustersSortBy` (optional) + Sort the list of clusters by a specific criteria. + +:returns: Iterator over :class:`ClusterDetails` + .. py:method:: list_node_types() -> ListNodeTypesResponse @@ -665,37 +709,37 @@ 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` - + +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` - + +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. - - - + +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) @@ -727,15 +771,15 @@ 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 - - - - + +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] @@ -767,29 +811,29 @@ 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) - Parameters needed in order to automatically scale clusters up and down based on load. Note: - autoscaling works best with DB runtime versions 3.0 or later. - :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. - + +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) + Parameters needed in order to automatically scale clusters up and down based on load. Note: + autoscaling works best with DB runtime versions 3.0 or later. +: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. + .. py:method:: resize_and_wait(cluster_id: str [, autoscale: Optional[AutoScale], num_workers: Optional[int], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails @@ -824,19 +868,19 @@ 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. - + +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. + .. py:method:: restart_and_wait(cluster_id: str [, restart_user: Optional[str], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails @@ -856,22 +900,22 @@ Selects smallest available node type given the conditions. - :param min_memory_gb: int - :param gb_per_core: int - :param min_cores: int - :param min_gpus: int - :param local_disk: bool - :param local_disk_min_size: bool - :param category: bool - :param photon_worker_capable: bool - :param photon_driver_capable: bool - :param graviton: bool - :param is_io_cache_enabled: bool - :param support_port_forwarding: bool - :param fleet: bool - - :returns: `node_type` compatible string - +:param min_memory_gb: int +:param gb_per_core: int +:param min_cores: int +:param min_gpus: int +:param local_disk: bool +:param local_disk_min_size: bool +:param category: bool +:param photon_worker_capable: bool +:param photon_driver_capable: bool +:param graviton: bool +:param is_io_cache_enabled: bool +:param support_port_forwarding: bool +:param fleet: bool + +:returns: `node_type` compatible string + .. py:method:: select_spark_version(long_term_support: bool = False, beta: bool = False, latest: bool = True, ml: bool = False, genomics: bool = False, gpu: bool = False, scala: str = 2.12, spark_version: str, photon: bool = False, graviton: bool = False) -> str @@ -888,42 +932,42 @@ Selects the latest Databricks Runtime Version. - :param long_term_support: bool - :param beta: bool - :param latest: bool - :param ml: bool - :param genomics: bool - :param gpu: bool - :param scala: str - :param spark_version: str - :param photon: bool - :param graviton: bool +:param long_term_support: bool +:param beta: bool +:param latest: bool +:param ml: bool +:param genomics: bool +:param gpu: bool +:param scala: str +:param spark_version: str +:param photon: bool +:param graviton: bool + +:returns: `spark_version` compatible string - :returns: `spark_version` compatible string - .. 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` - + +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` - + +Returns the list of available Spark versions. These versions can be used to launch a cluster. + +:returns: :class:`GetSparkVersionsResponse` + .. py:method:: start(cluster_id: str) -> Wait[ClusterDetails] @@ -955,21 +999,21 @@ 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. - + +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. + .. py:method:: start_and_wait(cluster_id: str, timeout: datetime.timedelta = 0:20:00) -> ClusterDetails @@ -1004,44 +1048,44 @@ 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 - - - - + +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 - restarted so that the new attributes can take effect. If a cluster is updated while in a `TERMINATED` - state, it will remain `TERMINATED`. The updated attributes will take effect the next time the cluster - 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 - Specifies which fields of the cluster will be updated. This is required in the POST request. The - update mask should be supplied as a single string. To specify multiple fields, separate them with - commas (no spaces). To delete a field from a cluster configuration, add it to the `update_mask` - 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. - + +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 +restarted so that the new attributes can take effect. If a cluster is updated while in a `TERMINATED` +state, it will remain `TERMINATED`. The updated attributes will take effect the next time the cluster +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 + Specifies which fields of the cluster will be updated. This is required in the POST request. The + update mask should be supplied as a single string. To specify multiple fields, separate them with + commas (no spaces). To delete a field from a cluster configuration, add it to the `update_mask` + 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. + .. py:method:: update_and_wait(cluster_id: str, update_mask: str [, cluster: Optional[UpdateClusterResource], timeout: datetime.timedelta = 0:20:00]) -> ClusterDetails @@ -1049,15 +1093,15 @@ .. 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` - + +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` + .. py:method:: wait_get_cluster_running(cluster_id: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[ClusterDetails], None]]) -> ClusterDetails diff --git a/docs/workspace/compute/command_execution.rst b/docs/workspace/compute/command_execution.rst index 916a48ba5..1b6f7e9fb 100644 --- a/docs/workspace/compute/command_execution.rst +++ b/docs/workspace/compute/command_execution.rst @@ -5,24 +5,24 @@ .. py:class:: CommandExecutionAPI This API allows execution of Python, Scala, SQL, or R commands on running Databricks Clusters. This API - only supports (classic) all-purpose clusters. Serverless compute is not supported. +only supports (classic) all-purpose clusters. Serverless compute is not supported. .. 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. - + +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. + .. py:method:: cancel_and_wait( [, cluster_id: Optional[str], command_id: Optional[str], context_id: Optional[str], timeout: datetime.timedelta = 0:20:00]) -> CommandStatusResponse @@ -30,29 +30,29 @@ .. 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` - + +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` - + +Gets the status for an execution context. + +:param cluster_id: str +:param context_id: str + +:returns: :class:`ContextStatusResponse` + .. py:method:: create( [, cluster_id: Optional[str], language: Optional[Language]]) -> Wait[ContextStatusResponse] @@ -76,19 +76,19 @@ 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. - + +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. + .. py:method:: create_and_wait( [, cluster_id: Optional[str], language: Optional[Language], timeout: datetime.timedelta = 0:20:00]) -> ContextStatusResponse @@ -96,14 +96,14 @@ .. 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 - - - + +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] @@ -132,23 +132,23 @@ 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) - Executable code - :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. - + +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) + Executable code +: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. + .. py:method:: execute_and_wait( [, cluster_id: Optional[str], command: Optional[str], context_id: Optional[str], language: Optional[Language], timeout: datetime.timedelta = 0:20:00]) -> CommandStatusResponse diff --git a/docs/workspace/compute/global_init_scripts.rst b/docs/workspace/compute/global_init_scripts.rst index 9d2372a6d..62d5e16c4 100644 --- a/docs/workspace/compute/global_init_scripts.rst +++ b/docs/workspace/compute/global_init_scripts.rst @@ -5,12 +5,12 @@ .. py:class:: GlobalInitScriptsAPI 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 - entire cluster fails with a `GLOBAL_INIT_SCRIPT_FAILURE` error code. +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 +entire cluster fails with a `GLOBAL_INIT_SCRIPT_FAILURE` error code. .. py:method:: create(name: str, script: str [, enabled: Optional[bool], position: Optional[int]]) -> CreateResponse @@ -35,40 +35,40 @@ 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 - The Base64-encoded content of the script. - :param enabled: bool (optional) - Specifies whether the script is enabled. The script runs only if enabled. - :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` - + +Creates a new global init script in this workspace. + +:param name: str + The name of the script +:param script: str + The Base64-encoded content of the script. +:param enabled: bool (optional) + Specifies whether the script is enabled. The script runs only if enabled. +: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. - - - + +Deletes a global init script. + +:param script_id: str + The ID of the global init script. + + + .. py:method:: get(script_id: str) -> GlobalInitScriptDetailsWithContent @@ -95,14 +95,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[GlobalInitScriptDetails] @@ -118,13 +118,13 @@ 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` - + +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` + .. py:method:: update(script_id: str, name: str, script: str [, enabled: Optional[bool], position: Optional[int]]) @@ -153,28 +153,27 @@ 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 - The name of the script - :param script: str - The Base64-encoded content of the script. - :param enabled: bool (optional) - Specifies whether the script is enabled. The script runs only if enabled. - :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 + +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 + The name of the script +:param script: str + The Base64-encoded content of the script. +:param enabled: bool (optional) + Specifies whether the script is enabled. The script runs only if enabled. +: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. + + diff --git a/docs/workspace/compute/instance_pools.rst b/docs/workspace/compute/instance_pools.rst index 333c44938..61c55d0e0 100644 --- a/docs/workspace/compute/instance_pools.rst +++ b/docs/workspace/compute/instance_pools.rst @@ -5,19 +5,19 @@ .. py:class:: InstancePoolsAPI 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. +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. .. py:method:: create(instance_pool_name: str, node_type_id: str [, aws_attributes: Optional[InstancePoolAwsAttributes], azure_attributes: Optional[InstancePoolAzureAttributes], custom_tags: Optional[Dict[str, str]], disk_spec: Optional[DiskSpec], enable_elastic_disk: Optional[bool], gcp_attributes: Optional[InstancePoolGcpAttributes], idle_instance_autotermination_minutes: Optional[int], max_capacity: Optional[int], min_idle_instances: Optional[int], preloaded_docker_images: Optional[List[DockerImage]], preloaded_spark_versions: Optional[List[str]]]) -> CreateInstancePoolResponse @@ -40,70 +40,70 @@ 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. - :param node_type_id: str - 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 - intensive workloads. A list of available node types can be retrieved by using the - :method:clusters/listNodeTypes API call. - :param aws_attributes: :class:`InstancePoolAwsAttributes` (optional) - Attributes related to instance pools running on Amazon Web Services. If not specified at pool - creation, a set of default values will be used. - :param azure_attributes: :class:`InstancePoolAzureAttributes` (optional) - Attributes related to instance pools running on Azure. If not specified at pool creation, a set of - default values will be used. - :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. - :param enable_elastic_disk: bool (optional) - Autoscaling Local Storage: when enabled, this instances in this pool will dynamically acquire - additional disk space when its Spark workers are running low on disk space. In AWS, this feature - requires specific AWS permissions to function correctly - refer to the User Guide for more details. - :param gcp_attributes: :class:`InstancePoolGcpAttributes` (optional) - Attributes related to instance pools running on Google Cloud Platform. If not specified at pool - creation, a set of default values will be used. - :param idle_instance_autotermination_minutes: int (optional) - Automatically terminates the extra instances in the pool cache after they are inactive for this time - in minutes if min_idle_instances requirement is already met. If not set, the extra pool instances - will be automatically terminated after a default timeout. If specified, the threshold must be - between 0 and 10000 minutes. Users can also set this value to 0 to instantly remove idle instances - from the cache if min cache size could still hold. - :param max_capacity: int (optional) - Maximum number of outstanding instances to keep in the pool, including both instances used by - clusters and idle instances. Clusters that require further instance provisioning will fail during - upsize requests. - :param min_idle_instances: int (optional) - Minimum number of idle instances to keep in the instance pool - :param preloaded_docker_images: List[:class:`DockerImage`] (optional) - Custom Docker Image BYOC - :param preloaded_spark_versions: List[str] (optional) - 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` - + +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. +:param node_type_id: str + 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 + intensive workloads. A list of available node types can be retrieved by using the + :method:clusters/listNodeTypes API call. +:param aws_attributes: :class:`InstancePoolAwsAttributes` (optional) + Attributes related to instance pools running on Amazon Web Services. If not specified at pool + creation, a set of default values will be used. +:param azure_attributes: :class:`InstancePoolAzureAttributes` (optional) + Attributes related to instance pools running on Azure. If not specified at pool creation, a set of + default values will be used. +: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. +:param enable_elastic_disk: bool (optional) + Autoscaling Local Storage: when enabled, this instances in this pool will dynamically acquire + additional disk space when its Spark workers are running low on disk space. In AWS, this feature + requires specific AWS permissions to function correctly - refer to the User Guide for more details. +:param gcp_attributes: :class:`InstancePoolGcpAttributes` (optional) + Attributes related to instance pools running on Google Cloud Platform. If not specified at pool + creation, a set of default values will be used. +:param idle_instance_autotermination_minutes: int (optional) + Automatically terminates the extra instances in the pool cache after they are inactive for this time + in minutes if min_idle_instances requirement is already met. If not set, the extra pool instances + will be automatically terminated after a default timeout. If specified, the threshold must be + between 0 and 10000 minutes. Users can also set this value to 0 to instantly remove idle instances + from the cache if min cache size could still hold. +:param max_capacity: int (optional) + Maximum number of outstanding instances to keep in the pool, including both instances used by + clusters and idle instances. Clusters that require further instance provisioning will fail during + upsize requests. +:param min_idle_instances: int (optional) + Minimum number of idle instances to keep in the instance pool +:param preloaded_docker_images: List[:class:`DockerImage`] (optional) + Custom Docker Image BYOC +:param preloaded_spark_versions: List[str] (optional) + 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. - - - + +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]]) @@ -130,39 +130,39 @@ 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 - Pool name requested by the user. Pool name must be unique. Length must be between 1 and 100 - characters. - :param node_type_id: str - 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 - intensive workloads. A list of available node types can be retrieved by using the - :method:clusters/listNodeTypes API call. - :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 - in minutes if min_idle_instances requirement is already met. If not set, the extra pool instances - will be automatically terminated after a default timeout. If specified, the threshold must be - between 0 and 10000 minutes. Users can also set this value to 0 to instantly remove idle instances - from the cache if min cache size could still hold. - :param max_capacity: int (optional) - Maximum number of outstanding instances to keep in the pool, including both instances used by - clusters and idle instances. Clusters that require further instance provisioning will fail during - upsize requests. - :param min_idle_instances: int (optional) - Minimum number of idle instances to keep in the instance pool - - - + +Modifies the configuration of an existing instance pool. + +:param instance_pool_id: str + Instance pool ID +:param instance_pool_name: str + Pool name requested by the user. Pool name must be unique. Length must be between 1 and 100 + characters. +:param node_type_id: str + 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 + intensive workloads. A list of available node types can be retrieved by using the + :method:clusters/listNodeTypes API call. +: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 + in minutes if min_idle_instances requirement is already met. If not set, the extra pool instances + will be automatically terminated after a default timeout. If specified, the threshold must be + between 0 and 10000 minutes. Users can also set this value to 0 to instantly remove idle instances + from the cache if min cache size could still hold. +:param max_capacity: int (optional) + Maximum number of outstanding instances to keep in the pool, including both instances used by + clusters and idle instances. Clusters that require further instance provisioning will fail during + 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 @@ -187,39 +187,39 @@ 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` - + +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` - + +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` - + +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` + .. py:method:: list() -> Iterator[InstancePoolAndStats] @@ -235,36 +235,35 @@ all = w.instance_pools.list() List instance pool info. - - Gets a list of instance pools with their statistics. - - :returns: Iterator over :class:`InstancePoolAndStats` - + +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` - + +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 + +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` diff --git a/docs/workspace/compute/instance_profiles.rst b/docs/workspace/compute/instance_profiles.rst index a7a25f869..4b863deb8 100644 --- a/docs/workspace/compute/instance_profiles.rst +++ b/docs/workspace/compute/instance_profiles.rst @@ -5,10 +5,10 @@ .. py:class:: InstanceProfilesAPI 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 +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]]) @@ -28,34 +28,34 @@ 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 - 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`. - :param skip_validation: bool (optional) - By default, Databricks validates that it has sufficient permissions to launch instances with the - instance profile. This validation uses AWS dry-run mode for the RunInstances API. If validation - 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. - - - + +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 + 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`. +:param skip_validation: bool (optional) + By default, Databricks validates that it has sufficient permissions to launch instances with the + instance profile. This validation uses AWS dry-run mode for the RunInstances API. If validation + 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]]) @@ -73,38 +73,38 @@ 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`. - - - + +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 +120,24 @@ 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` - + +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 + +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. + + diff --git a/docs/workspace/compute/libraries.rst b/docs/workspace/compute/libraries.rst index 64f688fdc..305039e26 100644 --- a/docs/workspace/compute/libraries.rst +++ b/docs/workspace/compute/libraries.rst @@ -5,71 +5,70 @@ .. py:class:: LibrariesAPI 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. +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` - + +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` - + +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. - - - + +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 + +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. + + diff --git a/docs/workspace/compute/policy_compliance_for_clusters.rst b/docs/workspace/compute/policy_compliance_for_clusters.rst index 90c3aeb98..b22207cd3 100644 --- a/docs/workspace/compute/policy_compliance_for_clusters.rst +++ b/docs/workspace/compute/policy_compliance_for_clusters.rst @@ -5,67 +5,66 @@ .. py:class:: PolicyComplianceForClustersAPI 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. +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` - + +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` - + +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) - Use this field to specify the maximum number of results to be returned by the server. The server may - further constrain the maximum number of results returned in a single page. - :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 + +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) + Use this field to specify the maximum number of results to be returned by the server. The server may + further constrain the maximum number of results returned in a single page. +: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` diff --git a/docs/workspace/compute/policy_families.rst b/docs/workspace/compute/policy_families.rst index 56e4f4275..ad8061a91 100644 --- a/docs/workspace/compute/policy_families.rst +++ b/docs/workspace/compute/policy_families.rst @@ -5,14 +5,14 @@ .. py:class:: PolicyFamiliesAPI 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. +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. .. py:method:: get(policy_family_id: str [, version: Optional[int]]) -> PolicyFamily @@ -31,16 +31,16 @@ 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` - + +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` + .. py:method:: list( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[PolicyFamily] @@ -57,14 +57,13 @@ 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 + +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` diff --git a/docs/workspace/dashboards/genie.rst b/docs/workspace/dashboards/genie.rst index 5581870b9..9be9b5932 100644 --- a/docs/workspace/dashboards/genie.rst +++ b/docs/workspace/dashboards/genie.rst @@ -5,28 +5,28 @@ .. py:class:: GenieAPI Genie provides a no-code experience for business users, powered by AI/BI. Analysts set up spaces that - business users can use to ask questions using natural language. Genie uses data registered to Unity - Catalog and requires at least CAN USE permission on a Pro or Serverless SQL warehouse. Also, Databricks - Assistant must be enabled. +business users can use to ask questions using natural language. Genie uses data registered to Unity +Catalog and requires at least CAN USE permission on a Pro or Serverless SQL warehouse. Also, Databricks +Assistant must be enabled. .. 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 - 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. - + +Create new message in [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. + .. py:method:: create_message_and_wait(space_id: str, conversation_id: str, content: str, timeout: datetime.timedelta = 0:20:00) -> GenieMessage @@ -34,67 +34,67 @@ .. 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` - + +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` - + +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 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` - + +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:: 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. - + +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. + .. py:method:: start_conversation_and_wait(space_id: str, content: str, timeout: datetime.timedelta = 0:20:00) -> GenieMessage diff --git a/docs/workspace/dashboards/lakeview.rst b/docs/workspace/dashboards/lakeview.rst index b8dceeb9e..b8c64f15d 100644 --- a/docs/workspace/dashboards/lakeview.rst +++ b/docs/workspace/dashboards/lakeview.rst @@ -5,254 +5,256 @@ .. py:class:: LakeviewAPI These APIs provide specific management operations for Lakeview dashboards. Generic resource management can - be done with Workspace API (import, export, get-status, list, delete). +be done with Workspace API (import, export, get-status, list, delete). .. py:method:: create( [, dashboard: Optional[Dashboard]]) -> Dashboard Create dashboard. - - Create a draft dashboard. - - :param dashboard: :class:`Dashboard` (optional) - - :returns: :class:`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` - + +: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` - + +: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 - UUID identifying the schedule. - :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. - - - + +:param dashboard_id: str + UUID identifying the dashboard to which the schedule belongs. +:param schedule_id: str + UUID identifying the schedule. +: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 - UUID identifying the schedule which the subscription belongs. - :param subscription_id: str - UUID identifying the subscription. - :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. - - - + +: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. +: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` - + +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` - + +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` - + +: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` - + +: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) - A page token, received from a previous `ListDashboards` call. This token can be used to retrieve the - subsequent page. - :param show_trashed: bool (optional) - The flag to include dashboards located in the trash. If unspecified, only active dashboards will be - returned. - :param view: :class:`DashboardView` (optional) - `DASHBOARD_VIEW_BASIC`only includes summary metadata from the dashboard. - - :returns: Iterator over :class:`Dashboard` - + +:param page_size: int (optional) + The number of dashboards to return per page. +:param page_token: str (optional) + A page token, received from a previous `ListDashboards` call. This token can be used to retrieve the + subsequent page. +:param show_trashed: bool (optional) + The flag to include dashboards located in the trash. If unspecified, only active dashboards will be + 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) - The number of schedules to return per page. - :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` - + +:param dashboard_id: str + UUID identifying the dashboard to which the schedules belongs. +:param page_size: int (optional) + The number of schedules to return per page. +: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 - UUID identifying the schedule which the subscriptions belongs. - :param page_size: int (optional) - The number of subscriptions to return per page. - :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]]) -> Dashboard + +:param dashboard_id: str + UUID identifying the dashboard which the subscriptions belongs. +:param schedule_id: str + UUID identifying the schedule which the subscriptions belongs. +:param page_size: int (optional) + The number of subscriptions to return per page. +: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) - Display name for the new Lakeview dashboard. - :param parent_path: str (optional) - The workspace path of the folder to contain the migrated Lakeview dashboard. - - :returns: :class:`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) + Display name for the new Lakeview dashboard. +:param parent_path: str (optional) + The workspace path of the folder to contain the migrated Lakeview dashboard. +: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) - Flag to indicate if the publisher's credentials should be embedded in the published dashboard. These - 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` - + +Publish the current draft dashboard. + +:param dashboard_id: str + UUID identifying the dashboard to be published. +:param embed_credentials: bool (optional) + Flag to indicate if the publisher's credentials should be embedded in the published dashboard. These + 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. - - - + +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. - - - + +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` - + +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 + +: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` diff --git a/docs/workspace/files/dbfs.rst b/docs/workspace/files/dbfs.rst index c52d11bc8..e200363ac 100644 --- a/docs/workspace/files/dbfs.rst +++ b/docs/workspace/files/dbfs.rst @@ -5,37 +5,37 @@ .. py:class:: DbfsExt DBFS API makes it simple to interact with various data sources without having to include a users - credentials every time to read a file. +credentials every time to read a file. .. 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. - - - + +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. - - - + +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,23 +44,23 @@ .. 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` - + +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` + .. py:method:: delete(path: str [, recursive: bool = False]) @@ -98,30 +98,30 @@ .. 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` - + +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` + .. py:method:: list(path: str [, recursive: bool = False]) -> Iterator[files.FileInfo] List directory contents or file details. - List the contents of a directory, or details of the file. If the file or directory does not exist, - this call throws an exception with `RESOURCE_DOES_NOT_EXIST`. +List the contents of a directory, or details of the file. If the file or directory does not exist, +this call throws an exception with `RESOURCE_DOES_NOT_EXIST`. + +When calling list on a large directory, the list operation will time out after approximately 60 +seconds. - When calling list on a large directory, the list operation will time out after approximately 60 - seconds. +:param path: the DBFS or UC Volume path to list +:param recursive: traverse deep into directory tree +:returns iterator of metadata for every file - :param path: the DBFS or UC Volume path to list - :param recursive: traverse deep into directory tree - :returns iterator of metadata for every file - .. py:method:: mkdirs(path: str) @@ -130,19 +130,19 @@ .. 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. - - - + +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,50 +154,50 @@ .. 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. - - - + +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) - The number of bytes to read starting from the offset. This has a limit of 1 MB, and a default value - of 0.5 MB. - :param offset: int (optional) - The offset to read from in bytes. - - :returns: :class:`ReadResponse` - + +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) + The number of bytes to read starting from the offset. This has a limit of 1 MB, and a default value + of 0.5 MB. +:param offset: int (optional) + The offset to read from in bytes. + +:returns: :class:`ReadResponse` + .. py:method:: upload(path: str, src: BinaryIO [, overwrite: bool = False]) diff --git a/docs/workspace/files/files.rst b/docs/workspace/files/files.rst index f1bd70317..8402abb13 100644 --- a/docs/workspace/files/files.rst +++ b/docs/workspace/files/files.rst @@ -5,148 +5,147 @@ .. py:class:: FilesAPI 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. - - [Unity Catalog volumes]: https://docs.databricks.com/en/connect/unity-catalog/volumes.html +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. + +[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. - - - + +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. - - - + +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. - - - + +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` - + +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. - - - + +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` - + +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) - An opaque page token which was the `next_page_token` in the response of the previous request to list - the contents of this directory. Provide this token to retrieve the next page of directory entries. - When providing a `page_token`, all other parameters provided to the request must match the previous - 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` - + +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) + An opaque page token which was the `next_page_token` in the response of the previous request to list + the contents of this directory. Provide this token to retrieve the next page of directory entries. + When providing a `page_token`, all other parameters provided to the request must match the previous + 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 + +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. + + diff --git a/docs/workspace/iam/account_access_control_proxy.rst b/docs/workspace/iam/account_access_control_proxy.rst index 3265b29cc..3242b7944 100644 --- a/docs/workspace/iam/account_access_control_proxy.rst +++ b/docs/workspace/iam/account_access_control_proxy.rst @@ -5,52 +5,51 @@ .. py:class:: AccountAccessControlProxyAPI These APIs manage access rules on resources in an account. Currently, only grant rules are supported. A - grant rule specifies a role assigned to a set of principals. A list of rules attached to a resource is - called a rule set. A workspace must belong to an account for these APIs to work. +grant rule specifies a role assigned to a set of principals. A list of rules attached to a resource is +called a rule set. A workspace must belong to an account for these APIs to work. .. 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` - + +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 - Etag used for versioning. The response is at least as fresh as the eTag provided. Etag is used for - optimistic concurrency control as a way to help prevent simultaneous updates of a rule set from - overwriting each other. It is strongly suggested that systems make use of the etag in the read -> - 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` - + +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 + Etag used for versioning. The response is at least as fresh as the eTag provided. Etag is used for + optimistic concurrency control as a way to help prevent simultaneous updates of a rule set from + overwriting each other. It is strongly suggested that systems make use of the etag in the read -> + 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 + +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` diff --git a/docs/workspace/iam/current_user.rst b/docs/workspace/iam/current_user.rst index 47ef1eff3..6a877bb2f 100644 --- a/docs/workspace/iam/current_user.rst +++ b/docs/workspace/iam/current_user.rst @@ -20,8 +20,7 @@ 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 + +Get details about the current method caller's identity. + +:returns: :class:`User` diff --git a/docs/workspace/iam/groups.rst b/docs/workspace/iam/groups.rst index ef32112c8..98ece2ad1 100644 --- a/docs/workspace/iam/groups.rst +++ b/docs/workspace/iam/groups.rst @@ -5,11 +5,11 @@ .. py:class:: GroupsAPI 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. +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. .. 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 @@ -30,30 +30,30 @@ 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) - :param id: str (optional) - Databricks group ID - :param members: List[:class:`ComplexValue`] (optional) - :param meta: :class:`ResourceMeta` (optional) - Container for the group identifier. Workspace local versus account. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`GroupSchema`] (optional) - The schema of the group. - - :returns: :class:`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) +:param id: str (optional) + Databricks group ID +:param members: List[:class:`ComplexValue`] (optional) +:param meta: :class:`ResourceMeta` (optional) + Container for the group identifier. Workspace local versus account. +:param roles: List[:class:`ComplexValue`] (optional) + 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) @@ -73,14 +73,14 @@ 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. - - - + +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 @@ -103,43 +103,43 @@ 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` - + +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) - Desired number of results per page. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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. +:param sort_order: :class:`ListSortOrder` (optional) + 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]]]) @@ -174,42 +174,41 @@ 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"]. - - - + +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) - 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) - :param members: List[:class:`ComplexValue`] (optional) - :param meta: :class:`ResourceMeta` (optional) - Container for the group identifier. Workspace local versus account. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`GroupSchema`] (optional) - The schema of the group. - - - \ No newline at end of file + +Updates the details of a group by replacing the entire group entity. + +:param id: str + Databricks group ID +: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) +:param members: List[:class:`ComplexValue`] (optional) +:param meta: :class:`ResourceMeta` (optional) + Container for the group identifier. Workspace local versus account. +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`GroupSchema`] (optional) + The schema of the group. + + diff --git a/docs/workspace/iam/permission_migration.rst b/docs/workspace/iam/permission_migration.rst index 8eef6e0e1..1aaba1a93 100644 --- a/docs/workspace/iam/permission_migration.rst +++ b/docs/workspace/iam/permission_migration.rst @@ -9,15 +9,14 @@ .. 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 - The name of the workspace group that permissions will be migrated from. - :param to_account_group_name: str - 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 + +:param workspace_id: int + WorkspaceId of the associated workspace where the permission migration will occur. +:param from_workspace_group_name: str + The name of the workspace group that permissions will be migrated from. +:param to_account_group_name: str + 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` diff --git a/docs/workspace/iam/permissions.rst b/docs/workspace/iam/permissions.rst index bf8f8e77f..24894cc8b 100644 --- a/docs/workspace/iam/permissions.rst +++ b/docs/workspace/iam/permissions.rst @@ -5,54 +5,54 @@ .. py:class:: PermissionsAPI 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 +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 @@ -75,19 +75,19 @@ 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` - + +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` + .. py:method:: get_permission_levels(request_object_type: str, request_object_id: str) -> GetPermissionLevelsResponse @@ -110,16 +110,16 @@ 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` - + +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` + .. py:method:: set(request_object_type: str, request_object_id: str [, access_control_list: Optional[List[AccessControlRequest]]]) -> ObjectPermissions @@ -152,36 +152,35 @@ 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, - jobs, notebooks, pipelines, queries, registered-models, repos, serving-endpoints, or warehouses. - :param request_object_id: str - The id of the request object. - :param access_control_list: List[:class:`AccessControlRequest`] (optional) - - :returns: :class:`ObjectPermissions` - + +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, + jobs, notebooks, pipelines, queries, registered-models, repos, serving-endpoints, or warehouses. +: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, - jobs, notebooks, pipelines, queries, registered-models, repos, serving-endpoints, or warehouses. - :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 + +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, + jobs, notebooks, pipelines, queries, registered-models, repos, serving-endpoints, or warehouses. +:param request_object_id: str + The id of the request object. +:param access_control_list: List[:class:`AccessControlRequest`] (optional) + +:returns: :class:`ObjectPermissions` diff --git a/docs/workspace/iam/service_principals.rst b/docs/workspace/iam/service_principals.rst index 0fb8ca643..f1ba78396 100644 --- a/docs/workspace/iam/service_principals.rst +++ b/docs/workspace/iam/service_principals.rst @@ -5,10 +5,10 @@ .. py:class:: ServicePrincipalsAPI Identities for use with jobs, automated tools, and systems such as scripts, apps, and CI/CD platforms. - Databricks recommends creating service principals to run production jobs or modify production data. If all - processes that act on production data run with service principals, interactive users do not need any - write, delete, or modify privileges in production. This eliminates the risk of a user overwriting - production data by accident. +Databricks recommends creating service principals to run production jobs or modify production data. If all +processes that act on production data run with service principals, interactive users do not need any +write, delete, or modify privileges in production. This eliminates the risk of a user overwriting +production data by accident. .. py:method:: create( [, active: Optional[bool], application_id: Optional[str], display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], roles: Optional[List[ComplexValue]], schemas: Optional[List[ServicePrincipalSchema]]]) -> ServicePrincipal @@ -33,43 +33,43 @@ 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) - UUID relating to the service principal - :param display_name: str (optional) - String that represents a concatenation of given and family names. - :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) - :param id: str (optional) - Databricks service principal ID. - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`ServicePrincipalSchema`] (optional) - The schema of the List response. - - :returns: :class:`ServicePrincipal` - + +Creates a new service principal in the Databricks workspace. + +:param active: bool (optional) + If this user is active +:param application_id: str (optional) + UUID relating to the service principal +:param display_name: str (optional) + String that represents a concatenation of given and family names. +: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) +:param id: str (optional) + Databricks service principal ID. +:param roles: List[:class:`ComplexValue`] (optional) + 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. - - - + +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 @@ -92,14 +92,14 @@ 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` - + +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` + .. 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[ServicePrincipal] @@ -116,31 +116,31 @@ 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) - Desired number of results per page. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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. +:param sort_order: :class:`ListSortOrder` (optional) + 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` + .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]]) @@ -168,17 +168,17 @@ 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"]. - - - + +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]]]) @@ -204,30 +204,29 @@ 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) - If this user is active - :param application_id: str (optional) - UUID relating to the service principal - :param display_name: str (optional) - String that represents a concatenation of given and family names. - :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) - :param roles: List[:class:`ComplexValue`] (optional) - 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 + +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) + If this user is active +:param application_id: str (optional) + UUID relating to the service principal +:param display_name: str (optional) + String that represents a concatenation of given and family names. +: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) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`ServicePrincipalSchema`] (optional) + The schema of the List response. + + diff --git a/docs/workspace/iam/users.rst b/docs/workspace/iam/users.rst index 616ef7b86..e7c16c191 100644 --- a/docs/workspace/iam/users.rst +++ b/docs/workspace/iam/users.rst @@ -5,14 +5,14 @@ .. 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 - access. When a user leaves your organization or no longer needs access to Databricks workspace, admins can - terminate the user in your identity provider and that user’s account will also be removed from - Databricks workspace. This ensures a consistent offboarding process and prevents unauthorized users from - accessing sensitive data. + +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 +access. When a user leaves your organization or no longer needs access to Databricks workspace, admins can +terminate the user in your identity provider and that user’s account will also be removed from +Databricks workspace. This ensures a consistent offboarding process and prevents unauthorized users from +accessing sensitive data. .. py:method:: create( [, active: Optional[bool], display_name: Optional[str], emails: Optional[List[ComplexValue]], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], name: Optional[Name], roles: Optional[List[ComplexValue]], schemas: Optional[List[UserSchema]], user_name: Optional[str]]) -> User @@ -30,40 +30,40 @@ 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. - :param groups: List[:class:`ComplexValue`] (optional) - :param id: str (optional) - Databricks user ID. This is automatically set by Databricks. Any value provided by the client will - be ignored. - :param name: :class:`Name` (optional) - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`UserSchema`] (optional) - The schema of the user. - :param user_name: str (optional) - Email address of the Databricks user. - - :returns: :class:`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. +:param groups: List[:class:`ComplexValue`] (optional) +:param id: str (optional) + Databricks user ID. This is automatically set by Databricks. Any value provided by the client will + be ignored. +:param name: :class:`Name` (optional) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`UserSchema`] (optional) + The schema of the user. +:param user_name: str (optional) + Email address of the Databricks user. + +:returns: :class:`User` + .. py:method:: delete(id: str) @@ -83,15 +83,15 @@ 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. - - - + +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 @@ -111,52 +111,52 @@ 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) - Comma-separated list of attributes to return in response. - :param count: int (optional) - Desired number of results per page. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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`, - `name.givenName`, and `emails`. - :param sort_order: :class:`GetSortOrder` (optional) - 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` - + +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) + Comma-separated list of attributes to return in response. +:param count: int (optional) + Desired number of results per page. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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`, + `name.givenName`, and `emails`. +:param sort_order: :class:`GetSortOrder` (optional) + 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` - + +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` - + +Gets the permissions of all passwords. Passwords can inherit permissions from their root object. + +:returns: :class:`PasswordPermissions` + .. 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] @@ -175,32 +175,32 @@ 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) - Desired number of results per page. - :param excluded_attributes: str (optional) - Comma-separated list of attributes to exclude in response. - :param filter: str (optional) - Query by which the results have to be filtered. Supported operators are equals(`eq`), - 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`, - `name.givenName`, and `emails`. - :param sort_order: :class:`ListSortOrder` (optional) - 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` - + +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) + Desired number of results per page. +:param excluded_attributes: str (optional) + Comma-separated list of attributes to exclude in response. +:param filter: str (optional) + Query by which the results have to be filtered. Supported operators are equals(`eq`), + 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`, + `name.givenName`, and `emails`. +:param sort_order: :class:`ListSortOrder` (optional) + 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` + .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]]) @@ -223,29 +223,29 @@ 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"]. - - - + +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` - + +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` + .. 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]]) @@ -265,47 +265,46 @@ 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. - :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. - :param groups: List[:class:`ComplexValue`] (optional) - :param name: :class:`Name` (optional) - :param roles: List[:class:`ComplexValue`] (optional) - Corresponds to AWS instance profile/arn role. - :param schemas: List[:class:`UserSchema`] (optional) - The schema of the user. - :param user_name: str (optional) - Email address of the Databricks 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. +: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. +:param groups: List[:class:`ComplexValue`] (optional) +:param name: :class:`Name` (optional) +:param roles: List[:class:`ComplexValue`] (optional) + Corresponds to AWS instance profile/arn role. +:param schemas: List[:class:`UserSchema`] (optional) + 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 + +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` diff --git a/docs/workspace/jobs/jobs.rst b/docs/workspace/jobs/jobs.rst index b7d677f03..644e09358 100644 --- a/docs/workspace/jobs/jobs.rst +++ b/docs/workspace/jobs/jobs.rst @@ -5,20 +5,20 @@ .. 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 + +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 .. py:method:: cancel_all_runs( [, all_queued_runs: Optional[bool], job_id: Optional[int]]) @@ -55,18 +55,18 @@ 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. - - - + +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] @@ -105,17 +105,17 @@ 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. - + +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. + .. py:method:: cancel_run_and_wait(run_id: int, timeout: datetime.timedelta = 0:20:00) -> Run @@ -153,119 +153,119 @@ 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) - The id of the user specified budget policy to use for this job. If not specified, a default budget - policy may be applied when creating or modifying the job. See `effective_budget_policy_id` for the - budget policy used by this workload. - :param continuous: :class:`Continuous` (optional) - An optional continuous property for this job. The continuous property will ensure that there is - always one run executing. Only one of `schedule` and `continuous` can be used. - :param deployment: :class:`JobDeployment` (optional) - Deployment information for jobs managed by external sources. - :param description: str (optional) - 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) - An optional set of email addresses that is notified when runs of this job begin or complete as well - as when this job is deleted. - :param environments: List[:class:`JobEnvironment`] (optional) - A list of task execution environment specifications that can be referenced by serverless tasks of - this job. An environment is required to be present for serverless tasks. For serverless notebook - tasks, the environment is accessible in the notebook environment panel. For other serverless tasks, - the task environment is required to be specified using environment_key in the task settings. - :param format: :class:`Format` (optional) - Used to tell what is the format of the job. This field is ignored in Create/Update/Reset calls. When - using the Jobs API 2.1 this value is always set to `"MULTI_TASK"`. - :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) - An optional set of health rules that can be defined for this job. - :param job_clusters: List[:class:`JobCluster`] (optional) - A list of job cluster specifications that can be shared and reused by tasks of this job. Libraries - cannot be declared in a shared job cluster. You must declare dependent libraries in task settings. - :param max_concurrent_runs: int (optional) - An optional maximum allowed number of concurrent runs of the job. Set this value if you want to be - able to execute multiple runs of the same job concurrently. This is useful for example if you - trigger your job on a frequent schedule and want to allow consecutive runs to overlap with each - other, or if you want to trigger multiple runs which differ by their input parameters. This setting - affects only new runs. For example, suppose the job’s concurrency is 4 and there are 4 concurrent - active runs. Then setting the concurrency to 3 won’t kill any of the active runs. However, from - then on, new runs are skipped unless there are fewer than 3 active runs. This value cannot exceed - 1000. Setting this value to `0` causes all new runs to be skipped. - :param name: str (optional) - An optional name for the job. The maximum length is 4096 bytes in UTF-8 encoding. - :param notification_settings: :class:`JobNotificationSettings` (optional) - Optional notification settings that are used when sending notifications to each of the - `email_notifications` and `webhook_notifications` for this job. - :param parameters: List[:class:`JobParameterDefinition`] (optional) - Job-level parameter definitions - :param queue: :class:`QueueSettings` (optional) - The queue settings of the job. - :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 - triggered by clicking “Run Now” in the Jobs UI or sending an API request to `runNow`. - :param tags: Dict[str,str] (optional) - A map of tags associated with the job. These are forwarded to the cluster as cluster tags for jobs - clusters, and are subject to the same limitations as cluster tags. A maximum of 25 tags can be added - to the job. - :param tasks: List[:class:`Task`] (optional) - A list of task specifications to be executed by this job. - :param timeout_seconds: int (optional) - An optional timeout applied to each run of this job. A value of `0` means no timeout. - :param trigger: :class:`TriggerSettings` (optional) - A configuration to trigger a run when certain conditions are met. The default behavior is that the - job runs only when triggered by clicking “Run Now” in the Jobs UI or sending an API request to - `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` - + +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) + The id of the user specified budget policy to use for this job. If not specified, a default budget + policy may be applied when creating or modifying the job. See `effective_budget_policy_id` for the + budget policy used by this workload. +:param continuous: :class:`Continuous` (optional) + An optional continuous property for this job. The continuous property will ensure that there is + always one run executing. Only one of `schedule` and `continuous` can be used. +:param deployment: :class:`JobDeployment` (optional) + Deployment information for jobs managed by external sources. +:param description: str (optional) + 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) + An optional set of email addresses that is notified when runs of this job begin or complete as well + as when this job is deleted. +:param environments: List[:class:`JobEnvironment`] (optional) + A list of task execution environment specifications that can be referenced by serverless tasks of + this job. An environment is required to be present for serverless tasks. For serverless notebook + tasks, the environment is accessible in the notebook environment panel. For other serverless tasks, + the task environment is required to be specified using environment_key in the task settings. +:param format: :class:`Format` (optional) + Used to tell what is the format of the job. This field is ignored in Create/Update/Reset calls. When + using the Jobs API 2.1 this value is always set to `"MULTI_TASK"`. +: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) + An optional set of health rules that can be defined for this job. +:param job_clusters: List[:class:`JobCluster`] (optional) + A list of job cluster specifications that can be shared and reused by tasks of this job. Libraries + cannot be declared in a shared job cluster. You must declare dependent libraries in task settings. +:param max_concurrent_runs: int (optional) + An optional maximum allowed number of concurrent runs of the job. Set this value if you want to be + able to execute multiple runs of the same job concurrently. This is useful for example if you + trigger your job on a frequent schedule and want to allow consecutive runs to overlap with each + other, or if you want to trigger multiple runs which differ by their input parameters. This setting + affects only new runs. For example, suppose the job’s concurrency is 4 and there are 4 concurrent + active runs. Then setting the concurrency to 3 won’t kill any of the active runs. However, from + then on, new runs are skipped unless there are fewer than 3 active runs. This value cannot exceed + 1000. Setting this value to `0` causes all new runs to be skipped. +:param name: str (optional) + An optional name for the job. The maximum length is 4096 bytes in UTF-8 encoding. +:param notification_settings: :class:`JobNotificationSettings` (optional) + Optional notification settings that are used when sending notifications to each of the + `email_notifications` and `webhook_notifications` for this job. +:param parameters: List[:class:`JobParameterDefinition`] (optional) + Job-level parameter definitions +:param queue: :class:`QueueSettings` (optional) + The queue settings of the job. +: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 + triggered by clicking “Run Now” in the Jobs UI or sending an API request to `runNow`. +:param tags: Dict[str,str] (optional) + A map of tags associated with the job. These are forwarded to the cluster as cluster tags for jobs + clusters, and are subject to the same limitations as cluster tags. A maximum of 25 tags can be added + to the job. +:param tasks: List[:class:`Task`] (optional) + A list of task specifications to be executed by this job. +:param timeout_seconds: int (optional) + An optional timeout applied to each run of this job. A value of `0` means no timeout. +:param trigger: :class:`TriggerSettings` (optional) + A configuration to trigger a run when certain conditions are met. The default behavior is that the + job runs only when triggered by clicking “Run Now” in the Jobs UI or sending an API request to + `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. - - - + +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. - - - + +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 @@ -304,16 +304,16 @@ 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` - + +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) -> Job @@ -348,38 +348,38 @@ w.jobs.delete_run(run_id=run.run_id) Get a single job. - - Retrieves the details for a single job. - - :param job_id: int - The canonical identifier of the job to retrieve information about. This field is required. - - :returns: :class:`Job` - + +Retrieves the details for a single job. + +:param job_id: int + The canonical identifier of the job to retrieve information about. This field is required. + +: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` - + +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` - + +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` + .. py:method:: get_run(run_id: int [, include_history: bool, include_resolved_values: bool, page_token: str]) -> Run @@ -414,19 +414,19 @@ w.jobs.delete_run(run_id=run.run_id) - This method fetches the details of a run identified by `run_id`. If the run has multiple pages of tasks or iterations, - it will paginate through all pages and aggregate the results. - :param run_id: int - The canonical identifier of the run for which to retrieve the metadata. This field is required. - :param include_history: bool (optional) - Whether to include the repair history in the response. - :param include_resolved_values: bool (optional) - Whether to include resolved parameter values in the response. - :param page_token: str (optional) - To list the next page or the previous page of job tasks, set this field to the value of the - `next_page_token` or `prev_page_token` returned in the GetJob response. - :returns: :class:`Run` - +This method fetches the details of a run identified by `run_id`. If the run has multiple pages of tasks or iterations, +it will paginate through all pages and aggregate the results. +:param run_id: int + The canonical identifier of the run for which to retrieve the metadata. This field is required. +:param include_history: bool (optional) + Whether to include the repair history in the response. +:param include_resolved_values: bool (optional) + Whether to include resolved parameter values in the response. +:param page_token: str (optional) + To list the next page or the previous page of job tasks, set this field to the value of the + `next_page_token` or `prev_page_token` returned in the GetJob response. +:returns: :class:`Run` + .. py:method:: get_run_output(run_id: int) -> RunOutput @@ -461,21 +461,21 @@ 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` - + +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] @@ -512,25 +512,25 @@ w.jobs.delete(job_id=created_job.job_id) List jobs. - - Retrieves a list of jobs. - - :param expand_tasks: bool (optional) - Whether to include task and cluster details in the response. - :param limit: int (optional) - The number of jobs to return. This value must be greater than 0 and less or equal to 100. The - default value is 20. - :param name: str (optional) - A filter on the list based on the exact (case insensitive) job name. - :param offset: int (optional) - The offset of the first job to return, relative to the most recently created job. Deprecated since - June 2023. Use `page_token` to iterate through the pages instead. - :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` - + +Retrieves a list of jobs. + +:param expand_tasks: bool (optional) + Whether to include task and cluster details in the response. +:param limit: int (optional) + The number of jobs to return. This value must be greater than 0 and less or equal to 100. The + default value is 20. +:param name: str (optional) + A filter on the list based on the exact (case insensitive) job name. +:param offset: int (optional) + The offset of the first job to return, relative to the most recently created job. Deprecated since + June 2023. Use `page_token` to iterate through the pages instead. +: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] @@ -567,40 +567,40 @@ w.jobs.delete(job_id=created_job.job_id) List job runs. - - List runs in descending order by start time. - - :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`. - This field cannot be `true` when completed_only is `true`. - :param completed_only: bool (optional) - If completed_only is `true`, only completed runs are included in the results; otherwise, lists both - active and completed runs. This field cannot be `true` when active_only is `true`. - :param expand_tasks: bool (optional) - Whether to include task and cluster details in the response. - :param job_id: int (optional) - The job for which to list runs. If omitted, the Jobs service lists runs from all jobs. - :param limit: int (optional) - The number of runs to return. This value must be greater than 0 and less than 25. The default value - is 20. If a request specifies a limit of 0, the service instead uses the maximum limit. - :param offset: int (optional) - The offset of the first run to return, relative to the most recent run. Deprecated since June 2023. - Use `page_token` to iterate through the pages instead. - :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 runs respectively. - :param run_type: :class:`RunType` (optional) - The type of runs to return. For a description of run types, see :method:jobs/getRun. - :param start_time_from: int (optional) - Show runs that started _at or after_ this value. The value must be a UTC timestamp in milliseconds. - Can be combined with _start_time_to_ to filter by a time range. - :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` - + +List runs in descending order by start time. + +: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`. + This field cannot be `true` when completed_only is `true`. +:param completed_only: bool (optional) + If completed_only is `true`, only completed runs are included in the results; otherwise, lists both + active and completed runs. This field cannot be `true` when active_only is `true`. +:param expand_tasks: bool (optional) + Whether to include task and cluster details in the response. +:param job_id: int (optional) + The job for which to list runs. If omitted, the Jobs service lists runs from all jobs. +:param limit: int (optional) + The number of runs to return. This value must be greater than 0 and less than 25. The default value + is 20. If a request specifies a limit of 0, the service instead uses the maximum limit. +:param offset: int (optional) + The offset of the first run to return, relative to the most recent run. Deprecated since June 2023. + Use `page_token` to iterate through the pages instead. +: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 runs respectively. +:param run_type: :class:`RunType` (optional) + The type of runs to return. For a description of run types, see :method:jobs/getRun. +:param start_time_from: int (optional) + Show runs that started _at or after_ this value. The value must be a UTC timestamp in milliseconds. + Can be combined with _start_time_to_ to filter by a time range. +: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` + .. py:method:: repair_run(run_id: int [, dbt_commands: Optional[List[str]], jar_params: Optional[List[str]], job_parameters: Optional[Dict[str, str]], latest_repair_id: Optional[int], notebook_params: Optional[Dict[str, str]], pipeline_params: Optional[PipelineParams], python_named_params: Optional[Dict[str, str]], python_params: Optional[List[str]], rerun_all_failed_tasks: Optional[bool], rerun_dependent_tasks: Optional[bool], rerun_tasks: Optional[List[str]], spark_submit_params: Optional[List[str]], sql_params: Optional[Dict[str, str]]]) -> Wait[Run] @@ -642,95 +642,95 @@ 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) - An array of commands to execute for jobs with the dbt task, for example `"dbt_commands": ["dbt - deps", "dbt seed", "dbt deps", "dbt seed", "dbt run"]` - :param jar_params: List[str] (optional) - A list of parameters for jobs with Spark JAR tasks, for example `"jar_params": ["john doe", "35"]`. - The parameters are used to invoke the main function of the main class specified in the Spark JAR - 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"` - :param latest_repair_id: int (optional) - The ID of the latest repair. This parameter is not required when repairing a run for the first time, - but must be provided on subsequent requests to repair the same run. - :param notebook_params: Dict[str,str] (optional) - 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) - Controls whether the pipeline should perform a full refresh - :param python_named_params: Dict[str,str] (optional) - :param python_params: List[str] (optional) - A list of parameters for jobs with Python tasks, for example `"python_params": ["john doe", "35"]`. - 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. - :param rerun_dependent_tasks: bool (optional) - If true, repair all tasks that depend on the tasks in `rerun_tasks`, even if they were previously - successful. Can be also used in combination with `rerun_all_failed_tasks`. - :param rerun_tasks: List[str] (optional) - The task keys of the task runs to repair. - :param spark_submit_params: List[str] (optional) - A list of parameters for jobs with spark submit task, for example `"spark_submit_params": - ["--class", "org.apache.spark.examples.SparkPi"]`. The parameters are passed to spark-submit script - 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. - + +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) + An array of commands to execute for jobs with the dbt task, for example `"dbt_commands": ["dbt + deps", "dbt seed", "dbt deps", "dbt seed", "dbt run"]` +:param jar_params: List[str] (optional) + A list of parameters for jobs with Spark JAR tasks, for example `"jar_params": ["john doe", "35"]`. + The parameters are used to invoke the main function of the main class specified in the Spark JAR + 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"` +:param latest_repair_id: int (optional) + The ID of the latest repair. This parameter is not required when repairing a run for the first time, + but must be provided on subsequent requests to repair the same run. +:param notebook_params: Dict[str,str] (optional) + 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) + Controls whether the pipeline should perform a full refresh +:param python_named_params: Dict[str,str] (optional) +:param python_params: List[str] (optional) + A list of parameters for jobs with Python tasks, for example `"python_params": ["john doe", "35"]`. + 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. +:param rerun_dependent_tasks: bool (optional) + If true, repair all tasks that depend on the tasks in `rerun_tasks`, even if they were previously + successful. Can be also used in combination with `rerun_all_failed_tasks`. +:param rerun_tasks: List[str] (optional) + The task keys of the task runs to repair. +:param spark_submit_params: List[str] (optional) + A list of parameters for jobs with spark submit task, for example `"spark_submit_params": + ["--class", "org.apache.spark.examples.SparkPi"]`. The parameters are passed to spark-submit script + 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. + .. py:method:: repair_run_and_wait(run_id: int [, dbt_commands: Optional[List[str]], jar_params: Optional[List[str]], job_parameters: Optional[Dict[str, str]], latest_repair_id: Optional[int], notebook_params: Optional[Dict[str, str]], pipeline_params: Optional[PipelineParams], python_named_params: Optional[Dict[str, str]], python_params: Optional[List[str]], rerun_all_failed_tasks: Optional[bool], rerun_dependent_tasks: Optional[bool], rerun_tasks: Optional[List[str]], spark_submit_params: Optional[List[str]], sql_params: Optional[Dict[str, str]], timeout: datetime.timedelta = 0:20:00]) -> Run @@ -774,20 +774,20 @@ 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. - - - + +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]], 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] @@ -824,102 +824,102 @@ 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) - An array of commands to execute for jobs with the dbt task, for example `"dbt_commands": ["dbt - deps", "dbt seed", "dbt deps", "dbt seed", "dbt run"]` - :param idempotency_token: str (optional) - 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"]`. - The parameters are used to invoke the main function of the main class specified in the Spark JAR - 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"` - :param notebook_params: Dict[str,str] (optional) - 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) - A list of task keys to run inside of the job. If this field is not provided, all tasks in the job - will be run. - :param pipeline_params: :class:`PipelineParams` (optional) - Controls whether the pipeline should perform a full refresh - :param python_named_params: Dict[str,str] (optional) - :param python_params: List[str] (optional) - A list of parameters for jobs with Python tasks, for example `"python_params": ["john doe", "35"]`. - 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. - :param spark_submit_params: List[str] (optional) - A list of parameters for jobs with spark submit task, for example `"spark_submit_params": - ["--class", "org.apache.spark.examples.SparkPi"]`. The parameters are passed to spark-submit script - 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. - + +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) + An array of commands to execute for jobs with the dbt task, for example `"dbt_commands": ["dbt + deps", "dbt seed", "dbt deps", "dbt seed", "dbt run"]` +:param idempotency_token: str (optional) + 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"]`. + The parameters are used to invoke the main function of the main class specified in the Spark JAR + 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"` +:param notebook_params: Dict[str,str] (optional) + 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) + A list of task keys to run inside of the job. If this field is not provided, all tasks in the job + will be run. +:param pipeline_params: :class:`PipelineParams` (optional) + Controls whether the pipeline should perform a full refresh +:param python_named_params: Dict[str,str] (optional) +:param python_params: List[str] (optional) + A list of parameters for jobs with Python tasks, for example `"python_params": ["john doe", "35"]`. + 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. +:param spark_submit_params: List[str] (optional) + A list of parameters for jobs with spark submit task, for example `"spark_submit_params": + ["--class", "org.apache.spark.examples.SparkPi"]`. The parameters are passed to spark-submit script + 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. + .. py:method:: run_now_and_wait(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]], 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]], timeout: datetime.timedelta = 0:20:00]) -> Run @@ -927,16 +927,16 @@ .. 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` - + +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` + .. py:method:: submit( [, access_control_list: Optional[List[JobAccessControlRequest]], budget_policy_id: Optional[str], email_notifications: Optional[JobEmailNotifications], environments: Optional[List[JobEnvironment]], git_source: Optional[GitSource], health: Optional[JobsHealthRules], idempotency_token: Optional[str], notification_settings: Optional[JobNotificationSettings], queue: Optional[QueueSettings], run_as: Optional[JobRunAs], run_name: Optional[str], tasks: Optional[List[SubmitTask]], timeout_seconds: Optional[int], webhook_notifications: Optional[WebhookNotifications]]) -> Wait[Run] @@ -969,64 +969,64 @@ 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) - The user specified id of the budget policy to use for this one-time run. If not specified, the run - will be not be attributed to any budget policy. - :param email_notifications: :class:`JobEmailNotifications` (optional) - An optional set of email addresses notified when the run begins or completes. - :param environments: List[:class:`JobEnvironment`] (optional) - A list of task execution environment specifications that can be referenced by tasks of this run. - :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) - An optional set of health rules that can be defined for this job. - :param idempotency_token: str (optional) - 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 - `email_notifications` and `webhook_notifications` for this run. - :param queue: :class:`QueueSettings` (optional) - The queue settings of the one-time run. - :param run_as: :class:`JobRunAs` (optional) - Specifies the user or service principal that the job runs as. If not specified, the job runs as the - user who submits the request. - :param run_name: str (optional) - An optional name for the run. The default value is `Untitled`. - :param tasks: List[:class:`SubmitTask`] (optional) - :param timeout_seconds: int (optional) - 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. - + +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) + The user specified id of the budget policy to use for this one-time run. If not specified, the run + will be not be attributed to any budget policy. +:param email_notifications: :class:`JobEmailNotifications` (optional) + An optional set of email addresses notified when the run begins or completes. +:param environments: List[:class:`JobEnvironment`] (optional) + A list of task execution environment specifications that can be referenced by tasks of this run. +: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) + An optional set of health rules that can be defined for this job. +:param idempotency_token: str (optional) + 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 + `email_notifications` and `webhook_notifications` for this run. +:param queue: :class:`QueueSettings` (optional) + The queue settings of the one-time run. +:param run_as: :class:`JobRunAs` (optional) + Specifies the user or service principal that the job runs as. If not specified, the job runs as the + user who submits the request. +:param run_name: str (optional) + An optional name for the run. The default value is `Untitled`. +:param tasks: List[:class:`SubmitTask`] (optional) +:param timeout_seconds: int (optional) + 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. + .. py:method:: submit_and_wait( [, access_control_list: Optional[List[JobAccessControlRequest]], budget_policy_id: Optional[str], email_notifications: Optional[JobEmailNotifications], environments: Optional[List[JobEnvironment]], git_source: Optional[GitSource], health: Optional[JobsHealthRules], idempotency_token: Optional[str], notification_settings: Optional[JobNotificationSettings], queue: Optional[QueueSettings], run_as: Optional[JobRunAs], run_name: Optional[str], tasks: Optional[List[SubmitTask]], timeout_seconds: Optional[int], webhook_notifications: Optional[WebhookNotifications], timeout: datetime.timedelta = 0:20:00]) -> Run @@ -1068,41 +1068,41 @@ 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) - Remove top-level fields in the job settings. Removing nested fields is not supported, except for - 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. - - - + +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) + Remove top-level fields in the job settings. Removing nested fields is not supported, except for + 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` - + +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` + .. py:method:: wait_get_run_job_terminated_or_skipped(run_id: int, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[Run], None]]) -> Run diff --git a/docs/workspace/jobs/policy_compliance_for_jobs.rst b/docs/workspace/jobs/policy_compliance_for_jobs.rst index 69f211552..b4326e9e2 100644 --- a/docs/workspace/jobs/policy_compliance_for_jobs.rst +++ b/docs/workspace/jobs/policy_compliance_for_jobs.rst @@ -5,62 +5,61 @@ .. py:class:: PolicyComplianceForJobsAPI 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. +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` - + +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` - + +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) - Use this field to specify the maximum number of results to be returned by the server. The server may - further constrain the maximum number of results returned in a single page. - :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 + +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) + Use this field to specify the maximum number of results to be returned by the server. The server may + further constrain the maximum number of results returned in a single page. +: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` diff --git a/docs/workspace/marketplace/consumer_fulfillments.rst b/docs/workspace/marketplace/consumer_fulfillments.rst index 4ea7a9c29..5833c3fac 100644 --- a/docs/workspace/marketplace/consumer_fulfillments.rst +++ b/docs/workspace/marketplace/consumer_fulfillments.rst @@ -9,28 +9,27 @@ .. 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` - + +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 + +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` diff --git a/docs/workspace/marketplace/consumer_installations.rst b/docs/workspace/marketplace/consumer_installations.rst index 3cdb00a5a..363d90655 100644 --- a/docs/workspace/marketplace/consumer_installations.rst +++ b/docs/workspace/marketplace/consumer_installations.rst @@ -9,70 +9,69 @@ .. 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) - :param recipient_type: :class:`DeltaSharingRecipientType` (optional) - :param repo_detail: :class:`RepoInstallation` (optional) - for git repo installations - :param share_name: str (optional) - - :returns: :class:`Installation` - + +Install payload associated with a Databricks Marketplace listing. + +:param listing_id: str +:param accepted_consumer_terms: :class:`ConsumerTerms` (optional) +:param catalog_name: str (optional) +:param recipient_type: :class:`DeltaSharingRecipientType` (optional) +: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 - - - + +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` - + +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` - + +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 + +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` diff --git a/docs/workspace/marketplace/consumer_listings.rst b/docs/workspace/marketplace/consumer_listings.rst index 242a8fce7..9dff6a54e 100644 --- a/docs/workspace/marketplace/consumer_listings.rst +++ b/docs/workspace/marketplace/consumer_listings.rst @@ -5,75 +5,74 @@ .. py:class:: ConsumerListingsAPI Listings are the core entities in the Marketplace. They represent the products that are available for - consumption. +consumption. .. 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` - + +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` - + +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) - Matches any of the following categories - :param is_free: bool (optional) - Filters each listing based on if it is free. - :param is_private_exchange: bool (optional) - Filters each listing based on if it is a private exchange. - :param is_staff_pick: bool (optional) - Filters each listing based on whether it is a staff pick. - :param page_size: int (optional) - :param page_token: str (optional) - :param provider_ids: List[str] (optional) - Matches any of the following provider ids - :param tags: List[:class:`ListingTag`] (optional) - Matches any of the following tags - - :returns: Iterator over :class:`Listing` - + +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) + Matches any of the following categories +:param is_free: bool (optional) + Filters each listing based on if it is free. +:param is_private_exchange: bool (optional) + Filters each listing based on if it is a private exchange. +:param is_staff_pick: bool (optional) + Filters each listing based on whether it is a staff pick. +:param page_size: int (optional) +:param page_token: str (optional) +:param provider_ids: List[str] (optional) + 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) - Matches any of the following asset types - :param categories: List[:class:`Category`] (optional) - Matches any of the following categories - :param is_free: bool (optional) - :param is_private_exchange: bool (optional) - :param page_size: int (optional) - :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 + +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) + Matches any of the following asset types +:param categories: List[:class:`Category`] (optional) + Matches any of the following categories +:param is_free: bool (optional) +:param is_private_exchange: bool (optional) +:param page_size: int (optional) +:param page_token: str (optional) +:param provider_ids: List[str] (optional) + Matches any of the following provider ids + +:returns: Iterator over :class:`Listing` diff --git a/docs/workspace/marketplace/consumer_personalization_requests.rst b/docs/workspace/marketplace/consumer_personalization_requests.rst index 63ead75d3..e732113ff 100644 --- a/docs/workspace/marketplace/consumer_personalization_requests.rst +++ b/docs/workspace/marketplace/consumer_personalization_requests.rst @@ -9,42 +9,41 @@ .. 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` - :param comment: str (optional) - :param company: str (optional) - :param first_name: str (optional) - :param is_from_lighthouse: bool (optional) - :param last_name: str (optional) - :param recipient_type: :class:`DeltaSharingRecipientType` (optional) - - :returns: :class:`CreatePersonalizationRequestResponse` - + +Create a personalization request for a listing. + +:param listing_id: str +:param intended_use: str +:param accepted_consumer_terms: :class:`ConsumerTerms` +:param comment: str (optional) +:param company: str (optional) +:param first_name: str (optional) +: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` - + +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 + +List personalization requests for a consumer across all listings. + +:param page_size: int (optional) +:param page_token: str (optional) + +:returns: Iterator over :class:`PersonalizationRequest` diff --git a/docs/workspace/marketplace/consumer_providers.rst b/docs/workspace/marketplace/consumer_providers.rst index 13cca357e..f6cc1d770 100644 --- a/docs/workspace/marketplace/consumer_providers.rst +++ b/docs/workspace/marketplace/consumer_providers.rst @@ -9,34 +9,33 @@ .. 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` - + +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` - + +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 + +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` diff --git a/docs/workspace/marketplace/provider_exchange_filters.rst b/docs/workspace/marketplace/provider_exchange_filters.rst index ceca51e63..3d3becc67 100644 --- a/docs/workspace/marketplace/provider_exchange_filters.rst +++ b/docs/workspace/marketplace/provider_exchange_filters.rst @@ -9,46 +9,45 @@ .. py:method:: create(filter: ExchangeFilter) -> CreateExchangeFilterResponse Create a new exchange filter. - - Add an exchange filter. - - :param filter: :class:`ExchangeFilter` - - :returns: :class:`CreateExchangeFilterResponse` - + +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 - - - + +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` - + +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 + +Update an exchange filter. + +:param id: str +:param filter: :class:`ExchangeFilter` + +:returns: :class:`UpdateExchangeFilterResponse` diff --git a/docs/workspace/marketplace/provider_exchanges.rst b/docs/workspace/marketplace/provider_exchanges.rst index d53fd823d..6c5eda159 100644 --- a/docs/workspace/marketplace/provider_exchanges.rst +++ b/docs/workspace/marketplace/provider_exchanges.rst @@ -9,105 +9,104 @@ .. 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` - + +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` - + +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 - - - + +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 - - - + +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` - + +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` - + +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` - + +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` - + +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 + +Update an exchange + +:param id: str +:param exchange: :class:`Exchange` + +:returns: :class:`UpdateExchangeResponse` diff --git a/docs/workspace/marketplace/provider_files.rst b/docs/workspace/marketplace/provider_files.rst index f719ca65f..b71865e30 100644 --- a/docs/workspace/marketplace/provider_files.rst +++ b/docs/workspace/marketplace/provider_files.rst @@ -9,48 +9,47 @@ .. 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` - + +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 - - - + +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` - + +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 + +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` diff --git a/docs/workspace/marketplace/provider_listings.rst b/docs/workspace/marketplace/provider_listings.rst index d26c5293e..7b96689a8 100644 --- a/docs/workspace/marketplace/provider_listings.rst +++ b/docs/workspace/marketplace/provider_listings.rst @@ -5,61 +5,60 @@ .. py:class:: ProviderListingsAPI Listings are the core entities in the Marketplace. They represent the products that are available for - consumption. +consumption. .. py:method:: create(listing: Listing) -> CreateListingResponse Create a listing. - - Create a new listing - - :param listing: :class:`Listing` - - :returns: :class:`CreateListingResponse` - + +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 - - - + +Delete a listing + +:param id: str + + + .. py:method:: get(id: str) -> GetListingResponse Get a listing. - - Get a listing - - :param id: str - - :returns: :class:`GetListingResponse` - + +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` - + +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 + +Update a listing + +:param id: str +:param listing: :class:`Listing` + +:returns: :class:`UpdateListingResponse` diff --git a/docs/workspace/marketplace/provider_personalization_requests.rst b/docs/workspace/marketplace/provider_personalization_requests.rst index 32cdbdbb3..ba896ce96 100644 --- a/docs/workspace/marketplace/provider_personalization_requests.rst +++ b/docs/workspace/marketplace/provider_personalization_requests.rst @@ -5,32 +5,31 @@ .. py:class:: ProviderPersonalizationRequestsAPI Personalization requests are an alternate to instantly available listings. Control the lifecycle of - personalized solutions. +personalized solutions. .. 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` - + +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 + +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` diff --git a/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst b/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst index cc29e089f..4ddee879a 100644 --- a/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst +++ b/docs/workspace/marketplace/provider_provider_analytics_dashboards.rst @@ -9,42 +9,41 @@ .. 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` - + +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` - + +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` - + +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 + +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` diff --git a/docs/workspace/marketplace/provider_providers.rst b/docs/workspace/marketplace/provider_providers.rst index 610c9602e..61ea4d966 100644 --- a/docs/workspace/marketplace/provider_providers.rst +++ b/docs/workspace/marketplace/provider_providers.rst @@ -9,56 +9,55 @@ .. py:method:: create(provider: ProviderInfo) -> CreateProviderResponse Create a provider. - - Create a provider - - :param provider: :class:`ProviderInfo` - - :returns: :class:`CreateProviderResponse` - + +Create a provider + +:param provider: :class:`ProviderInfo` + +:returns: :class:`CreateProviderResponse` + .. py:method:: delete(id: str) Delete provider. - - Delete provider - - :param id: str - - - + +Delete provider + +:param id: str + + + .. py:method:: get(id: str) -> GetProviderResponse Get provider. - - Get provider profile - - :param id: str - - :returns: :class:`GetProviderResponse` - + +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` - + +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 + +Update provider profile + +:param id: str +:param provider: :class:`ProviderInfo` + +:returns: :class:`UpdateProviderResponse` diff --git a/docs/workspace/ml/experiments.rst b/docs/workspace/ml/experiments.rst index 44ceeef8c..386395493 100644 --- a/docs/workspace/ml/experiments.rst +++ b/docs/workspace/ml/experiments.rst @@ -5,11 +5,11 @@ .. py: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 - 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. +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. .. py:method:: create_experiment(name: str [, artifact_location: Optional[str], tags: Optional[List[ExperimentTag]]]) -> CreateExperimentResponse @@ -30,26 +30,26 @@ 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. - - :param name: str - Experiment name. - :param artifact_location: str (optional) - Location where all artifacts for the experiment are stored. If not provided, the remote server will - select an appropriate default. - :param tags: List[:class:`ExperimentTag`] (optional) - A collection of tags to set on the experiment. Maximum tag size and number of tags per request - 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` - + +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. + +:param name: str + Experiment name. +:param artifact_location: str (optional) + Location where all artifacts for the experiment are stored. If not provided, the remote server will + select an appropriate default. +:param tags: List[:class:`ExperimentTag`] (optional) + A collection of tags to set on the experiment. Maximum tag size and number of tags per request + 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 @@ -75,101 +75,101 @@ 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` - associated with a single execution. - - :param experiment_id: str (optional) - ID of the associated experiment. - :param start_time: int (optional) - Unix timestamp in milliseconds of when the run started. - :param tags: List[:class:`RunTag`] (optional) - Additional metadata for run. - :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` - + +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` +associated with a single execution. + +:param experiment_id: str (optional) + ID of the associated experiment. +:param start_time: int (optional) + Unix timestamp in milliseconds of when the run started. +:param tags: List[:class:`RunTag`] (optional) + Additional metadata for run. +: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. - - :param experiment_id: str - ID of the associated 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. + +: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. - - - + +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. - - :param experiment_id: str - The ID of the experiment containing the runs to delete. - :param max_timestamp_millis: int - The maximum creation timestamp in milliseconds since the UNIX epoch for deleting runs. Only runs - created prior to or at this timestamp are deleted. - :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` - + +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. + +:param experiment_id: str + The ID of the experiment containing the runs to delete. +:param max_timestamp_millis: int + The maximum creation timestamp in milliseconds since the UNIX epoch for deleting runs. Only runs + created prior to or at this timestamp are deleted. +: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. - - 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. - - - + +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. - - 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` - + +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` + .. py:method:: get_experiment(experiment_id: str) -> GetExperimentResponse @@ -192,104 +192,104 @@ 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` - + +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. - - 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) - Maximum number of Metric records to return per paginated request. Default is set to 25,000. If set - higher than 25,000, a request Exception will be raised. - :param page_token: str (optional) - Token indicating the page of metric histories to fetch. - :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. - - :returns: Iterator over :class:`Metric` - + +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) + Maximum number of Metric records to return per paginated request. Default is set to 25,000. If set + higher than 25,000, a request Exception will be raised. +:param page_token: str (optional) + Token indicating the page of metric histories to fetch. +: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. + +: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` - + +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` - + +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 - MLflow version. - - :returns: :class:`GetRunResponse` - + +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 + 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). - - :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 - `/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 path: str (optional) - Filter artifacts matching this path (a relative path from the root artifact directory). - :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 - in a future MLflow version. - - :returns: Iterator over :class:`FileInfo` - + +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). + +: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 + `/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 path: str (optional) + Filter artifacts matching this path (a relative path from the root artifact directory). +: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 + 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] @@ -306,308 +306,308 @@ 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) - Qualifier for type of experiments to be returned. If unspecified, return only active experiments. - - :returns: Iterator over :class:`Experiment` - + +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) + 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. - - 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 - - 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 - - :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. - :param params: List[:class:`Param`] (optional) - Params to log. A single request can contain up to 100 params, and up to 1000 metrics, params, and - tags in total. - :param run_id: str (optional) - ID of the run to log under - :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. - - - + +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 + +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 + +: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. +:param params: List[:class:`Param`] (optional) + Params to log. A single request can contain up to 100 params, and up to 1000 metrics, params, and + tags in total. +:param run_id: str (optional) + ID of the run to log under +: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]]) Log inputs to a run. - - **NOTE:** Experimental: This API may change or be removed in a future release without warning. - - :param datasets: List[:class:`DatasetInput`] (optional) - Dataset inputs - :param run_id: str (optional) - ID of the run to log under - - - + +**NOTE:** Experimental: This API may change or be removed in a future release without warning. + +: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 - 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 - Double value of the metric being logged. - :param timestamp: int - Unix timestamp in milliseconds at the time metric was logged. - :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 - removed in a future MLflow version. - :param step: int (optional) - Step at which to log the metric - - - + +Logs 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 + Double value of the metric being logged. +:param timestamp: int + Unix timestamp in milliseconds at the time metric was logged. +: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 + 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 - - - + +**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. - - 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 - String value of the param being logged. Maximum size is 500 bytes. - :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 - removed in a future MLflow version. - - - + +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 + String value of the param being logged. Maximum size is 500 bytes. +: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 + removed in a future MLflow version. + + + .. py:method:: restore_experiment(experiment_id: str) Restores 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. - - - + +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. - - :param run_id: str - ID of the run to restore. - - - + +Restores a deleted run. + +: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. - - :param experiment_id: str - The ID of the experiment containing the runs to restore. - :param min_timestamp_millis: int - The minimum deletion timestamp in milliseconds since the UNIX epoch for restoring runs. Only runs - deleted no earlier than this timestamp are restored. - :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` - + +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. + +:param experiment_id: str + The ID of the experiment containing the runs to restore. +:param min_timestamp_millis: int + The minimum deletion timestamp in milliseconds since the UNIX epoch for restoring runs. Only runs + deleted no earlier than this timestamp are restored. +: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] 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) - Maximum number of experiments desired. Max threshold is 3000. - :param order_by: List[str] (optional) - List of columns for ordering search results, which can include experiment name and last updated - timestamp with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Tiebreaks are - done by experiment id DESC. - :param page_token: str (optional) - Token indicating the page of experiments to fetch - :param view_type: :class:`SearchExperimentsViewType` (optional) - Qualifier for type of experiments to be returned. If unspecified, return only active experiments. - - :returns: Iterator over :class:`Experiment` - + +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) + Maximum number of experiments desired. Max threshold is 3000. +:param order_by: List[str] (optional) + List of columns for ordering search results, which can include experiment name and last updated + timestamp with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Tiebreaks are + done by experiment id DESC. +:param page_token: str (optional) + Token indicating the page of experiments to fetch +:param view_type: :class:`SearchExperimentsViewType` (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] Search for runs. - - Searches for runs that satisfy expressions. - - 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 - provided). - :param page_token: str (optional) - Token for the current page of runs. - :param run_view_type: :class:`SearchRunsRunViewType` (optional) - Whether to display only active, only deleted, or all runs. Defaults to only active runs. - - :returns: Iterator over :class:`Run` - + +Searches for runs that satisfy expressions. + +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 + provided). +:param page_token: str (optional) + Token for the current page of runs. +:param run_view_type: :class:`SearchRunsRunViewType` (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. - - 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. - :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. - - - + +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. +: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(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` - + +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. - - 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. - :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. - :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 - removed in a future MLflow version. - - - + +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. +: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. +: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 + removed in a future MLflow version. + + + .. py:method:: update_experiment(experiment_id: str [, new_name: Optional[str]]) @@ -630,29 +630,29 @@ 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. - - - + +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` - + +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 @@ -680,18 +680,17 @@ 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_uuid: str (optional) - [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 + +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_uuid: str (optional) + [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` diff --git a/docs/workspace/ml/model_registry.rst b/docs/workspace/ml/model_registry.rst index d08a85415..efc7475c5 100644 --- a/docs/workspace/ml/model_registry.rst +++ b/docs/workspace/ml/model_registry.rst @@ -5,40 +5,40 @@ .. py:class:: ModelRegistryAPI Note: This API reference documents APIs for the Workspace Model Registry. Databricks recommends using - [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. +[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` - + +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` + .. py:method:: create_comment(name: str, version: str, comment: str) -> CreateCommentResponse @@ -65,19 +65,19 @@ 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` - + +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` + .. py:method:: create_model(name: str [, description: Optional[str], tags: Optional[List[ModelTag]]]) -> CreateModelResponse @@ -95,20 +95,20 @@ 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` - + +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` + .. py:method:: create_model_version(name: str, source: str [, description: Optional[str], run_id: Optional[str], run_link: Optional[str], tags: Optional[List[ModelVersionTag]]]) -> CreateModelVersionResponse @@ -128,52 +128,52 @@ 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 - URI indicating the location of the model artifacts. - :param description: str (optional) - Optional description for model version. - :param run_id: str (optional) - MLflow run ID for correlation, if `source` was generated by an experiment run in MLflow tracking - server - :param run_link: str (optional) - MLflow run link - this is the exact link of the run that generated this model version, potentially - hosted at another instance of MLflow. - :param tags: List[:class:`ModelVersionTag`] (optional) - Additional metadata for model version. - - :returns: :class:`CreateModelVersionResponse` - + +Creates a model version. + +:param name: str + Register model under this name +:param source: str + URI indicating the location of the model artifacts. +:param description: str (optional) + Optional description for model version. +:param run_id: str (optional) + MLflow run ID for correlation, if `source` was generated by an experiment run in MLflow tracking + server +:param run_link: str (optional) + MLflow run link - this is the exact link of the run that generated this model version, potentially + 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` - + +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` + .. py:method:: create_webhook(events: List[RegistryWebhookEvent] [, description: Optional[str], http_url_spec: Optional[HttpUrlSpec], job_spec: Optional[JobSpec], model_name: Optional[str], status: Optional[RegistryWebhookStatus]]) -> CreateWebhookResponse @@ -197,183 +197,183 @@ 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. - :param http_url_spec: :class:`HttpUrlSpec` (optional) - :param job_spec: :class:`JobSpec` (optional) - :param model_name: str (optional) - Name of the model whose events would trigger this webhook. - :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` - + +**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. +:param http_url_spec: :class:`HttpUrlSpec` (optional) +:param job_spec: :class:`JobSpec` (optional) +:param model_name: str (optional) + Name of the model whose events would trigger this webhook. +: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 - - - + +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. - - - + +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. - - - + +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 - - - + +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 - Model version number 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. - - - + +Deletes a model version tag. + +:param name: str + Name of the registered model that the tag was logged under. +:param version: str + Model version number 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_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. - - - + +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. - - - + +**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` - + +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` + .. py:method:: get_model(name: str) -> GetModelResponse @@ -393,71 +393,71 @@ 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` - + +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` - + +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` - + +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` - + +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` - + +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` + .. py:method:: list_models( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[Model] @@ -474,30 +474,30 @@ 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` - + +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` - + +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` + .. py:method:: list_webhooks( [, events: Optional[List[RegistryWebhookEvent]], model_name: Optional[str], page_token: Optional[str]]) -> Iterator[RegistryWebhook] @@ -514,207 +514,207 @@ 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. - :param model_name: str (optional) - If not specified, all webhooks associated with the specified events are listed, regardless of their - associated model. - :param page_token: str (optional) - Token indicating the page of artifact results to fetch - - :returns: Iterator over :class:`RegistryWebhook` - + +**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. +:param model_name: str (optional) + If not specified, all webhooks associated with the specified events are listed, regardless of their + 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` - + +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` - + +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. - :param max_results: int (optional) - Maximum number of models desired. Max threshold is 10K. - :param order_by: List[str] (optional) - List of columns to be ordered by including model name, version, stage with an optional "DESC" or - "ASC" annotation, where "ASC" is the default. Tiebreaks are done by latest stage transition - 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` - + +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. +:param max_results: int (optional) + Maximum number of models desired. Max threshold is 10K. +:param order_by: List[str] (optional) + List of columns to be ordered by including model name, version, stage with an optional "DESC" or + "ASC" annotation, where "ASC" is the default. Tiebreaks are done by latest stage transition + 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 - quotes. - :param max_results: int (optional) - Maximum number of models desired. Default is 100. Max threshold is 1000. - :param order_by: List[str] (optional) - List of columns for ordering search results, which can include model name and last updated timestamp - with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Tiebreaks are done by model - 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` - + +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 + quotes. +:param max_results: int (optional) + Maximum number of models desired. Default is 100. Max threshold is 1000. +:param order_by: List[str] (optional) + List of columns for ordering search results, which can include model name and last updated timestamp + with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Tiebreaks are done by model + 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 - Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, - its preexisting value will be replaced by the specified `value`. All storage backends are guaranteed - to support key values up to 250 bytes in size. - :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. - - - + +Sets a tag on a registered model. + +:param name: str + Unique name of the model. +:param key: str + Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, + its preexisting value will be replaced by the specified `value`. All storage backends are guaranteed + to support key values up to 250 bytes in size. +: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 - Model version number. - :param key: str - Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, - its preexisting value will be replaced by the specified `value`. All storage backends are guaranteed - to support key values up to 250 bytes in size. - :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. - - - + +Sets a model version tag. + +:param name: str + Unique name of the model. +:param version: str + Model version number. +:param key: str + Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, + its preexisting value will be replaced by the specified `value`. All storage backends are guaranteed + to support key values up to 250 bytes in size. +: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` - + +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` - + +**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` - + +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` + .. py:method:: update_comment(id: str, comment: str) -> UpdateCommentResponse @@ -743,16 +743,16 @@ 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` - + +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` + .. py:method:: update_model(name: str [, description: Optional[str]]) @@ -776,16 +776,16 @@ 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`. - - - + +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]]) @@ -809,32 +809,32 @@ 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`. - - - + +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` - + +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` + .. py:method:: update_webhook(id: str [, description: Optional[str], events: Optional[List[RegistryWebhookEvent]], http_url_spec: Optional[HttpUrlSpec], job_spec: Optional[JobSpec], status: Optional[RegistryWebhookStatus]]) @@ -860,54 +860,53 @@ 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) - User-specified description for the webhook. - :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 + +**NOTE:** This endpoint is in Public Preview. + +Updates a registry webhook. + +:param id: str + Webhook ID +:param description: str (optional) + User-specified description for the webhook. +: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. + + diff --git a/docs/workspace/pipelines/pipelines.rst b/docs/workspace/pipelines/pipelines.rst index 1ba875740..8859e01b1 100644 --- a/docs/workspace/pipelines/pipelines.rst +++ b/docs/workspace/pipelines/pipelines.rst @@ -5,15 +5,15 @@ .. 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 - data quality and specify how to handle records that fail those expectations. + +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 +data quality and specify how to handle records that fail those expectations. .. py:method:: create( [, allow_duplicate_names: Optional[bool], budget_policy_id: Optional[str], catalog: Optional[str], channel: Optional[str], clusters: Optional[List[PipelineCluster]], configuration: Optional[Dict[str, str]], continuous: Optional[bool], deployment: Optional[PipelineDeployment], development: Optional[bool], dry_run: Optional[bool], edition: Optional[str], filters: Optional[Filters], gateway_definition: Optional[IngestionGatewayPipelineDefinition], id: Optional[str], ingestion_definition: Optional[IngestionPipelineDefinition], libraries: Optional[List[PipelineLibrary]], name: Optional[str], notifications: Optional[List[Notifications]], photon: Optional[bool], restart_window: Optional[RestartWindow], schema: Optional[str], serverless: Optional[bool], storage: Optional[str], target: Optional[str], trigger: Optional[PipelineTrigger]]) -> CreatePipelineResponse @@ -49,78 +49,78 @@ 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) - Budget policy of this pipeline. - :param catalog: str (optional) - A catalog in Unity Catalog to publish data from this pipeline to. If `target` is specified, tables - in this pipeline are published to a `target` schema inside `catalog` (for example, - `catalog`.`target`.`table`). If `target` is not specified, no data is published to Unity Catalog. - :param channel: str (optional) - DLT Release Channel that specifies which version to use. - :param clusters: List[:class:`PipelineCluster`] (optional) - Cluster settings for this pipeline deployment. - :param configuration: Dict[str,str] (optional) - String-String configuration for this pipeline execution. - :param continuous: bool (optional) - Whether the pipeline is continuous or triggered. This replaces `trigger`. - :param deployment: :class:`PipelineDeployment` (optional) - Deployment type of this pipeline. - :param development: bool (optional) - Whether the pipeline is in Development mode. Defaults to false. - :param dry_run: bool (optional) - :param edition: str (optional) - Pipeline product edition. - :param filters: :class:`Filters` (optional) - Filters on which Pipeline packages to include in the deployed graph. - :param gateway_definition: :class:`IngestionGatewayPipelineDefinition` (optional) - The definition of a gateway pipeline to support change data capture. - :param id: str (optional) - Unique identifier for this pipeline. - :param ingestion_definition: :class:`IngestionPipelineDefinition` (optional) - The configuration for a managed ingestion pipeline. These settings cannot be used with the - 'libraries', 'target' or 'catalog' settings. - :param libraries: List[:class:`PipelineLibrary`] (optional) - Libraries or code needed by this deployment. - :param name: str (optional) - Friendly identifier for this pipeline. - :param notifications: List[:class:`Notifications`] (optional) - List of notification settings for this pipeline. - :param photon: bool (optional) - Whether Photon is enabled for this pipeline. - :param restart_window: :class:`RestartWindow` (optional) - Restart window of this pipeline. - :param schema: str (optional) - The default schema (database) where tables are read from or published to. The presence of this field - implies that the pipeline is in direct publishing mode. - :param serverless: bool (optional) - Whether serverless compute is enabled for this pipeline. - :param storage: str (optional) - DBFS root directory for storing checkpoints and tables. - :param target: str (optional) - Target schema (database) to add tables in this pipeline to. If not specified, no data is published - 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` - + +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) + Budget policy of this pipeline. +:param catalog: str (optional) + A catalog in Unity Catalog to publish data from this pipeline to. If `target` is specified, tables + in this pipeline are published to a `target` schema inside `catalog` (for example, + `catalog`.`target`.`table`). If `target` is not specified, no data is published to Unity Catalog. +:param channel: str (optional) + DLT Release Channel that specifies which version to use. +:param clusters: List[:class:`PipelineCluster`] (optional) + Cluster settings for this pipeline deployment. +:param configuration: Dict[str,str] (optional) + String-String configuration for this pipeline execution. +:param continuous: bool (optional) + Whether the pipeline is continuous or triggered. This replaces `trigger`. +:param deployment: :class:`PipelineDeployment` (optional) + Deployment type of this pipeline. +:param development: bool (optional) + Whether the pipeline is in Development mode. Defaults to false. +:param dry_run: bool (optional) +:param edition: str (optional) + Pipeline product edition. +:param filters: :class:`Filters` (optional) + Filters on which Pipeline packages to include in the deployed graph. +:param gateway_definition: :class:`IngestionGatewayPipelineDefinition` (optional) + The definition of a gateway pipeline to support change data capture. +:param id: str (optional) + Unique identifier for this pipeline. +:param ingestion_definition: :class:`IngestionPipelineDefinition` (optional) + The configuration for a managed ingestion pipeline. These settings cannot be used with the + 'libraries', 'target' or 'catalog' settings. +:param libraries: List[:class:`PipelineLibrary`] (optional) + Libraries or code needed by this deployment. +:param name: str (optional) + Friendly identifier for this pipeline. +:param notifications: List[:class:`Notifications`] (optional) + List of notification settings for this pipeline. +:param photon: bool (optional) + Whether Photon is enabled for this pipeline. +:param restart_window: :class:`RestartWindow` (optional) + Restart window of this pipeline. +:param schema: str (optional) + The default schema (database) where tables are read from or published to. The presence of this field + implies that the pipeline is in direct publishing mode. +:param serverless: bool (optional) + Whether serverless compute is enabled for this pipeline. +:param storage: str (optional) + DBFS root directory for storing checkpoints and tables. +:param target: str (optional) + Target schema (database) to add tables in this pipeline to. If not specified, no data is published + 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 - - - + +Deletes a pipeline. + +:param pipeline_id: str + + + .. py:method:: get(pipeline_id: str) -> GetPipelineResponse @@ -158,49 +158,49 @@ w.pipelines.delete(pipeline_id=created.pipeline_id) Get a pipeline. - - :param pipeline_id: str - - :returns: :class:`GetPipelineResponse` - + +: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` - + +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` - + +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` - + +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` + .. py:method:: list_pipeline_events(pipeline_id: str [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) -> Iterator[PipelineEvent] @@ -238,31 +238,31 @@ 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) - Max number of entries to return in a single page. The system may return fewer than max_results - events in a response, even if there are more events available. - :param order_by: List[str] (optional) - A string indicating a sort order by timestamp for the results, for example, ["timestamp asc"]. The - sort order can be ascending or descending. By default, events are returned in descending order by - timestamp. - :param page_token: str (optional) - 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` - + +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) + Max number of entries to return in a single page. The system may return fewer than max_results + events in a response, even if there are more events available. +:param order_by: List[str] (optional) + A string indicating a sort order by timestamp for the results, for example, ["timestamp asc"]. The + sort order can be ascending or descending. By default, events are returned in descending order by + timestamp. +:param page_token: str (optional) + 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` + .. py:method:: list_pipelines( [, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) -> Iterator[PipelineStateInfo] @@ -279,102 +279,102 @@ 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 - max_results events in a response, even if there are more events available. This field is optional. - The default value is 25. The maximum value is 100. An error is returned if the value of max_results - is greater than 100. - :param order_by: List[str] (optional) - A list of strings specifying the order of results. Supported order_by fields are id and name. The - default is id asc. This field is optional. - :param page_token: str (optional) - Page token returned by previous call - - :returns: Iterator over :class:`PipelineStateInfo` - + +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 + max_results events in a response, even if there are more events available. This field is optional. + The default value is 25. The maximum value is 100. An error is returned if the value of max_results + is greater than 100. +:param order_by: List[str] (optional) + A list of strings specifying the order of results. Supported order_by fields are id and name. The + 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) - Max number of entries to return in a single page. - :param page_token: str (optional) - 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` - + +List updates for an active pipeline. + +:param pipeline_id: str + The pipeline to return updates for. +:param max_results: int (optional) + Max number of entries to return in a single page. +:param page_token: str (optional) + 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` - + +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) - If true, this update will reset all tables before running. - :param full_refresh_selection: List[str] (optional) - A list of tables to update with fullRefresh. If both refresh_selection and full_refresh_selection - are empty, this is a full graph update. Full Refresh on a table means that the states of the table - will be reset before the refresh. - :param refresh_selection: List[str] (optional) - A list of tables to update without fullRefresh. If both refresh_selection and full_refresh_selection - are empty, this is a full graph update. Full Refresh on a table means that the states of the table - will be reset before the refresh. - :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` - + +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) + If true, this update will reset all tables before running. +:param full_refresh_selection: List[str] (optional) + A list of tables to update with fullRefresh. If both refresh_selection and full_refresh_selection + are empty, this is a full graph update. Full Refresh on a table means that the states of the table + will be reset before the refresh. +:param refresh_selection: List[str] (optional) + A list of tables to update without fullRefresh. If both refresh_selection and full_refresh_selection + are empty, this is a full graph update. Full Refresh on a table means that the states of the table + will be reset before the refresh. +: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. - + +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. + .. py:method:: stop_and_wait(pipeline_id: str, timeout: datetime.timedelta = 0:20:00) -> GetPipelineResponse @@ -426,83 +426,83 @@ 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) - If false, deployment will fail if name has changed and conflicts the name of another pipeline. - :param budget_policy_id: str (optional) - Budget policy of this pipeline. - :param catalog: str (optional) - A catalog in Unity Catalog to publish data from this pipeline to. If `target` is specified, tables - in this pipeline are published to a `target` schema inside `catalog` (for example, - `catalog`.`target`.`table`). If `target` is not specified, no data is published to Unity Catalog. - :param channel: str (optional) - DLT Release Channel that specifies which version to use. - :param clusters: List[:class:`PipelineCluster`] (optional) - Cluster settings for this pipeline deployment. - :param configuration: Dict[str,str] (optional) - String-String configuration for this pipeline execution. - :param continuous: bool (optional) - Whether the pipeline is continuous or triggered. This replaces `trigger`. - :param deployment: :class:`PipelineDeployment` (optional) - Deployment type of this pipeline. - :param development: bool (optional) - Whether the pipeline is in Development mode. Defaults to false. - :param edition: str (optional) - Pipeline product edition. - :param expected_last_modified: int (optional) - If present, the last-modified time of the pipeline settings before the edit. If the settings were - modified after that time, then the request will fail with a conflict. - :param filters: :class:`Filters` (optional) - Filters on which Pipeline packages to include in the deployed graph. - :param gateway_definition: :class:`IngestionGatewayPipelineDefinition` (optional) - The definition of a gateway pipeline to support change data capture. - :param id: str (optional) - Unique identifier for this pipeline. - :param ingestion_definition: :class:`IngestionPipelineDefinition` (optional) - The configuration for a managed ingestion pipeline. These settings cannot be used with the - 'libraries', 'target' or 'catalog' settings. - :param libraries: List[:class:`PipelineLibrary`] (optional) - Libraries or code needed by this deployment. - :param name: str (optional) - Friendly identifier for this pipeline. - :param notifications: List[:class:`Notifications`] (optional) - List of notification settings for this pipeline. - :param photon: bool (optional) - Whether Photon is enabled for this pipeline. - :param restart_window: :class:`RestartWindow` (optional) - Restart window of this pipeline. - :param schema: str (optional) - The default schema (database) where tables are read from or published to. The presence of this field - implies that the pipeline is in direct publishing mode. - :param serverless: bool (optional) - Whether serverless compute is enabled for this pipeline. - :param storage: str (optional) - DBFS root directory for storing checkpoints and tables. - :param target: str (optional) - Target schema (database) to add tables in this pipeline to. If not specified, no data is published - 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. - - - + +Updates a pipeline with the supplied configuration. + +:param pipeline_id: str + Unique identifier for this pipeline. +:param allow_duplicate_names: bool (optional) + If false, deployment will fail if name has changed and conflicts the name of another pipeline. +:param budget_policy_id: str (optional) + Budget policy of this pipeline. +:param catalog: str (optional) + A catalog in Unity Catalog to publish data from this pipeline to. If `target` is specified, tables + in this pipeline are published to a `target` schema inside `catalog` (for example, + `catalog`.`target`.`table`). If `target` is not specified, no data is published to Unity Catalog. +:param channel: str (optional) + DLT Release Channel that specifies which version to use. +:param clusters: List[:class:`PipelineCluster`] (optional) + Cluster settings for this pipeline deployment. +:param configuration: Dict[str,str] (optional) + String-String configuration for this pipeline execution. +:param continuous: bool (optional) + Whether the pipeline is continuous or triggered. This replaces `trigger`. +:param deployment: :class:`PipelineDeployment` (optional) + Deployment type of this pipeline. +:param development: bool (optional) + Whether the pipeline is in Development mode. Defaults to false. +:param edition: str (optional) + Pipeline product edition. +:param expected_last_modified: int (optional) + If present, the last-modified time of the pipeline settings before the edit. If the settings were + modified after that time, then the request will fail with a conflict. +:param filters: :class:`Filters` (optional) + Filters on which Pipeline packages to include in the deployed graph. +:param gateway_definition: :class:`IngestionGatewayPipelineDefinition` (optional) + The definition of a gateway pipeline to support change data capture. +:param id: str (optional) + Unique identifier for this pipeline. +:param ingestion_definition: :class:`IngestionPipelineDefinition` (optional) + The configuration for a managed ingestion pipeline. These settings cannot be used with the + 'libraries', 'target' or 'catalog' settings. +:param libraries: List[:class:`PipelineLibrary`] (optional) + Libraries or code needed by this deployment. +:param name: str (optional) + Friendly identifier for this pipeline. +:param notifications: List[:class:`Notifications`] (optional) + List of notification settings for this pipeline. +:param photon: bool (optional) + Whether Photon is enabled for this pipeline. +:param restart_window: :class:`RestartWindow` (optional) + Restart window of this pipeline. +:param schema: str (optional) + The default schema (database) where tables are read from or published to. The presence of this field + implies that the pipeline is in direct publishing mode. +:param serverless: bool (optional) + Whether serverless compute is enabled for this pipeline. +:param storage: str (optional) + DBFS root directory for storing checkpoints and tables. +:param target: str (optional) + Target schema (database) to add tables in this pipeline to. If not specified, no data is published + 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` - + +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` + .. py:method:: wait_get_pipeline_idle(pipeline_id: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[GetPipelineResponse], None]]) -> GetPipelineResponse diff --git a/docs/workspace/provisioning/credentials.rst b/docs/workspace/provisioning/credentials.rst index 8f38d13c4..8094b6ac1 100644 --- a/docs/workspace/provisioning/credentials.rst +++ b/docs/workspace/provisioning/credentials.rst @@ -5,9 +5,9 @@ .. py:class:: CredentialsAPI These APIs manage credential configurations for this workspace. Databricks needs access to a cross-account - service IAM role in your AWS account so that Databricks can deploy clusters in the appropriate VPC for the - new workspace. A credential configuration encapsulates this role information, and its ID is used when - creating a new workspace. +service IAM role in your AWS account so that Databricks can deploy clusters in the appropriate VPC for the +new workspace. A credential configuration encapsulates this role information, and its ID is used when +creating a new workspace. .. py:method:: create(credentials_name: str, aws_credentials: CreateCredentialAwsCredentials) -> Credential @@ -33,39 +33,39 @@ 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` - + +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 - - - + +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 @@ -93,14 +93,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[Credential] @@ -116,8 +116,7 @@ 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 + +Gets all Databricks credential configurations associated with an account specified by ID. + +:returns: Iterator over :class:`Credential` diff --git a/docs/workspace/serving/serving_endpoints.rst b/docs/workspace/serving/serving_endpoints.rst index 430a13182..723ccc20c 100644 --- a/docs/workspace/serving/serving_endpoints.rst +++ b/docs/workspace/serving/serving_endpoints.rst @@ -5,54 +5,54 @@ .. 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 - cloud account. A serving endpoint can consist of one or more MLflow models from the Databricks Model - Registry, called served entities. A serving endpoint can have at most ten served entities. You can - configure traffic settings to define how requests should be routed to your served entities behind an - endpoint. Additionally, you can configure the scale of resources that should be applied to each served - entity. + +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 +cloud account. A serving endpoint can consist of one or more MLflow models from the Databricks Model +Registry, called served entities. A serving endpoint can have at most ten served entities. You can +configure traffic settings to define how requests should be routed to your served entities behind an +endpoint. Additionally, you can configure the scale of resources that should be applied to each served +entity. .. 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` - + +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, config: EndpointCoreConfigInput [, ai_gateway: Optional[AiGatewayConfig], 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 config: :class:`EndpointCoreConfigInput` - The core config of the serving endpoint. - :param ai_gateway: :class:`AiGatewayConfig` (optional) - The AI Gateway configuration for the serving endpoint. NOTE: only external model endpoints are - supported as of now. - :param rate_limits: List[:class:`RateLimit`] (optional) - Rate limits to be applied to the serving endpoint. NOTE: this field is deprecated, please use AI - Gateway to manage rate limits. - :param route_optimized: bool (optional) - 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. - + +: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 config: :class:`EndpointCoreConfigInput` + The core config of the serving endpoint. +:param ai_gateway: :class:`AiGatewayConfig` (optional) + The AI Gateway configuration for the serving endpoint. NOTE: only external model endpoints are + supported as of now. +:param rate_limits: List[:class:`RateLimit`] (optional) + Rate limits to be applied to the serving endpoint. NOTE: this field is deprecated, please use AI + Gateway to manage rate limits. +:param route_optimized: bool (optional) + 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, config: EndpointCoreConfigInput [, ai_gateway: Optional[AiGatewayConfig], rate_limits: Optional[List[RateLimit]], route_optimized: Optional[bool], tags: Optional[List[EndpointTag]], timeout: datetime.timedelta = 0:20:00]) -> ServingEndpointDetailed @@ -60,37 +60,37 @@ .. py:method:: delete(name: str) Delete a serving endpoint. - - :param name: str - The name of the serving endpoint. This field is required. - - - + +:param name: str + The name of the serving endpoint. This field is required. + + + .. 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` - + +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` - + +Retrieves the details for a single serving endpoint. + +:param name: str + The name of the serving endpoint. This field is required. + +:returns: :class:`ServingEndpointDetailed` + .. py:method:: get_langchain_chat_open_ai_client(model) @@ -101,206 +101,206 @@ .. py:method:: get_open_api(name: str) 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. - - - + +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. + + + .. 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` - + +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` - + +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` + .. py:method:: list() -> Iterator[ServingEndpoint] Get all serving endpoints. - - :returns: Iterator over :class:`ServingEndpoint` - + +: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` - + +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]]]) -> Iterator[EndpointTag] 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: Iterator over :class:`EndpointTag` - + +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: Iterator over :class:`EndpointTag` + .. 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` - + +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 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) - Configuration for AI Guardrails to prevent unwanted data and unsafe data in requests and responses. - :param inference_table_config: :class:`AiGatewayInferenceTableConfig` (optional) - Configuration for payload logging using inference tables. Use these tables to monitor and audit data - being sent to and received from model APIs and to improve model quality. - :param rate_limits: List[:class:`AiGatewayRateLimit`] (optional) - Configuration for rate limits which can be set to limit endpoint traffic. - :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` - + +Used to update the AI Gateway of a serving endpoint. NOTE: Only external model 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) + Configuration for AI Guardrails to prevent unwanted data and unsafe data in requests and responses. +:param inference_table_config: :class:`AiGatewayInferenceTableConfig` (optional) + Configuration for payload logging using inference tables. Use these tables to monitor and audit data + being sent to and received from model APIs and to improve model quality. +:param rate_limits: List[:class:`AiGatewayRateLimit`] (optional) + Configuration for rate limits which can be set to limit endpoint traffic. +: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) - Pandas Dataframe input in the records orientation. - :param dataframe_split: :class:`DataframeSplitInput` (optional) - Pandas Dataframe input in the split orientation. - :param extra_params: Dict[str,str] (optional) - The extra parameters field used ONLY for __completions, chat,__ and __embeddings external & - foundation model__ serving endpoints. This is a map of strings and should only be used with other - external/foundation model query fields. - :param input: Any (optional) - The input string (or array of strings) field used ONLY for __embeddings external & foundation - model__ serving endpoints and is the only field (along with extra_params if needed) used by - embeddings queries. - :param inputs: Any (optional) - Tensor-based input in columnar format. - :param instances: List[Any] (optional) - Tensor-based input in row format. - :param max_tokens: int (optional) - The max tokens field used ONLY for __completions__ and __chat external & foundation model__ serving - endpoints. This is an integer and should only be used with other chat/completions query fields. - :param messages: List[:class:`ChatMessage`] (optional) - The messages field used ONLY for __chat external & foundation model__ serving endpoints. This is a - map of strings and should only be used with other chat query fields. - :param n: int (optional) - The n (number of candidates) field used ONLY for __completions__ and __chat external & foundation - model__ serving endpoints. This is an integer between 1 and 5 with a default of 1 and should only be - used with other chat/completions query fields. - :param prompt: Any (optional) - The prompt string (or array of strings) field used ONLY for __completions external & foundation - model__ serving endpoints and should only be used with other completions query fields. - :param stop: List[str] (optional) - The stop sequences field used ONLY for __completions__ and __chat external & foundation model__ - serving endpoints. This is a list of strings and should only be used with other chat/completions - query fields. - :param stream: bool (optional) - The stream field used ONLY for __completions__ and __chat external & foundation model__ serving - endpoints. This is a boolean defaulting to false and should only be used with other chat/completions - query fields. - :param temperature: float (optional) - 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` - + +:param name: str + The name of the serving endpoint. This field is required. +:param dataframe_records: List[Any] (optional) + Pandas Dataframe input in the records orientation. +:param dataframe_split: :class:`DataframeSplitInput` (optional) + Pandas Dataframe input in the split orientation. +:param extra_params: Dict[str,str] (optional) + The extra parameters field used ONLY for __completions, chat,__ and __embeddings external & + foundation model__ serving endpoints. This is a map of strings and should only be used with other + external/foundation model query fields. +:param input: Any (optional) + The input string (or array of strings) field used ONLY for __embeddings external & foundation + model__ serving endpoints and is the only field (along with extra_params if needed) used by + embeddings queries. +:param inputs: Any (optional) + Tensor-based input in columnar format. +:param instances: List[Any] (optional) + Tensor-based input in row format. +:param max_tokens: int (optional) + The max tokens field used ONLY for __completions__ and __chat external & foundation model__ serving + endpoints. This is an integer and should only be used with other chat/completions query fields. +:param messages: List[:class:`ChatMessage`] (optional) + The messages field used ONLY for __chat external & foundation model__ serving endpoints. This is a + map of strings and should only be used with other chat query fields. +:param n: int (optional) + The n (number of candidates) field used ONLY for __completions__ and __chat external & foundation + model__ serving endpoints. This is an integer between 1 and 5 with a default of 1 and should only be + used with other chat/completions query fields. +:param prompt: Any (optional) + The prompt string (or array of strings) field used ONLY for __completions external & foundation + model__ serving endpoints and should only be used with other completions query fields. +:param stop: List[str] (optional) + The stop sequences field used ONLY for __completions__ and __chat external & foundation model__ + serving endpoints. This is a list of strings and should only be used with other chat/completions + query fields. +:param stream: bool (optional) + The stream field used ONLY for __completions__ and __chat external & foundation model__ serving + endpoints. This is a boolean defaulting to false and should only be used with other chat/completions + query fields. +:param temperature: float (optional) + 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` - + +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) - Configuration for Inference Tables which automatically logs requests and responses to Unity Catalog. - :param served_entities: List[:class:`ServedEntityInput`] (optional) - A list of served entities for the endpoint to serve. A serving endpoint can have up to 15 served - entities. - :param served_models: List[:class:`ServedModelInput`] (optional) - (Deprecated, use served_entities instead) A list of served models for the endpoint to serve. A - serving endpoint can have up to 15 served models. - :param traffic_config: :class:`TrafficConfig` (optional) - The traffic config defining how invocations to the serving endpoint should be routed. - - :returns: - Long-running operation waiter for :class:`ServingEndpointDetailed`. - See :method:wait_get_serving_endpoint_not_updating for more details. - + +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) + Configuration for Inference Tables which automatically logs requests and responses to Unity Catalog. +:param served_entities: List[:class:`ServedEntityInput`] (optional) + A list of served entities for the endpoint to serve. A serving endpoint can have up to 15 served + entities. +:param served_models: List[:class:`ServedModelInput`] (optional) + (Deprecated, use served_entities instead) A list of served models for the endpoint to serve. A + serving endpoint can have up to 15 served models. +:param traffic_config: :class:`TrafficConfig` (optional) + The traffic config defining how invocations to the serving endpoint should be routed. + +:returns: + Long-running operation waiter for :class:`ServingEndpointDetailed`. + See :method:wait_get_serving_endpoint_not_updating for more details. + .. py:method:: update_config_and_wait(name: str [, auto_capture_config: Optional[AutoCaptureConfigInput], served_entities: Optional[List[ServedEntityInput]], served_models: Optional[List[ServedModelInput]], traffic_config: Optional[TrafficConfig], timeout: datetime.timedelta = 0:20:00]) -> ServingEndpointDetailed @@ -308,15 +308,15 @@ .. 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` - + +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` + .. py:method:: wait_get_serving_endpoint_not_updating(name: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[ServingEndpointDetailed], None]]) -> ServingEndpointDetailed diff --git a/docs/workspace/serving/serving_endpoints_data_plane.rst b/docs/workspace/serving/serving_endpoints_data_plane.rst index 8fb09e7ff..b3501b121 100644 --- a/docs/workspace/serving/serving_endpoints_data_plane.rst +++ b/docs/workspace/serving/serving_endpoints_data_plane.rst @@ -5,55 +5,54 @@ .. py:class:: ServingEndpointsDataPlaneAPI Serving endpoints DataPlane provides a set of operations to interact with data plane endpoints for Serving - endpoints service. +endpoints service. .. 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) - Pandas Dataframe input in the records orientation. - :param dataframe_split: :class:`DataframeSplitInput` (optional) - Pandas Dataframe input in the split orientation. - :param extra_params: Dict[str,str] (optional) - The extra parameters field used ONLY for __completions, chat,__ and __embeddings external & - foundation model__ serving endpoints. This is a map of strings and should only be used with other - external/foundation model query fields. - :param input: Any (optional) - The input string (or array of strings) field used ONLY for __embeddings external & foundation - model__ serving endpoints and is the only field (along with extra_params if needed) used by - embeddings queries. - :param inputs: Any (optional) - Tensor-based input in columnar format. - :param instances: List[Any] (optional) - Tensor-based input in row format. - :param max_tokens: int (optional) - The max tokens field used ONLY for __completions__ and __chat external & foundation model__ serving - endpoints. This is an integer and should only be used with other chat/completions query fields. - :param messages: List[:class:`ChatMessage`] (optional) - The messages field used ONLY for __chat external & foundation model__ serving endpoints. This is a - map of strings and should only be used with other chat query fields. - :param n: int (optional) - The n (number of candidates) field used ONLY for __completions__ and __chat external & foundation - model__ serving endpoints. This is an integer between 1 and 5 with a default of 1 and should only be - used with other chat/completions query fields. - :param prompt: Any (optional) - The prompt string (or array of strings) field used ONLY for __completions external & foundation - model__ serving endpoints and should only be used with other completions query fields. - :param stop: List[str] (optional) - The stop sequences field used ONLY for __completions__ and __chat external & foundation model__ - serving endpoints. This is a list of strings and should only be used with other chat/completions - query fields. - :param stream: bool (optional) - The stream field used ONLY for __completions__ and __chat external & foundation model__ serving - endpoints. This is a boolean defaulting to false and should only be used with other chat/completions - query fields. - :param temperature: float (optional) - 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 + +:param name: str + The name of the serving endpoint. This field is required. +:param dataframe_records: List[Any] (optional) + Pandas Dataframe input in the records orientation. +:param dataframe_split: :class:`DataframeSplitInput` (optional) + Pandas Dataframe input in the split orientation. +:param extra_params: Dict[str,str] (optional) + The extra parameters field used ONLY for __completions, chat,__ and __embeddings external & + foundation model__ serving endpoints. This is a map of strings and should only be used with other + external/foundation model query fields. +:param input: Any (optional) + The input string (or array of strings) field used ONLY for __embeddings external & foundation + model__ serving endpoints and is the only field (along with extra_params if needed) used by + embeddings queries. +:param inputs: Any (optional) + Tensor-based input in columnar format. +:param instances: List[Any] (optional) + Tensor-based input in row format. +:param max_tokens: int (optional) + The max tokens field used ONLY for __completions__ and __chat external & foundation model__ serving + endpoints. This is an integer and should only be used with other chat/completions query fields. +:param messages: List[:class:`ChatMessage`] (optional) + The messages field used ONLY for __chat external & foundation model__ serving endpoints. This is a + map of strings and should only be used with other chat query fields. +:param n: int (optional) + The n (number of candidates) field used ONLY for __completions__ and __chat external & foundation + model__ serving endpoints. This is an integer between 1 and 5 with a default of 1 and should only be + used with other chat/completions query fields. +:param prompt: Any (optional) + The prompt string (or array of strings) field used ONLY for __completions external & foundation + model__ serving endpoints and should only be used with other completions query fields. +:param stop: List[str] (optional) + The stop sequences field used ONLY for __completions__ and __chat external & foundation model__ + serving endpoints. This is a list of strings and should only be used with other chat/completions + query fields. +:param stream: bool (optional) + The stream field used ONLY for __completions__ and __chat external & foundation model__ serving + endpoints. This is a boolean defaulting to false and should only be used with other chat/completions + query fields. +:param temperature: float (optional) + 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` diff --git a/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst b/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst index 00d12fa36..18c9fd772 100644 --- a/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst +++ b/docs/workspace/settings/aibi_dashboard_embedding_access_policy.rst @@ -5,54 +5,53 @@ .. py:class:: AibiDashboardEmbeddingAccessPolicyAPI Controls whether AI/BI published dashboard embedding is enabled, conditionally enabled, or disabled at the - workspace level. By default, this setting is conditionally enabled (ALLOW_APPROVED_DOMAINS). +workspace level. By default, this setting is conditionally enabled (ALLOW_APPROVED_DOMAINS). .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`AibiDashboardEmbeddingAccessPolicySetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`AibiDashboardEmbeddingAccessPolicySetting` diff --git a/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst b/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst index d793e9a7c..4dc665dbb 100644 --- a/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst +++ b/docs/workspace/settings/aibi_dashboard_embedding_approved_domains.rst @@ -5,55 +5,54 @@ .. py:class:: AibiDashboardEmbeddingApprovedDomainsAPI Controls the list of domains approved to host the embedded AI/BI dashboards. The approved domains list - can't be mutated when the current access policy is not set to ALLOW_APPROVED_DOMAINS. +can't be mutated when the current access policy is not set to ALLOW_APPROVED_DOMAINS. .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` diff --git a/docs/workspace/settings/automatic_cluster_update.rst b/docs/workspace/settings/automatic_cluster_update.rst index 2219e1130..82805780e 100644 --- a/docs/workspace/settings/automatic_cluster_update.rst +++ b/docs/workspace/settings/automatic_cluster_update.rst @@ -5,40 +5,39 @@ .. py:class:: AutomaticClusterUpdateAPI Controls whether automatic cluster update is enabled for the current workspace. By default, it is turned - off. +off. .. 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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`AutomaticClusterUpdateSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`AutomaticClusterUpdateSetting` diff --git a/docs/workspace/settings/compliance_security_profile.rst b/docs/workspace/settings/compliance_security_profile.rst index f503830bc..d5530ec44 100644 --- a/docs/workspace/settings/compliance_security_profile.rst +++ b/docs/workspace/settings/compliance_security_profile.rst @@ -5,42 +5,41 @@ .. py:class:: ComplianceSecurityProfileAPI 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. +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`ComplianceSecurityProfileSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`ComplianceSecurityProfileSetting` diff --git a/docs/workspace/settings/credentials_manager.rst b/docs/workspace/settings/credentials_manager.rst index c8bfa4f30..eacb47eec 100644 --- a/docs/workspace/settings/credentials_manager.rst +++ b/docs/workspace/settings/credentials_manager.rst @@ -5,21 +5,20 @@ .. py:class:: CredentialsManagerAPI Credentials manager interacts with with Identity Providers to to perform token exchanges using stored - credentials and refresh tokens. +credentials and refresh tokens. .. 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 + +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` diff --git a/docs/workspace/settings/default_namespace.rst b/docs/workspace/settings/default_namespace.rst index 061a0e34e..fa767d0ba 100644 --- a/docs/workspace/settings/default_namespace.rst +++ b/docs/workspace/settings/default_namespace.rst @@ -5,76 +5,75 @@ .. py:class:: DefaultNamespaceAPI 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. +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` - + +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` - + +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` - This represents the setting configuration for the default namespace in the Databricks workspace. - Setting the default catalog for the workspace determines the catalog that is used when queries do - not reference a fully qualified 3 level name. For example, if the default catalog is set to - 'retail_prod' 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. - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`DefaultNamespaceSetting` - \ No newline at end of file + +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` + This represents the setting configuration for the default namespace in the Databricks workspace. + Setting the default catalog for the workspace determines the catalog that is used when queries do + not reference a fully qualified 3 level name. For example, if the default catalog is set to + 'retail_prod' 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. +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`DefaultNamespaceSetting` diff --git a/docs/workspace/settings/disable_legacy_access.rst b/docs/workspace/settings/disable_legacy_access.rst index c8baba3a7..4a3b7885f 100644 --- a/docs/workspace/settings/disable_legacy_access.rst +++ b/docs/workspace/settings/disable_legacy_access.rst @@ -5,57 +5,56 @@ .. 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 - Unity Catalog access on all path based access. + +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 +Unity Catalog access on all path based access. .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`DisableLegacyAccess` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`DisableLegacyAccess` diff --git a/docs/workspace/settings/disable_legacy_dbfs.rst b/docs/workspace/settings/disable_legacy_dbfs.rst index ad11fa606..69bf93608 100644 --- a/docs/workspace/settings/disable_legacy_dbfs.rst +++ b/docs/workspace/settings/disable_legacy_dbfs.rst @@ -5,53 +5,52 @@ .. py:class:: DisableLegacyDbfsAPI When this setting is on, access to DBFS root and DBFS mounts is disallowed (as well as creation of new - mounts). When the setting is off, all DBFS functionality is enabled +mounts). When the setting is off, all DBFS functionality is enabled .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`DisableLegacyDbfs` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`DisableLegacyDbfs` diff --git a/docs/workspace/settings/enhanced_security_monitoring.rst b/docs/workspace/settings/enhanced_security_monitoring.rst index fe7668973..9f6a4d190 100644 --- a/docs/workspace/settings/enhanced_security_monitoring.rst +++ b/docs/workspace/settings/enhanced_security_monitoring.rst @@ -5,44 +5,43 @@ .. py:class:: EnhancedSecurityMonitoringAPI 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. +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`EnhancedSecurityMonitoringSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`EnhancedSecurityMonitoringSetting` diff --git a/docs/workspace/settings/ip_access_lists.rst b/docs/workspace/settings/ip_access_lists.rst index a265c5943..162009162 100644 --- a/docs/workspace/settings/ip_access_lists.rst +++ b/docs/workspace/settings/ip_access_lists.rst @@ -5,22 +5,22 @@ .. 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. + +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 @@ -44,45 +44,45 @@ 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` - + +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 - - - + +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 @@ -108,14 +108,14 @@ 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` - + +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` + .. py:method:: list() -> Iterator[IpAccessListInfo] @@ -131,11 +131,11 @@ all = w.ip_access_lists.list() Get access lists. - - Gets all IP access lists for the specified workspace. - - :returns: Iterator over :class:`IpAccessListInfo` - + +Gets all IP access lists for the specified workspace. + +: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]]]) @@ -165,65 +165,64 @@ 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 - CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value - `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. 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) - - - + +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 +CIDR counts as a single value. Attempts to exceed that number return error 400 with `error_code` value +`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. 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) - Specifies whether this IP access list is enabled. - :param ip_addresses: List[str] (optional) - :param label: str (optional) - 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 + +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) + Specifies whether this IP access list is enabled. +:param ip_addresses: List[str] (optional) +:param label: str (optional) + 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. + + diff --git a/docs/workspace/settings/notification_destinations.rst b/docs/workspace/settings/notification_destinations.rst index 8fb2d0c3c..e43383704 100644 --- a/docs/workspace/settings/notification_destinations.rst +++ b/docs/workspace/settings/notification_destinations.rst @@ -5,71 +5,70 @@ .. py:class:: NotificationDestinationsAPI The notification destinations API lets you programmatically manage a workspace's notification - destinations. Notification destinations are used to send notifications for query alerts and jobs to - destinations outside of Databricks. Only workspace admins can create, update, and delete notification - destinations. +destinations. Notification destinations are used to send notifications for query alerts and jobs to +destinations outside of Databricks. Only workspace admins can create, update, and delete notification +destinations. .. 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` - + +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 - - - + +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` - + +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` - + +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 + +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` diff --git a/docs/workspace/settings/restrict_workspace_admins.rst b/docs/workspace/settings/restrict_workspace_admins.rst index 47660fda4..3c2e16b5a 100644 --- a/docs/workspace/settings/restrict_workspace_admins.rst +++ b/docs/workspace/settings/restrict_workspace_admins.rst @@ -5,66 +5,65 @@ .. py:class:: RestrictWorkspaceAdminsAPI The Restrict Workspace Admins setting lets you control the capabilities of workspace admins. With the - setting status set to ALLOW_ALL, workspace admins can create service principal personal access tokens on - behalf of any service principal in their workspace. Workspace admins can also change a job owner to any - user in their workspace. And they can change the job run_as setting to any user in their workspace or to a - service principal on which they have the Service Principal User role. With the setting status set to - RESTRICT_TOKENS_AND_JOB_RUN_AS, workspace admins can only create personal access tokens on behalf of - service principals they have the Service Principal User role on. They can also only change a job owner to - themselves. And they can change the job run_as setting to themselves or to a service principal on which - they have the Service Principal User role. +setting status set to ALLOW_ALL, workspace admins can create service principal personal access tokens on +behalf of any service principal in their workspace. Workspace admins can also change a job owner to any +user in their workspace. And they can change the job run_as setting to any user in their workspace or to a +service principal on which they have the Service Principal User role. With the setting status set to +RESTRICT_TOKENS_AND_JOB_RUN_AS, workspace admins can only create personal access tokens on behalf of +service principals they have the Service Principal User role on. They can also only change a job owner to +themselves. And they can change the job run_as setting to themselves or to a service principal on which +they have the Service Principal User role. .. 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` - + +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` - + +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` - :param field_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - - :returns: :class:`RestrictWorkspaceAdminsSetting` - \ No newline at end of file + +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` +:param field_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). + +:returns: :class:`RestrictWorkspaceAdminsSetting` diff --git a/docs/workspace/settings/settings.rst b/docs/workspace/settings/settings.rst index aa806280e..8338866ec 100644 --- a/docs/workspace/settings/settings.rst +++ b/docs/workspace/settings/settings.rst @@ -10,77 +10,77 @@ :type: AibiDashboardEmbeddingAccessPolicyAPI Controls whether AI/BI published dashboard embedding is enabled, conditionally enabled, or disabled at the - workspace level. By default, this setting is conditionally enabled (ALLOW_APPROVED_DOMAINS). + workspace level. By default, this setting is conditionally enabled (ALLOW_APPROVED_DOMAINS). .. py:property:: aibi_dashboard_embedding_approved_domains :type: AibiDashboardEmbeddingApprovedDomainsAPI Controls the list of domains approved to host the embedded AI/BI dashboards. The approved domains list - can't be mutated when the current access policy is not set to ALLOW_APPROVED_DOMAINS. + can't be mutated when the current access policy is not set to ALLOW_APPROVED_DOMAINS. .. py:property:: automatic_cluster_update :type: AutomaticClusterUpdateAPI Controls whether automatic cluster update is enabled for the current workspace. By default, it is turned - off. + off. .. py:property:: compliance_security_profile :type: ComplianceSecurityProfileAPI 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. + workspace is permanent. By default, it is turned off. + + This settings can NOT be disabled once it is enabled. .. py:property:: default_namespace :type: DefaultNamespaceAPI 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. + 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:property:: disable_legacy_access :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 - Unity Catalog access on all path based access. + + 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 + Unity Catalog access on all path based access. .. py:property:: disable_legacy_dbfs :type: DisableLegacyDbfsAPI When this setting is on, access to DBFS root and DBFS mounts is disallowed (as well as creation of new - mounts). When the setting is off, all DBFS functionality is enabled + mounts). When the setting is off, all DBFS functionality is enabled .. py:property:: enhanced_security_monitoring :type: EnhancedSecurityMonitoringAPI 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. + 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:property:: restrict_workspace_admins :type: RestrictWorkspaceAdminsAPI The Restrict Workspace Admins setting lets you control the capabilities of workspace admins. With the - setting status set to ALLOW_ALL, workspace admins can create service principal personal access tokens on - behalf of any service principal in their workspace. Workspace admins can also change a job owner to any - user in their workspace. And they can change the job run_as setting to any user in their workspace or to a - service principal on which they have the Service Principal User role. With the setting status set to - RESTRICT_TOKENS_AND_JOB_RUN_AS, workspace admins can only create personal access tokens on behalf of - service principals they have the Service Principal User role on. They can also only change a job owner to - themselves. And they can change the job run_as setting to themselves or to a service principal on which - they have the Service Principal User role. \ No newline at end of file + setting status set to ALLOW_ALL, workspace admins can create service principal personal access tokens on + behalf of any service principal in their workspace. Workspace admins can also change a job owner to any + user in their workspace. And they can change the job run_as setting to any user in their workspace or to a + service principal on which they have the Service Principal User role. With the setting status set to + RESTRICT_TOKENS_AND_JOB_RUN_AS, workspace admins can only create personal access tokens on behalf of + service principals they have the Service Principal User role on. They can also only change a job owner to + themselves. And they can change the job run_as setting to themselves or to a service principal on which + they have the Service Principal User role. \ No newline at end of file diff --git a/docs/workspace/settings/token_management.rst b/docs/workspace/settings/token_management.rst index 50dbe1328..a2fe7ddea 100644 --- a/docs/workspace/settings/token_management.rst +++ b/docs/workspace/settings/token_management.rst @@ -5,7 +5,7 @@ .. py:class:: TokenManagementAPI Enables administrators to get all tokens and delete tokens for other users. Admins can either get every - token, get a specific token by ID, or get all tokens for a particular user. +token, get a specific token by ID, or get all tokens for a particular user. .. py:method:: create_obo_token(application_id: str [, comment: Optional[str], lifetime_seconds: Optional[int]]) -> CreateOboTokenResponse @@ -33,30 +33,30 @@ 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` - + +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. - - - + +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 @@ -86,32 +86,32 @@ 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` - + +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` - + +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` - + +Gets the permissions of all tokens. Tokens can inherit permissions from their root object. + +:returns: :class:`TokenPermissions` + .. py:method:: list( [, created_by_id: Optional[int], created_by_username: Optional[str]]) -> Iterator[TokenInfo] @@ -128,36 +128,35 @@ 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` - + +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` - + +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 + +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` diff --git a/docs/workspace/settings/tokens.rst b/docs/workspace/settings/tokens.rst index 899db00d1..273909746 100644 --- a/docs/workspace/settings/tokens.rst +++ b/docs/workspace/settings/tokens.rst @@ -5,7 +5,7 @@ .. py:class:: TokensAPI The Token API allows you to create, list, and revoke tokens that can be used to authenticate and access - Databricks REST APIs. +Databricks REST APIs. .. py:method:: create( [, comment: Optional[str], lifetime_seconds: Optional[int]]) -> CreateTokenResponse @@ -26,34 +26,34 @@ 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` - + +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. - - - + +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,7 @@ 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 + +Lists all the valid tokens for a user-workspace pair. + +:returns: Iterator over :class:`PublicTokenInfo` diff --git a/docs/workspace/settings/workspace_conf.rst b/docs/workspace/settings/workspace_conf.rst index 3759de043..a3533f564 100644 --- a/docs/workspace/settings/workspace_conf.rst +++ b/docs/workspace/settings/workspace_conf.rst @@ -20,20 +20,19 @@ 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] - + +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 + +Sets the configuration status for a workspace, including enabling or disabling it. + + + diff --git a/docs/workspace/sharing/providers.rst b/docs/workspace/sharing/providers.rst index 7cf398ac0..9b3f61ee8 100644 --- a/docs/workspace/sharing/providers.rst +++ b/docs/workspace/sharing/providers.rst @@ -5,7 +5,7 @@ .. py: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. +provider contains shares which further contain the shared data. .. py:method:: create(name: str, authentication_type: AuthenticationType [, comment: Optional[str], recipient_profile_str: Optional[str]]) -> ProviderInfo @@ -33,34 +33,34 @@ 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` - The delta sharing authentication type. - :param comment: str (optional) - Description about the provider. - :param recipient_profile_str: str (optional) - This field is required when the __authentication_type__ is **TOKEN** or not provided. - - :returns: :class:`ProviderInfo` - + +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` + The delta sharing authentication type. +:param comment: str (optional) + Description about the provider. +:param recipient_profile_str: str (optional) + This field is required when the __authentication_type__ is **TOKEN** 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. - - - + +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 @@ -90,15 +90,15 @@ 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` - + +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` + .. py:method:: list( [, data_provider_global_metastore_id: Optional[str], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ProviderInfo] @@ -115,27 +115,27 @@ 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. - :param max_results: int (optional) - Maximum number of providers 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 providers are returned (not recommended). - Note: The - number of returned providers might be less than the specified max_results size, even zero. The only - definitive indication that no further providers 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: Iterator over :class:`ProviderInfo` - + +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. +:param max_results: int (optional) + Maximum number of providers 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 providers are returned (not recommended). - Note: The + number of returned providers might be less than the specified max_results size, even zero. The only + definitive indication that no further providers 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: Iterator over :class:`ProviderInfo` + .. py:method:: list_shares(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ProviderShare] @@ -165,26 +165,26 @@ 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) - 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 - 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 shares are returned (not recommended). - Note: The number of - returned shares might be less than the specified max_results size, even zero. The only definitive - indication that no further shares 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: Iterator over :class:`ProviderShare` - + +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) + 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 + 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 shares are returned (not recommended). - Note: The number of + returned shares might be less than the specified max_results size, even zero. The only definitive + indication that no further shares 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: Iterator over :class:`ProviderShare` + .. py:method:: update(name: str [, comment: Optional[str], new_name: Optional[str], owner: Optional[str], recipient_profile_str: Optional[str]]) -> ProviderInfo @@ -214,21 +214,20 @@ 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) - Description about the provider. - :param new_name: str (optional) - New name for the provider. - :param owner: str (optional) - Username of Provider owner. - :param recipient_profile_str: str (optional) - This field is required when the __authentication_type__ is **TOKEN** or not provided. - - :returns: :class:`ProviderInfo` - \ No newline at end of file + +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) + Description about the provider. +:param new_name: str (optional) + New name for the provider. +:param owner: str (optional) + Username of Provider owner. +:param recipient_profile_str: str (optional) + This field is required when the __authentication_type__ is **TOKEN** or not provided. + +:returns: :class:`ProviderInfo` diff --git a/docs/workspace/sharing/recipient_activation.rst b/docs/workspace/sharing/recipient_activation.rst index 2c214d9c0..4ac315098 100644 --- a/docs/workspace/sharing/recipient_activation.rst +++ b/docs/workspace/sharing/recipient_activation.rst @@ -5,33 +5,32 @@ .. py:class:: RecipientActivationAPI The Recipient Activation API is only applicable in the open sharing model where the recipient object has - 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. +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. - - - + +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 + +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` diff --git a/docs/workspace/sharing/recipients.rst b/docs/workspace/sharing/recipients.rst index 44f2042bb..de90501fa 100644 --- a/docs/workspace/sharing/recipients.rst +++ b/docs/workspace/sharing/recipients.rst @@ -5,18 +5,18 @@ .. py:class:: RecipientsAPI 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 - to establish a secure connection to receive the shared data. This sharing mode is called **open sharing**. +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 +to establish a secure connection to receive the shared data. This sharing mode is called **open sharing**. .. py:method:: create(name: str, authentication_type: AuthenticationType [, comment: Optional[str], data_recipient_global_metastore_id: Optional[str], expiration_time: Optional[int], ip_access_list: Optional[IpAccessList], owner: Optional[str], properties_kvpairs: Optional[SecurablePropertiesKvPairs], sharing_code: Optional[str]]) -> RecipientInfo @@ -37,46 +37,46 @@ 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 has the **CREATE_RECIPIENT** privilege on the metastore. - - :param name: str - Name of Recipient. - :param authentication_type: :class:`AuthenticationType` - The delta sharing authentication type. - :param comment: str (optional) - Description about the recipient. - :param data_recipient_global_metastore_id: str (optional) - The global Unity Catalog metastore id provided by the data recipient. This field is required when - the __authentication_type__ is **DATABRICKS**. The identifier is of format - __cloud__:__region__:__metastore-uuid__. - :param expiration_time: int (optional) - Expiration timestamp of the token, in epoch milliseconds. - :param ip_access_list: :class:`IpAccessList` (optional) - IP Access List - :param owner: str (optional) - Username of the recipient owner. - :param properties_kvpairs: :class:`SecurablePropertiesKvPairs` (optional) - Recipient properties as map of string key-value pairs. - :param sharing_code: str (optional) - The one-time sharing code provided by the data recipient. This field is required when the - __authentication_type__ is **DATABRICKS**. - - :returns: :class:`RecipientInfo` - + +Creates a new recipient with the delta sharing authentication type in the metastore. The caller must +be a metastore admin or has the **CREATE_RECIPIENT** privilege on the metastore. + +:param name: str + Name of Recipient. +:param authentication_type: :class:`AuthenticationType` + The delta sharing authentication type. +:param comment: str (optional) + Description about the recipient. +:param data_recipient_global_metastore_id: str (optional) + The global Unity Catalog metastore id provided by the data recipient. This field is required when + the __authentication_type__ is **DATABRICKS**. The identifier is of format + __cloud__:__region__:__metastore-uuid__. +:param expiration_time: int (optional) + Expiration timestamp of the token, in epoch milliseconds. +:param ip_access_list: :class:`IpAccessList` (optional) + IP Access List +:param owner: str (optional) + Username of the recipient owner. +:param properties_kvpairs: :class:`SecurablePropertiesKvPairs` (optional) + Recipient properties as map of string key-value pairs. +:param sharing_code: str (optional) + The one-time sharing code provided by the data recipient. This field is required 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. - - - + +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 @@ -99,16 +99,16 @@ 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` - + +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` + .. py:method:: list( [, data_recipient_global_metastore_id: Optional[str], max_results: Optional[int], page_token: Optional[str]]) -> Iterator[RecipientInfo] @@ -125,28 +125,28 @@ 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. - :param max_results: int (optional) - Maximum number of recipients 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 recipients are returned (not recommended). - Note: The - number of returned recipients might be less than the specified max_results size, even zero. The only - definitive indication that no further recipients 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: Iterator over :class:`RecipientInfo` - + +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. +:param max_results: int (optional) + Maximum number of recipients 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 recipients are returned (not recommended). - Note: The + number of returned recipients might be less than the specified max_results size, even zero. The only + definitive indication that no further recipients 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: Iterator over :class:`RecipientInfo` + .. py:method:: rotate_token(name: str, existing_token_expire_in_seconds: int) -> RecipientInfo @@ -169,19 +169,19 @@ 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` - + +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` + .. py:method:: share_permissions(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> GetRecipientSharePermissionsResponse @@ -204,25 +204,25 @@ 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) - 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:`GetRecipientSharePermissionsResponse` - + +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) + 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:`GetRecipientSharePermissionsResponse` + .. py:method:: update(name: str [, comment: Optional[str], expiration_time: Optional[int], ip_access_list: Optional[IpAccessList], new_name: Optional[str], owner: Optional[str], properties_kvpairs: Optional[SecurablePropertiesKvPairs]]) @@ -245,27 +245,26 @@ 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) - Description about the recipient. - :param expiration_time: int (optional) - Expiration timestamp of the token, in epoch milliseconds. - :param ip_access_list: :class:`IpAccessList` (optional) - IP Access List - :param new_name: str (optional) - New name for the recipient. - :param owner: str (optional) - Username of the recipient owner. - :param properties_kvpairs: :class:`SecurablePropertiesKvPairs` (optional) - 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. - - - \ No newline at end of file + +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) + Description about the recipient. +:param expiration_time: int (optional) + Expiration timestamp of the token, in epoch milliseconds. +:param ip_access_list: :class:`IpAccessList` (optional) + IP Access List +:param new_name: str (optional) + New name for the recipient. +:param owner: str (optional) + Username of the recipient owner. +:param properties_kvpairs: :class:`SecurablePropertiesKvPairs` (optional) + 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. + + diff --git a/docs/workspace/sharing/shares.rst b/docs/workspace/sharing/shares.rst index 4d14b811d..f1c10ebeb 100644 --- a/docs/workspace/sharing/shares.rst +++ b/docs/workspace/sharing/shares.rst @@ -5,9 +5,9 @@ .. py:class:: SharesAPI A share is a container instantiated with :method:shares/create. Once created you can iteratively register - a collection of existing data assets defined within the metastore using :method:shares/update. You can - register data assets under their original name, qualified by their original schema, or provide alternate - exposed names. +a collection of existing data assets defined within the metastore using :method:shares/update. You can +register data assets under their original name, qualified by their original schema, or provide alternate +exposed names. .. py:method:: create(name: str [, comment: Optional[str], storage_root: Optional[str]]) -> ShareInfo @@ -28,31 +28,31 @@ 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` - + +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. - - - + +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 @@ -75,17 +75,17 @@ 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` - + +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` + .. py:method:: list( [, max_results: Optional[int], page_token: Optional[str]]) -> Iterator[ShareInfo] @@ -102,46 +102,46 @@ 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 - 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 shares are returned (not recommended). - Note: The number of - returned shares might be less than the specified max_results size, even zero. The only definitive - indication that no further shares 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: Iterator over :class:`ShareInfo` - + +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 + 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 shares are returned (not recommended). - Note: The number of + returned shares might be less than the specified max_results size, even zero. The only definitive + indication that no further shares 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: Iterator over :class:`ShareInfo` + .. py:method:: share_permissions(name: str [, max_results: Optional[int], page_token: Optional[str]]) -> catalog.PermissionsList 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) - 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:`PermissionsList` - + +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) + 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:`PermissionsList` + .. py:method:: update(name: str [, comment: Optional[str], new_name: Optional[str], owner: Optional[str], storage_root: Optional[str], updates: Optional[List[SharedDataObjectUpdate]]]) -> ShareInfo @@ -189,63 +189,62 @@ 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) - User-provided free-form text description. - :param new_name: str (optional) - New name for the share. - :param owner: str (optional) - Username of current owner of share. - :param storage_root: str (optional) - Storage root URL for the share. - :param updates: List[:class:`SharedDataObjectUpdate`] (optional) - Array of shared data object updates. - - :returns: :class:`ShareInfo` - + +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) + User-provided free-form text description. +:param new_name: str (optional) + New name for the share. +:param owner: str (optional) + Username of current owner of share. +:param storage_root: str (optional) + 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]]) 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. - - :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. - - - \ No newline at end of file + +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. + +: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. + + diff --git a/docs/workspace/sql/alerts.rst b/docs/workspace/sql/alerts.rst index c552d5f80..28d59a56e 100644 --- a/docs/workspace/sql/alerts.rst +++ b/docs/workspace/sql/alerts.rst @@ -5,9 +5,9 @@ .. py:class:: AlertsAPI The alerts API can be used to perform CRUD operations on alerts. An alert is a Databricks SQL object that - 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. +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. .. py:method:: create( [, alert: Optional[CreateAlertRequestAlert]]) -> Alert @@ -45,26 +45,26 @@ w.alerts.delete(id=alert.id) Create an alert. - - Creates an alert. - - :param alert: :class:`CreateAlertRequestAlert` (optional) - - :returns: :class:`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 - - - + +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 @@ -104,13 +104,13 @@ w.alerts.delete(id=alert.id) Get an alert. - - Gets an alert. - - :param id: str - - :returns: :class:`Alert` - + +Gets an alert. + +:param id: str + +:returns: :class:`Alert` + .. py:method:: list( [, page_size: Optional[int], page_token: Optional[str]]) -> Iterator[ListAlertsResponseAlert] @@ -127,15 +127,15 @@ 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` - + +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` + .. py:method:: update(id: str, update_mask: str [, alert: Optional[UpdateAlertRequestAlert]]) -> Alert @@ -177,15 +177,14 @@ w.alerts.delete(id=alert.id) Update an alert. - - Updates an alert. - - :param id: str - :param update_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - :param alert: :class:`UpdateAlertRequestAlert` (optional) - - :returns: :class:`Alert` - \ No newline at end of file + +Updates an alert. + +:param id: str +:param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). +:param alert: :class:`UpdateAlertRequestAlert` (optional) + +:returns: :class:`Alert` diff --git a/docs/workspace/sql/alerts_legacy.rst b/docs/workspace/sql/alerts_legacy.rst index 6dfd96128..e5f11673e 100644 --- a/docs/workspace/sql/alerts_legacy.rst +++ b/docs/workspace/sql/alerts_legacy.rst @@ -5,110 +5,109 @@ .. py:class:: AlertsLegacyAPI The alerts API can be used to perform CRUD operations on alerts. An alert is a Databricks SQL object that - 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 +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` - Alert configuration options. - :param query_id: str - Query ID. - :param parent: str (optional) - The identifier of the workspace folder containing the object. - :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` - + +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` + Alert configuration options. +:param query_id: str + Query ID. +:param parent: str (optional) + The identifier of the workspace folder containing the object. +: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 - - - + +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` - + +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` - + +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. - :param options: :class:`AlertOptions` - Alert configuration options. - :param query_id: str - Query ID. - :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 + +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. +:param options: :class:`AlertOptions` + Alert configuration options. +:param query_id: str + Query ID. +: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. + + diff --git a/docs/workspace/sql/dashboard_widgets.rst b/docs/workspace/sql/dashboard_widgets.rst index d4bbcde1d..df6a37f35 100644 --- a/docs/workspace/sql/dashboard_widgets.rst +++ b/docs/workspace/sql/dashboard_widgets.rst @@ -5,52 +5,51 @@ .. py:class:: DashboardWidgetsAPI This is an evolving API that facilitates the addition and removal of widgets from existing dashboards - within the Databricks Workspace. Data structures may change over time. +within the Databricks Workspace. Data structures may change over time. .. 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` - :param width: int - Width of a widget - :param text: str (optional) - If this is a textbox widget, the application displays this text. This field is ignored if the widget - contains a visualization in the `visualization` field. - :param visualization_id: str (optional) - Query Vizualization ID returned by :method:queryvisualizations/create. - - :returns: :class:`Widget` - + +:param dashboard_id: str + Dashboard ID returned by :method:dashboards/create. +:param options: :class:`WidgetOptions` +:param width: int + Width of a widget +:param text: str (optional) + If this is a textbox widget, the application displays this text. This field is ignored if the widget + 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 - - - + +: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 - Dashboard ID returned by :method:dashboards/create. - :param options: :class:`WidgetOptions` - :param width: int - Width of a widget - :param text: str (optional) - If this is a textbox widget, the application displays this text. This field is ignored if the widget - 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 + +:param id: str + Widget ID returned by :method:dashboardwidgets/create +:param dashboard_id: str + Dashboard ID returned by :method:dashboards/create. +:param options: :class:`WidgetOptions` +:param width: int + Width of a widget +:param text: str (optional) + If this is a textbox widget, the application displays this text. This field is ignored if the widget + contains a visualization in the `visualization` field. +:param visualization_id: str (optional) + Query Vizualization ID returned by :method:queryvisualizations/create. + +:returns: :class:`Widget` diff --git a/docs/workspace/sql/dashboards.rst b/docs/workspace/sql/dashboards.rst index f22c7c96b..2b44a1edd 100644 --- a/docs/workspace/sql/dashboards.rst +++ b/docs/workspace/sql/dashboards.rst @@ -5,10 +5,10 @@ .. py:class:: DashboardsAPI In general, there is little need to modify dashboards using the API. However, it can be useful to use - dashboard objects to look-up a collection of related query IDs. The API can also be used to duplicate - multiple dashboards at once since you can get a dashboard definition with a GET request and then POST it - to create a new one. Dashboards can be scheduled using the `sql_task` type of the Jobs API, e.g. - :method:jobs/create. +dashboard objects to look-up a collection of related query IDs. The API can also be used to duplicate +multiple dashboards at once since you can get a dashboard definition with a GET request and then POST it +to create a new one. Dashboards can be scheduled using the `sql_task` type of the Jobs API, e.g. +:method:jobs/create. .. py:method:: create(name: str [, dashboard_filters_enabled: Optional[bool], is_favorite: Optional[bool], parent: Optional[str], run_as_role: Optional[RunAsRole], tags: Optional[List[str]]]) -> Dashboard @@ -29,22 +29,22 @@ 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) - Indicates whether the dashboard filters are enabled - :param is_favorite: bool (optional) - Indicates whether this dashboard object should appear in the current user's favorites list. - :param parent: str (optional) - The identifier of the workspace folder containing the object. - :param run_as_role: :class:`RunAsRole` (optional) - 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` - + +: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) + Indicates whether the dashboard filters are enabled +:param is_favorite: bool (optional) + Indicates whether this dashboard object should appear in the current user's favorites list. +:param parent: str (optional) + The identifier of the workspace folder containing the object. +:param run_as_role: :class:`RunAsRole` (optional) + 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` + .. py:method:: delete(dashboard_id: str) @@ -67,14 +67,14 @@ 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 - - - + +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 @@ -97,13 +97,13 @@ 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` - + +Returns a JSON representation of a dashboard object, including its visualization and query objects. + +:param dashboard_id: str + +:returns: :class:`Dashboard` + .. py:method:: list( [, order: Optional[ListOrder], page: Optional[int], page_size: Optional[int], q: Optional[str]]) -> Iterator[Dashboard] @@ -120,23 +120,23 @@ 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) - Page number to retrieve. - :param page_size: int (optional) - Number of dashboards to return per page. - :param q: str (optional) - Full text search term. - - :returns: Iterator over :class:`Dashboard` - + +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) + Page number to retrieve. +:param page_size: int (optional) + Number of dashboards to return per page. +:param q: str (optional) + Full text search term. + +:returns: Iterator over :class:`Dashboard` + .. py:method:: restore(dashboard_id: str) @@ -159,30 +159,29 @@ 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 - - - + +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. - :param run_as_role: :class:`RunAsRole` (optional) - 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 + +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. +:param run_as_role: :class:`RunAsRole` (optional) + 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` diff --git a/docs/workspace/sql/data_sources.rst b/docs/workspace/sql/data_sources.rst index 8f7321fa0..4b05ce137 100644 --- a/docs/workspace/sql/data_sources.rst +++ b/docs/workspace/sql/data_sources.rst @@ -5,16 +5,16 @@ .. py:class:: DataSourcesAPI 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 +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,14 @@ 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 + +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` diff --git a/docs/workspace/sql/dbsql_permissions.rst b/docs/workspace/sql/dbsql_permissions.rst index 7f9e5d19c..18da30ff0 100644 --- a/docs/workspace/sql/dbsql_permissions.rst +++ b/docs/workspace/sql/dbsql_permissions.rst @@ -5,78 +5,77 @@ .. py:class:: DbsqlPermissionsAPI 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 +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` - + +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` - + +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 + +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` diff --git a/docs/workspace/sql/queries.rst b/docs/workspace/sql/queries.rst index 1f01c2f1d..c38b46291 100644 --- a/docs/workspace/sql/queries.rst +++ b/docs/workspace/sql/queries.rst @@ -5,8 +5,8 @@ .. py:class:: QueriesAPI The queries API can be used to perform CRUD operations on queries. A query is a Databricks SQL object that - includes the target SQL warehouse, query text, name, description, tags, and parameters. Queries can be - scheduled using the `sql_task` type of the Jobs API, e.g. :method:jobs/create. +includes the target SQL warehouse, query text, name, description, tags, and parameters. Queries can be +scheduled using the `sql_task` type of the Jobs API, e.g. :method:jobs/create. .. py:method:: create( [, query: Optional[CreateQueryRequestQuery]]) -> Query @@ -33,26 +33,26 @@ w.queries.delete(id=query.id) Create a query. - - Creates a query. - - :param query: :class:`CreateQueryRequestQuery` (optional) - - :returns: :class:`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 - - - + +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 @@ -81,39 +81,39 @@ w.queries.delete(id=query.id) Get a query. - - Gets a query. - - :param id: str - - :returns: :class:`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` - + +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` - + +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` + .. py:method:: update(id: str, update_mask: str [, query: Optional[UpdateQueryRequestQuery]]) -> Query @@ -146,15 +146,14 @@ w.queries.delete(id=query.id) Update a query. - - Updates a query. - - :param id: str - :param update_mask: str - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - :param query: :class:`UpdateQueryRequestQuery` (optional) - - :returns: :class:`Query` - \ No newline at end of file + +Updates a query. + +:param id: str +:param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). +:param query: :class:`UpdateQueryRequestQuery` (optional) + +:returns: :class:`Query` diff --git a/docs/workspace/sql/queries_legacy.rst b/docs/workspace/sql/queries_legacy.rst index a7ab56836..694be0946 100644 --- a/docs/workspace/sql/queries_legacy.rst +++ b/docs/workspace/sql/queries_legacy.rst @@ -5,179 +5,178 @@ .. py:class:: QueriesLegacyAPI 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 +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. - :param name: str (optional) - The title of this query that appears in list views, widget headings, and on the query page. - :param options: Any (optional) - Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, - `name`, `type`, and `value` properties. The `value` field here is the default value. It can be - overridden at runtime. - :param parent: str (optional) - The identifier of the workspace folder containing the object. - :param query: str (optional) - The text of the query to be run. - :param run_as_role: :class:`RunAsRole` (optional) - 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` - + +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. +:param name: str (optional) + The title of this query that appears in list views, widget headings, and on the query page. +:param options: Any (optional) + Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, + `name`, `type`, and `value` properties. The `value` field here is the default value. It can be + overridden at runtime. +:param parent: str (optional) + The identifier of the workspace folder containing the object. +:param query: str (optional) + The text of the query to be run. +:param run_as_role: :class:`RunAsRole` (optional) + 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 - - - + +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` - + +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. - :param page_size: int (optional) - Number of queries to return per page. - :param q: str (optional) - Full text search term - - :returns: Iterator over :class:`LegacyQuery` - + +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. +:param page_size: int (optional) + 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 - - - + +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. - :param name: str (optional) - The title of this query that appears in list views, widget headings, and on the query page. - :param options: Any (optional) - Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, - `name`, `type`, and `value` properties. The `value` field here is the default value. It can be - overridden at runtime. - :param query: str (optional) - The text of the query to be run. - :param run_as_role: :class:`RunAsRole` (optional) - 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 + +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. +:param name: str (optional) + The title of this query that appears in list views, widget headings, and on the query page. +:param options: Any (optional) + Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, + `name`, `type`, and `value` properties. The `value` field here is the default value. It can be + overridden at runtime. +:param query: str (optional) + The text of the query to be run. +:param run_as_role: :class:`RunAsRole` (optional) + 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` diff --git a/docs/workspace/sql/query_history.rst b/docs/workspace/sql/query_history.rst index 2f5520cdf..30d1db6ce 100644 --- a/docs/workspace/sql/query_history.rst +++ b/docs/workspace/sql/query_history.rst @@ -5,7 +5,7 @@ .. py:class:: QueryHistoryAPI A service responsible for storing and retrieving the list of queries run against SQL endpoints and - serverless compute. +serverless compute. .. py:method:: list( [, filter_by: Optional[QueryFilter], include_metrics: Optional[bool], max_results: Optional[int], page_token: Optional[str]]) -> ListQueriesResponse @@ -23,24 +23,23 @@ 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) - Whether to include the query metrics with each query. Only use this for a small subset of queries - (max_results). Defaults to false. - :param max_results: int (optional) - Limit the number of results returned in one page. Must be less than 1000 and the default is 100. - :param page_token: str (optional) - 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 + +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) + Whether to include the query metrics with each query. Only use this for a small subset of queries + (max_results). Defaults to false. +:param max_results: int (optional) + Limit the number of results returned in one page. Must be less than 1000 and the default is 100. +:param page_token: str (optional) + 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` diff --git a/docs/workspace/sql/query_visualizations.rst b/docs/workspace/sql/query_visualizations.rst index 95095fb20..39535d950 100644 --- a/docs/workspace/sql/query_visualizations.rst +++ b/docs/workspace/sql/query_visualizations.rst @@ -5,42 +5,41 @@ .. py:class:: QueryVisualizationsAPI This is an evolving API that facilitates the addition and removal of visualizations from existing queries - in the Databricks Workspace. Data structures can change over time. +in the Databricks Workspace. Data structures can change over time. .. 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` - + +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 - - - + +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 - Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the - setting payload will be updated. The field mask needs to be supplied as single string. To specify - multiple fields in the field mask, use comma as the separator (no space). - :param visualization: :class:`UpdateVisualizationRequestVisualization` (optional) - - :returns: :class:`Visualization` - \ No newline at end of file + +Updates a visualization. + +:param id: str +:param update_mask: str + Field mask is required to be passed into the PATCH request. Field mask specifies which fields of the + setting payload will be updated. The field mask needs to be supplied as single string. To specify + multiple fields in the field mask, use comma as the separator (no space). +:param visualization: :class:`UpdateVisualizationRequestVisualization` (optional) + +:returns: :class:`Visualization` diff --git a/docs/workspace/sql/query_visualizations_legacy.rst b/docs/workspace/sql/query_visualizations_legacy.rst index f56f78a5f..aca56b516 100644 --- a/docs/workspace/sql/query_visualizations_legacy.rst +++ b/docs/workspace/sql/query_visualizations_legacy.rst @@ -5,81 +5,80 @@ .. py:class:: QueryVisualizationsLegacyAPI 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 +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 - The type of visualization: chart, table, pivot table, and so on. - :param options: Any - The options object varies widely from one visualization type to the next and is unsupported. - Databricks does not recommend modifying visualization settings in JSON. - :param description: str (optional) - 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` - + +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 + The type of visualization: chart, table, pivot table, and so on. +:param options: Any + The options object varies widely from one visualization type to the next and is unsupported. + Databricks does not recommend modifying visualization settings in JSON. +:param description: str (optional) + 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 - - - + +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) - :param description: str (optional) - 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. - :param options: Any (optional) - The options object varies widely from one visualization type to the next and is unsupported. - Databricks does not recommend modifying visualization settings in JSON. - :param query: :class:`LegacyQuery` (optional) - :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 + +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) +:param description: str (optional) + 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. +:param options: Any (optional) + The options object varies widely from one visualization type to the next and is unsupported. + Databricks does not recommend modifying visualization settings in JSON. +:param query: :class:`LegacyQuery` (optional) +:param type: str (optional) + The type of visualization: chart, table, pivot table, and so on. +:param updated_at: str (optional) + +:returns: :class:`LegacyVisualization` diff --git a/docs/workspace/sql/statement_execution.rst b/docs/workspace/sql/statement_execution.rst index 44f64b512..1fd0d3407 100644 --- a/docs/workspace/sql/statement_execution.rst +++ b/docs/workspace/sql/statement_execution.rst @@ -5,248 +5,247 @@ .. py:class:: StatementExecutionAPI 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 - the statement has completed within this timespan, the response will include the result data as a JSON - 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 - the specified timeout; when set to `0s`, the call is asynchronous and responds immediately with a - 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 - with a `CANCELED` state. - Asynchronous mode - `wait_timeout=0s` (`on_wait_timeout` is ignored) - The call - doesn't wait for the statement to finish but returns directly with a statement ID. The status of the - statement execution can be polled by issuing :method:statementexecution/getStatement with the statement - ID. Once the execution has succeeded, this call also returns the result and metadata in the response. - - Hybrid mode (default) - `wait_timeout=10s` and `on_wait_timeout=CONTINUE` - The call waits for up to 10 - 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 - query text size is 16 MiB. - Cancelation might silently fail. A successful response from a cancel request - indicates that the cancel request was successfully received and sent to the processing engine. However, an - outstanding statement might have already completed execution when the cancel request arrives. Polling for - status until a terminal state is reached is a reliable way to determine the final state. - Wait timeouts - are approximate, occur server-side, and cannot account for things such as caller delays and network - latency from caller to service. - To guarantee that the statement is kept alive, you must poll at least - 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 +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 +the statement has completed within this timespan, the response will include the result data as a JSON +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 +the specified timeout; when set to `0s`, the call is asynchronous and responds immediately with a +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 +with a `CANCELED` state. - Asynchronous mode - `wait_timeout=0s` (`on_wait_timeout` is ignored) - The call +doesn't wait for the statement to finish but returns directly with a statement ID. The status of the +statement execution can be polled by issuing :method:statementexecution/getStatement with the statement +ID. Once the execution has succeeded, this call also returns the result and metadata in the response. - +Hybrid mode (default) - `wait_timeout=10s` and `on_wait_timeout=CONTINUE` - The call waits for up to 10 +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 +query text size is 16 MiB. - Cancelation might silently fail. A successful response from a cancel request +indicates that the cancel request was successfully received and sent to the processing engine. However, an +outstanding statement might have already completed execution when the cancel request arrives. Polling for +status until a terminal state is reached is a reliable way to determine the final state. - Wait timeouts +are approximate, occur server-side, and cannot account for things such as caller delays and network +latency from caller to service. - To guarantee that the statement is kept alive, you must poll at least +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. - - - + +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 - representations and might not match the final size in the requested `format`. If the result was - truncated due to the byte limit, then `truncated` in the response is set to `true`. When using - `EXTERNAL_LINKS` disposition, a default `byte_limit` of 100 GiB is applied if `byte_limit` is not - 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) - When `wait_timeout > 0s`, the call will block up to the specified time. If the statement execution - doesn't finish within this time, `on_wait_timeout` determines whether the execution should continue - or be canceled. When set to `CONTINUE`, the statement execution continues asynchronously and the - call returns a statement ID which can be used for polling with - :method:statementexecution/getStatement. When set to `CANCEL`, the statement execution is canceled - and the call returns with a `CANCELED` state. - :param parameters: List[:class:`StatementParameterListItem`] (optional) - A list of parameters to pass into a SQL statement containing parameter markers. A parameter consists - 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) - Applies the given row limit to the statement's result set, but unlike the `LIMIT` clause in SQL, it - also sets the `truncated` field in the response to indicate whether the result was trimmed due to - 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` - + +: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 + representations and might not match the final size in the requested `format`. If the result was + truncated due to the byte limit, then `truncated` in the response is set to `true`. When using + `EXTERNAL_LINKS` disposition, a default `byte_limit` of 100 GiB is applied if `byte_limit` is not + 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) + When `wait_timeout > 0s`, the call will block up to the specified time. If the statement execution + doesn't finish within this time, `on_wait_timeout` determines whether the execution should continue + or be canceled. When set to `CONTINUE`, the statement execution continues asynchronously and the + call returns a statement ID which can be used for polling with + :method:statementexecution/getStatement. When set to `CANCEL`, the statement execution is canceled + and the call returns with a `CANCELED` state. +:param parameters: List[:class:`StatementParameterListItem`] (optional) + A list of parameters to pass into a SQL statement containing parameter markers. A parameter consists + 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) + Applies the given row limit to the statement's result set, but unlike the `LIMIT` clause in SQL, it + also sets the `truncated` field in the response to indicate whether the result was trimmed due to + 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` - + +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 + +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` diff --git a/docs/workspace/sql/warehouses.rst b/docs/workspace/sql/warehouses.rst index fd55d5b0c..e5afd9419 100644 --- a/docs/workspace/sql/warehouses.rst +++ b/docs/workspace/sql/warehouses.rst @@ -5,7 +5,7 @@ .. py:class:: WarehousesAPI A SQL warehouse is a compute resource that lets you run SQL commands on data objects within Databricks - SQL. Compute resources are infrastructure resources that provide processing capabilities in the cloud. +SQL. Compute resources are infrastructure resources that provide processing capabilities in the cloud. .. py:method:: create( [, 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[CreateWarehouseRequestWarehouseType]]) -> Wait[GetWarehouseResponse] @@ -34,69 +34,69 @@ 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 - :param cluster_size: str (optional) - 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 - :param instance_profile_arn: str (optional) - 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. - + +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 +:param cluster_size: str (optional) + 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 +:param instance_profile_arn: str (optional) + 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. + .. py:method:: create_and_wait( [, 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[CreateWarehouseRequestWarehouseType], timeout: datetime.timedelta = 0:20:00]) -> GetWarehouseResponse @@ -104,14 +104,14 @@ .. py:method:: delete(id: str) Delete a warehouse. - - Deletes a SQL warehouse. - - :param id: str - Required. Id of the SQL 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] @@ -146,70 +146,70 @@ 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 - :param cluster_size: str (optional) - 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. - :param instance_profile_arn: str (optional) - 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. - + +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 +:param cluster_size: str (optional) + 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. +:param instance_profile_arn: str (optional) + 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. + .. py:method:: edit_and_wait(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], timeout: datetime.timedelta = 0:20:00]) -> GetWarehouseResponse @@ -243,48 +243,48 @@ 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` - + +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` - + +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` - + +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` - + +Gets the workspace level configuration that is shared by all SQL warehouses in a workspace. + +:returns: :class:`GetWorkspaceWarehouseConfigResponse` + .. py:method:: list( [, run_as_user_id: Optional[int]]) -> Iterator[EndpointInfo] @@ -301,75 +301,75 @@ 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` - + +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` - + +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) - Deprecated: Use sql_configuration_parameters - :param data_access_config: List[:class:`EndpointConfPair`] (optional) - Spark confs for external hive metastore configuration JSON serialized size must be less than <= 512K - :param enabled_warehouse_types: List[:class:`WarehouseTypePair`] (optional) - List of Warehouse Types allowed in this workspace (limits allowed value of the type field in - CreateWarehouse and EditWarehouse). Note: Some types cannot be disabled, they don't need to be - specified in SetWorkspaceWarehouseConfig. Note: Disabling a type may cause existing warehouses to be - converted to another type. Used by frontend to save specific type availability in the warehouse - create and edit form UI. - :param global_param: :class:`RepeatedEndpointConfPairs` (optional) - Deprecated: Use sql_configuration_parameters - :param google_service_account: str (optional) - GCP only: Google Service Account used to pass to cluster to access Google Cloud Storage - :param instance_profile_arn: str (optional) - AWS Only: Instance profile used to pass IAM role to the cluster - :param security_policy: :class:`SetWorkspaceWarehouseConfigRequestSecurityPolicy` (optional) - Security policy for warehouses - :param sql_configuration_parameters: :class:`RepeatedEndpointConfPairs` (optional) - SQL configuration parameters - - - + +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) + Deprecated: Use sql_configuration_parameters +:param data_access_config: List[:class:`EndpointConfPair`] (optional) + Spark confs for external hive metastore configuration JSON serialized size must be less than <= 512K +:param enabled_warehouse_types: List[:class:`WarehouseTypePair`] (optional) + List of Warehouse Types allowed in this workspace (limits allowed value of the type field in + CreateWarehouse and EditWarehouse). Note: Some types cannot be disabled, they don't need to be + specified in SetWorkspaceWarehouseConfig. Note: Disabling a type may cause existing warehouses to be + converted to another type. Used by frontend to save specific type availability in the warehouse + create and edit form UI. +:param global_param: :class:`RepeatedEndpointConfPairs` (optional) + Deprecated: Use sql_configuration_parameters +:param google_service_account: str (optional) + GCP only: Google Service Account used to pass to cluster to access Google Cloud Storage +:param instance_profile_arn: str (optional) + AWS Only: Instance profile used to pass IAM role to the cluster +:param security_policy: :class:`SetWorkspaceWarehouseConfigRequestSecurityPolicy` (optional) + 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. - + +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. + .. py:method:: start_and_wait(id: str, timeout: datetime.timedelta = 0:20:00) -> GetWarehouseResponse @@ -377,16 +377,16 @@ .. 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. - + +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. + .. py:method:: stop_and_wait(id: str, timeout: datetime.timedelta = 0:20:00) -> GetWarehouseResponse @@ -394,16 +394,16 @@ .. 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` - + +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` + .. py:method:: wait_get_warehouse_running(id: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[GetWarehouseResponse], None]]) -> GetWarehouseResponse diff --git a/docs/workspace/vectorsearch/vector_search_endpoints.rst b/docs/workspace/vectorsearch/vector_search_endpoints.rst index 1abd09b95..c53697944 100644 --- a/docs/workspace/vectorsearch/vector_search_endpoints.rst +++ b/docs/workspace/vectorsearch/vector_search_endpoints.rst @@ -9,18 +9,18 @@ .. 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. - + +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. + .. py:method:: create_endpoint_and_wait(name: str, endpoint_type: EndpointType, timeout: datetime.timedelta = 0:20:00) -> EndpointInfo @@ -28,31 +28,31 @@ .. py:method:: delete_endpoint(endpoint_name: str) Delete an endpoint. - - :param endpoint_name: str - Name of the 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` - + +: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` - + +:param page_token: str (optional) + Token for pagination + +:returns: Iterator over :class:`EndpointInfo` + .. py:method:: wait_get_endpoint_vector_search_endpoint_online(endpoint_name: str, timeout: datetime.timedelta = 0:20:00, callback: Optional[Callable[[EndpointInfo], None]]) -> EndpointInfo diff --git a/docs/workspace/vectorsearch/vector_search_indexes.rst b/docs/workspace/vectorsearch/vector_search_indexes.rst index 415e19d90..1222ab348 100644 --- a/docs/workspace/vectorsearch/vector_search_indexes.rst +++ b/docs/workspace/vectorsearch/vector_search_indexes.rst @@ -5,179 +5,178 @@ .. py:class:: VectorSearchIndexesAPI **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 - vectors and metadata through our REST and SDK APIs. With this model, the user manages index updates. +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 +vectors and metadata through our REST and SDK APIs. With this model, the user manages index updates. .. 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 - Name of the endpoint to be used for serving the index - :param primary_key: str - 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 - REST and SDK APIs. With this model, the user manages index updates. - :param delta_sync_index_spec: :class:`DeltaSyncVectorIndexSpecRequest` (optional) - 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` - + +Create a new index. + +:param name: str + Name of the index +:param endpoint_name: str + Name of the endpoint to be used for serving the index +:param primary_key: str + 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 + REST and SDK APIs. With this model, the user manages index updates. +:param delta_sync_index_spec: :class:`DeltaSyncVectorIndexSpecRequest` (optional) + 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` - + +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 - - - + +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` - + +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` - + +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 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 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. - :param num_results: int (optional) - Number of results to return. Defaults to 10. - :param query_text: str (optional) - Query text. Required for Delta Sync Index using model endpoint. - :param query_type: str (optional) - The query type to use. Choices are `ANN` and `HYBRID`. Defaults to `ANN`. - :param query_vector: List[float] (optional) - Query vector. Required for Direct Vector Access Index and Delta Sync Index using self-managed - vectors. - :param score_threshold: float (optional) - Threshold for the approximate nearest neighbor search. Defaults to 0.0. - - :returns: :class:`QueryVectorIndexResponse` - + +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 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. +:param num_results: int (optional) + Number of results to return. Defaults to 10. +:param query_text: str (optional) + Query text. Required for Delta Sync Index using model endpoint. +:param query_type: str (optional) + The query type to use. Choices are `ANN` and `HYBRID`. Defaults to `ANN`. +:param query_vector: List[float] (optional) + Query vector. Required for Direct Vector Access Index and Delta Sync Index using self-managed + 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` - + +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` - + +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. - - - + +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 + +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` diff --git a/docs/workspace/workspace/git_credentials.rst b/docs/workspace/workspace/git_credentials.rst index 34851e84a..ea93845b6 100644 --- a/docs/workspace/workspace/git_credentials.rst +++ b/docs/workspace/workspace/git_credentials.rst @@ -5,10 +5,10 @@ .. 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 + +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,41 +27,41 @@ 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`, - `gitLabEnterpriseEdition` and `awsCodeCommit`. - :param git_username: str (optional) - The username or email provided with your Git provider account, depending on which provider you are - using. For GitHub, GitHub Enterprise Server, or Azure DevOps Services, either email or username may - be used. For GitLab, GitLab Enterprise Edition, email must be used. For AWS CodeCommit, BitBucket or - BitBucket Server, username must be used. For all other providers please see your provider's Personal - Access Token authentication documentation to see what is supported. - :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` - + +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`, + `gitLabEnterpriseEdition` and `awsCodeCommit`. +:param git_username: str (optional) + The username or email provided with your Git provider account, depending on which provider you are + using. For GitHub, GitHub Enterprise Server, or Azure DevOps Services, either email or username may + be used. For GitLab, GitLab Enterprise Edition, email must be used. For AWS CodeCommit, BitBucket or + BitBucket Server, username must be used. For all other providers please see your provider's Personal + Access Token authentication documentation to see what is supported. +: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. - - - + +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,14 +82,14 @@ 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` - + +Gets the Git credential with the specified credential ID. + +:param credential_id: int + The ID for the corresponding credential to access. + +:returns: :class:`GetCredentialsResponse` + .. py:method:: list() -> Iterator[CredentialInfo] @@ -105,11 +105,11 @@ 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` - + +Lists the calling user's Git credentials. One credential per user is supported. + +:returns: Iterator over :class:`CredentialInfo` + .. py:method:: update(credential_id: int, git_provider: str [, git_username: Optional[str], personal_access_token: Optional[str]]) @@ -135,26 +135,25 @@ 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 - Git provider. This field is case-insensitive. The available Git providers are `gitHub`, - `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer`, - `gitLabEnterpriseEdition` and `awsCodeCommit`. - :param git_username: str (optional) - The username or email provided with your Git provider account, depending on which provider you are - using. For GitHub, GitHub Enterprise Server, or Azure DevOps Services, either email or username may - be used. For GitLab, GitLab Enterprise Edition, email must be used. For AWS CodeCommit, BitBucket or - BitBucket Server, username must be used. For all other providers please see your provider's Personal - Access Token authentication documentation to see what is supported. - :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 + +Updates the specified Git credential. + +:param credential_id: int + The ID for the corresponding credential to access. +:param git_provider: str + Git provider. This field is case-insensitive. The available Git providers are `gitHub`, + `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer`, + `gitLabEnterpriseEdition` and `awsCodeCommit`. +:param git_username: str (optional) + The username or email provided with your Git provider account, depending on which provider you are + using. For GitHub, GitHub Enterprise Server, or Azure DevOps Services, either email or username may + be used. For GitLab, GitLab Enterprise Edition, email must be used. For AWS CodeCommit, BitBucket or + BitBucket Server, username must be used. For all other providers please see your provider's Personal + Access Token authentication documentation to see what is supported. +: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 + + diff --git a/docs/workspace/workspace/repos.rst b/docs/workspace/workspace/repos.rst index 5f3e3e290..ce8908906 100644 --- a/docs/workspace/workspace/repos.rst +++ b/docs/workspace/workspace/repos.rst @@ -5,14 +5,14 @@ .. py:class:: ReposAPI 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. +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. .. py:method:: create(url: str, provider: str [, path: Optional[str], sparse_checkout: Optional[SparseCheckout]]) -> CreateRepoResponse @@ -35,37 +35,37 @@ 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 - Git provider. This field is case-insensitive. The available Git providers are `gitHub`, - `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer`, - `gitLabEnterpriseEdition` and `awsCodeCommit`. - :param path: str (optional) - Desired path for the repo in the workspace. Almost any path in the workspace can be chosen. If repo - is created in `/Repos`, path must be in the format `/Repos/{folder}/{repo-name}`. - :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` - + +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 + Git provider. This field is case-insensitive. The available Git providers are `gitHub`, + `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer`, + `gitLabEnterpriseEdition` and `awsCodeCommit`. +:param path: str (optional) + Desired path for the repo in the workspace. Almost any path in the workspace can be chosen. If repo + is created in `/Repos`, path must be in the format `/Repos/{folder}/{repo-name}`. +: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. - - - + +Deletes the specified repo. + +:param repo_id: int + The ID for the corresponding repo to delete. + + + .. py:method:: get(repo_id: int) -> GetRepoResponse @@ -90,38 +90,38 @@ 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` - + +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` - + +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` - + +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` + .. py:method:: list( [, next_page_token: Optional[str], path_prefix: Optional[str]]) -> Iterator[RepoInfo] @@ -138,34 +138,34 @@ 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. - :param path_prefix: str (optional) - 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` - + +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. +:param path_prefix: str (optional) + 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` - + +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` + .. py:method:: update(repo_id: int [, branch: Optional[str], sparse_checkout: Optional[SparseCheckoutUpdate], tag: Optional[str]]) @@ -190,34 +190,33 @@ 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) - Branch that the local version of the repo is checked out to. - :param sparse_checkout: :class:`SparseCheckoutUpdate` (optional) - If specified, update the sparse checkout settings. The update will fail if sparse checkout is not - enabled for the repo. - :param tag: str (optional) - 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. - - - + +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) + Branch that the local version of the repo is checked out to. +:param sparse_checkout: :class:`SparseCheckoutUpdate` (optional) + If specified, update the sparse checkout settings. The update will fail if sparse checkout is not + enabled for the repo. +:param tag: str (optional) + 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 + +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` diff --git a/docs/workspace/workspace/secrets.rst b/docs/workspace/workspace/secrets.rst index 96d94e1de..cb37e6155 100644 --- a/docs/workspace/workspace/secrets.rst +++ b/docs/workspace/workspace/secrets.rst @@ -5,14 +5,14 @@ .. 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. + +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. .. py:method:: create_scope(scope: str [, backend_azure_keyvault: Optional[AzureKeyVaultSecretScopeMetadata], initial_manage_principal: Optional[str], scope_backend_type: Optional[ScopeBackendType]]) @@ -38,112 +38,112 @@ 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) - The metadata for the secret scope if the type is `AZURE_KEYVAULT` - :param initial_manage_principal: str (optional) - 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` - - - + +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) + The metadata for the secret scope if the type is `AZURE_KEYVAULT` +:param initial_manage_principal: str (optional) + 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. - - - + +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. - - - + +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. - - - + +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` - + +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` - + +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` + .. py:method:: list_acls(scope: str) -> Iterator[AclItem] @@ -171,17 +171,17 @@ 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` - + +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` + .. py:method:: list_scopes() -> Iterator[SecretScope] @@ -197,13 +197,13 @@ 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` - + +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` + .. py:method:: list_secrets(scope: str) -> Iterator[SecretMetadata] @@ -231,19 +231,19 @@ 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` - + +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` + .. py:method:: put_acl(scope: str, principal: str, permission: AclPermission) @@ -275,41 +275,41 @@ 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. - - - + +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]]) @@ -337,31 +337,30 @@ 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 - A unique name to identify the secret. - :param bytes_value: str (optional) - 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 + +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 + A unique name to identify the secret. +:param bytes_value: str (optional) + 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. + + diff --git a/docs/workspace/workspace/workspace.rst b/docs/workspace/workspace/workspace.rst index 595872deb..5c7516cb8 100644 --- a/docs/workspace/workspace/workspace.rst +++ b/docs/workspace/workspace/workspace.rst @@ -5,30 +5,30 @@ .. 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. + +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. - - - + +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 @@ -55,15 +55,15 @@ w.workspace.delete(py_file) - Downloads notebook or file from the workspace - - :param path: location of the file or notebook on workspace. - :param format: By default, `ExportFormat.SOURCE`. If using `ExportFormat.AUTO` the `path` - is imported or exported as either a workspace file or a notebook, depending - on an analysis of the `item`’s extension and the header content provided in - the request. - :return: file-like `io.BinaryIO` of the `path` contents. - +Downloads notebook or file from the workspace + +:param path: location of the file or notebook on workspace. +:param format: By default, `ExportFormat.SOURCE`. If using `ExportFormat.AUTO` the `path` + is imported or exported as either a workspace file or a notebook, depending + on an analysis of the `item`’s extension and the header content provided in + the request. +:return: file-like `io.BinaryIO` of the `path` contents. + .. py:method:: export(path: str [, format: Optional[ExportFormat]]) -> ExportResponse @@ -84,60 +84,60 @@ 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` - + +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` - + +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` - + +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` + .. py:method:: get_status(path: str) -> ObjectInfo @@ -157,15 +157,15 @@ 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` - + +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` + .. py:method:: import_(path: str [, content: Optional[str], format: Optional[ImportFormat], language: Optional[Language], overwrite: Optional[bool]]) @@ -191,40 +191,40 @@ 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`: - 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. - :param language: :class:`Language` (optional) - The language of the object. This value is set only if the object type is `NOTEBOOK`. - :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. - - - + +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`: + 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. +:param language: :class:`Language` (optional) + The language of the object. This value is set only if the object type is `NOTEBOOK`. +: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 @@ -244,62 +244,62 @@ List workspace objects - :param recursive: bool - Optionally invoke recursive traversal +:param recursive: bool + Optionally invoke recursive traversal + +:returns: Iterator of workspaceObjectInfo - :returns: Iterator of workspaceObjectInfo - .. 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. - - - + +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` - + +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` - + +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` + .. py:method:: upload(path: str, content: bytes [, format: ImportFormat, language: Language, overwrite: bool = False]) @@ -325,19 +325,18 @@ w.workspace.delete(notebook) - Uploads a workspace object (for example, a notebook or file) or the contents of an entire - directory (`DBC` format). - - Errors: - * `RESOURCE_ALREADY_EXISTS`: if `path` already exists no `overwrite=True`. - * `INVALID_PARAMETER_VALUE`: if `format` and `content` values are not compatible. - - :param path: target location of the file on workspace. - :param content: the contents as either raw binary data `bytes` or a file-like the file-like `io.BinaryIO` of the `path` contents. - :param format: By default, `ImportFormat.SOURCE`. If using `ImportFormat.AUTO` the `path` - is imported or exported as either a workspace file or a notebook, depending - on an analysis of the `item`’s extension and the header content provided in - the request. In addition, if the `path` is imported as a notebook, then - the `item`’s extension is automatically removed. - :param language: Only required if using `ExportFormat.SOURCE`. - \ No newline at end of file +Uploads a workspace object (for example, a notebook or file) or the contents of an entire +directory (`DBC` format). + +Errors: + * `RESOURCE_ALREADY_EXISTS`: if `path` already exists no `overwrite=True`. + * `INVALID_PARAMETER_VALUE`: if `format` and `content` values are not compatible. + +:param path: target location of the file on workspace. +:param content: the contents as either raw binary data `bytes` or a file-like the file-like `io.BinaryIO` of the `path` contents. +:param format: By default, `ImportFormat.SOURCE`. If using `ImportFormat.AUTO` the `path` + is imported or exported as either a workspace file or a notebook, depending + on an analysis of the `item`’s extension and the header content provided in + the request. In addition, if the `path` is imported as a notebook, then + the `item`’s extension is automatically removed. +:param language: Only required if using `ExportFormat.SOURCE`.