diff --git a/databricks/sdk/service/agentbricks.py b/databricks/sdk/service/agentbricks.py index 02d27cfc5..feab675c6 100755 --- a/databricks/sdk/service/agentbricks.py +++ b/databricks/sdk/service/agentbricks.py @@ -342,17 +342,17 @@ def update_custom_llm(self, id: str, custom_llm: CustomLlm, update_mask: str) -> The CustomLlm containing the fields which should be updated. :param update_mask: str The list of the CustomLlm fields to update. These should correspond to the values (or lack thereof) - present in `custom_llm`. + present in ``custom_llm``. The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`CustomLlm` """ diff --git a/databricks/sdk/service/aisearch.py b/databricks/sdk/service/aisearch.py index bbb329756..02e364790 100755 --- a/databricks/sdk/service/aisearch.py +++ b/databricks/sdk/service/aisearch.py @@ -28,7 +28,7 @@ @dataclass class ColumnInfo: - """Column information (name and data type) for an index column. Surfaced on `Index.column_info`.""" + """Column information (name and data type) for an index column. Surfaced on ``Index.column_info``.""" name: Optional[str] = None """Name of the column.""" @@ -133,7 +133,7 @@ def from_dict(cls, d: Dict[str, Any]) -> DataModificationResult: class DataModificationStatus(Enum): """Overall outcome of a data-plane upsert or delete. Mirrors the legacy - `databricks.brickindexscheduler.UpsertDeleteDataStatus` value-for-value.""" + ``databricks.brickindexscheduler.UpsertDeleteDataStatus`` value-for-value.""" FAILURE = "FAILURE" PARTIAL_SUCCESS = "PARTIAL_SUCCESS" @@ -146,10 +146,10 @@ class DeltaSyncIndexSpec: pipeline_type: PipelineType """Pipeline execution mode. Required on create — the backend rejects an unset value. Storage - Optimized endpoints accept only `TRIGGERED`; Standard endpoints accept both. No explicit `stage` - — a REQUIRED field staged below its service would be dropped from combined specs while - remaining in `required`, tripping the OpenAPI required-vs-properties consistency check. The - field inherits the service's launch stage.""" + Optimized endpoints accept only ``TRIGGERED``; Standard endpoints accept both. No explicit + ``stage`` — a REQUIRED field staged below its service would be dropped from combined specs + while remaining in ``required``, tripping the OpenAPI required-vs-properties consistency check. + The field inherits the service's launch stage.""" columns_to_sync: Optional[List[str]] = None """[Optional] Select the columns to sync with the index. If left blank, all columns from the source @@ -234,9 +234,9 @@ class DirectAccessIndexSpec: """The columns that contain the embedding vectors.""" schema_json: Optional[str] = None - """The schema of the index in JSON format. Supported types are `integer`, `long`, `float`, - `double`, `boolean`, `string`, `date`, `timestamp`. Supported types for vector columns: - `array`, `array`.""" + """The schema of the index in JSON format. Supported types are ``integer``, ``long``, ``float``, + ``double``, ``boolean``, ``string``, ``date``, ``timestamp``. Supported types for vector + columns: ``array``, ``array``.""" def as_dict(self) -> dict: """Serializes the DirectAccessIndexSpec into a dictionary suitable for use as a JSON request body.""" @@ -387,19 +387,19 @@ class Endpoint: name: Optional[str] = None """Name of the AI Search endpoint. Server-assigned full resource path - (`workspaces/{workspace}/endpoints/{endpoint}`) on output. On create, the user-supplied short - name is conveyed via `CreateEndpointRequest.endpoint_id`; the server composes the full `name` - and returns it on the response.""" + (``workspaces/{workspace}/endpoints/{endpoint}``) on output. On create, the user-supplied short + name is conveyed via ``CreateEndpointRequest.endpoint_id``; the server composes the full + ``name`` and returns it on the response.""" replica_count: Optional[int] = None """The client-supplied desired number of replicas for the endpoint, applied at create/update time. - Mutually exclusive with `target_qps`.""" + Mutually exclusive with ``target_qps``.""" scaling_info: Optional[EndpointScalingInfo] = None """Scaling information for the endpoint""" target_qps: Optional[int] = None - """Target QPS for the endpoint. Mutually exclusive with `replica_count`. Best-effort; the system + """Target QPS for the endpoint. Mutually exclusive with ``replica_count``. Best-effort; the system does not guarantee this QPS will be achieved.""" throughput_info: Optional[EndpointThroughputInfo] = None @@ -560,7 +560,7 @@ class EndpointStatus: """Human-readable detail about the endpoint's current state or the reason for a state transition.""" state: Optional[EndpointStatusState] = None - """Current lifecycle state of the endpoint. See `State` for the meaning of each value.""" + """Current lifecycle state of the endpoint. See ``State`` for the meaning of each value.""" def as_dict(self) -> dict: """Serializes the EndpointStatus into a dictionary suitable for use as a JSON request body.""" @@ -703,7 +703,7 @@ class FacetResultData: """Facet aggregation rows returned by a query.""" facet_array: Optional[List[List[any]]] = None - """Facet rows; each row is `[facet_column_name, value_or_range, count]`.""" + """Facet rows; each row is ``[facet_column_name, value_or_range, count]``.""" facet_row_count: Optional[int] = None """Number of facet rows returned.""" @@ -736,7 +736,7 @@ def from_dict(cls, d: Dict[str, Any]) -> FacetResultData: class Index: """An AI Search index — a searchable collection of vectors and metadata hosted on an AI Search endpoint. Indexes are children of endpoints; customers create, get, list, and delete them. The - `{index}` segment of the resource name is the index's Unity Catalog table name.""" + ``{index}`` segment of the resource name is the index's Unity Catalog table name.""" primary_key: str """Primary key of the index. Set on create and immutable thereafter.""" @@ -748,23 +748,23 @@ class Index: """Creator of the index.""" delta_sync_index_spec: Optional[DeltaSyncIndexSpec] = None - """Specification for a Delta Sync index. Set when `index_type` is `DELTA_SYNC`.""" + """Specification for a Delta Sync index. Set when ``index_type`` is ``DELTA_SYNC``.""" direct_access_index_spec: Optional[DirectAccessIndexSpec] = None - """Specification for a Direct Access index. Set when `index_type` is `DIRECT_ACCESS`.""" + """Specification for a Direct Access index. Set when ``index_type`` is ``DIRECT_ACCESS``.""" endpoint: Optional[str] = None """Name of the endpoint associated with the index. Ignored on create — the endpoint is taken from - `CreateIndexRequest.parent`; populated only on output.""" + ``CreateIndexRequest.parent``; populated only on output.""" index_subtype: Optional[IndexSubtype] = None """The subtype of the index. Set on create and immutable thereafter.""" name: Optional[str] = None """Name of the AI Search index. Server-assigned full resource path - (`workspaces/{workspace}/endpoints/{endpoint}/indexes/{index}`) on output, where `{index}` is - the index's Unity Catalog table name. On create, the user-supplied UC table name is conveyed via - `CreateIndexRequest.index_id`; the server composes the full `name` and returns it on the + (``workspaces/{workspace}/endpoints/{endpoint}/indexes/{index}``) on output, where ``{index}`` + is the index's Unity Catalog table name. On create, the user-supplied UC table name is conveyed + via ``CreateIndexRequest.index_id``; the server composes the full ``name`` and returns it on the response.""" status: Optional[IndexStatus] = None @@ -887,12 +887,13 @@ def from_dict(cls, d: Dict[str, Any]) -> IndexStatus: class IndexSubtype(Enum): - """The subtype of the AI Search index, determining the indexing and retrieval strategy. - `VECTOR`: - Not a supported create value — do not select it. Use `HYBRID` (vector + hybrid search) or - `FULL_TEXT` (full-text only). It is the proto2 default (`= 0`) solely to mirror the legacy - `index_v2.proto` enum value-for-value; it is not an offered index subtype. - `FULL_TEXT`: An - index that uses full-text search without vector embeddings. - `HYBRID`: An index that uses - vector embeddings for similarity search and hybrid search.""" + """The subtype of the AI Search index, determining the indexing and retrieval strategy. + + - ``VECTOR``: Not a supported create value — do not select it. Use ``HYBRID`` (vector + hybrid + search) or ``FULL_TEXT`` (full-text only). It is the proto2 default (``= 0``) solely to mirror + the legacy ``index_v2.proto`` enum value-for-value; it is not an offered index subtype. + - ``FULL_TEXT``: An index that uses full-text search without vector embeddings. + - ``HYBRID``: An index that uses vector embeddings for similarity search and hybrid search.""" FULL_TEXT = "FULL_TEXT" HYBRID = "HYBRID" @@ -900,11 +901,12 @@ class IndexSubtype(Enum): class IndexType(Enum): - """There are 2 types of AI 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.""" + """There are 2 types of AI 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.""" DELTA_SYNC = "DELTA_SYNC" DIRECT_ACCESS = "DIRECT_ACCESS" @@ -949,10 +951,10 @@ class ListIndexesResponse: """Response for ListIndexes carrying the page of indexes and an optional continuation token.""" indexes: Optional[List[Index]] = None - """The indexes on the endpoint. The field is named `indexes` (not the irregular plural `indices`) - to satisfy core::0132, which derives the response field name from the ListIndexes method. - core::0158::response-plural-first-field independently computes the resource plural as `indices` - and is satisfied via a scoped field exception below.""" + """The indexes on the endpoint. The field is named ``indexes`` (not the irregular plural + ``indices``) to satisfy core::0132, which derives the response field name from the ListIndexes + method. core::0158::response-plural-first-field independently computes the resource plural as + ``indices`` and is satisfied via a scoped field exception below.""" next_page_token: Optional[str] = None """A token that can be used to get the next page of results. Empty when there are no more results.""" @@ -983,10 +985,12 @@ def from_dict(cls, d: Dict[str, Any]) -> ListIndexesResponse: class PipelineType(Enum): """Pipeline execution mode for a Delta Sync index. Required on create for Delta Sync indexes; the - legacy backend rejects an unset value with INVALID_PARAMETER_VALUE. - `TRIGGERED`: the pipeline - stops after refreshing the source table once, using the data available when the update started. - - `CONTINUOUS`: the pipeline processes new data as it arrives in the source table to keep the - index fresh.""" + legacy backend rejects an unset value with INVALID_PARAMETER_VALUE. + + - ``TRIGGERED``: the pipeline stops after refreshing the source table once, using the data + available when the update started. + - ``CONTINUOUS``: the pipeline processes new data as it arrives in the source table to keep the + index fresh.""" CONTINUOUS = "CONTINUOUS" TRIGGERED = "TRIGGERED" @@ -1079,10 +1083,10 @@ class RerankerConfig: model: Optional[str] = None """Reranker identifier: "databricks_reranker" for the base model, or a Model Serving endpoint name - when `model_type` is MODEL_TYPE_FINETUNED.""" + when ``model_type`` is MODEL_TYPE_FINETUNED.""" model_type: Optional[RerankerConfigModelType] = None - """Discriminator for how `model` is interpreted.""" + """Discriminator for how ``model`` is interpreted.""" parameters: Optional[RerankerConfigRerankerParameters] = None """Parameters controlling reranking.""" @@ -1120,7 +1124,7 @@ def from_dict(cls, d: Dict[str, Any]) -> RerankerConfig: class RerankerConfigModelType(Enum): - """How the `model` field is interpreted.""" + """How the ``model`` field is interpreted.""" MODEL_TYPE_BASE = "MODEL_TYPE_BASE" MODEL_TYPE_FINETUNED = "MODEL_TYPE_FINETUNED" @@ -1305,7 +1309,7 @@ def from_dict(cls, d: Dict[str, Any]) -> SyncIndexResponse: class ThroughputChangeRequestState(Enum): """State of the most recent throughput change request issued against a Storage Optimized endpoint. - Surfaced on `EndpointThroughputInfo.change_request_state`.""" + Surfaced on ``EndpointThroughputInfo.change_request_state``.""" CHANGE_ADJUSTED = "CHANGE_ADJUSTED" CHANGE_FAILED = "CHANGE_FAILED" @@ -1362,15 +1366,15 @@ def create_endpoint(self, parent: str, endpoint: Endpoint, *, endpoint_id: Optio """Create a new AI Search endpoint. :param parent: str - The Workspace where this Endpoint will be created. Format: `workspaces/{workspace_id}` + The Workspace where this Endpoint will be created. Format: ``workspaces/{workspace_id}`` :param endpoint: :class:`Endpoint` - The Endpoint resource to create. Fields other than `endpoint.name` carry the desired configuration; - `endpoint.name` is server-assigned from `parent` and `endpoint_id`. + The Endpoint resource to create. Fields other than ``endpoint.name`` carry the desired + configuration; ``endpoint.name`` is server-assigned from ``parent`` and ``endpoint_id``. :param endpoint_id: str (optional) The user-supplied short name for the Endpoint, per AIP-133. The server composes the full - `Endpoint.name` as `{parent}/endpoints/{endpoint_id}`. AIP-133 does not list `endpoint_id` as a - fields-may-be-required entry, so we annotate it OPTIONAL on the wire; the server still rejects empty - values with INVALID_PARAMETER_VALUE. + ``Endpoint.name`` as ``{parent}/endpoints/{endpoint_id}``. AIP-133 does not list ``endpoint_id`` as + a fields-may-be-required entry, so we annotate it OPTIONAL on the wire; the server still rejects + empty values with INVALID_PARAMETER_VALUE. :returns: :class:`Endpoint` """ @@ -1396,13 +1400,13 @@ def create_index(self, parent: str, index: Index, *, index_id: Optional[str] = N :param parent: str The Endpoint where this Index will be created. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}`` :param index: :class:`Index` - The Index resource to create. Fields other than `index.name` carry the desired configuration; - `index.name` is server-assigned from `parent` and `index_id`. + The Index resource to create. Fields other than ``index.name`` carry the desired configuration; + ``index.name`` is server-assigned from ``parent`` and ``index_id``. :param index_id: str (optional) The user-supplied Unity Catalog table name for the Index, per AIP-133. The server composes the full - `Index.name` as `{parent}/indexes/{index_id}`. AIP-133 does not list `index_id` as a + ``Index.name`` as ``{parent}/indexes/{index_id}``. AIP-133 does not list ``index_id`` as a fields-may-be-required entry, so we annotate it OPTIONAL on the wire; the server still rejects empty values with INVALID_PARAMETER_VALUE. @@ -1430,7 +1434,7 @@ def delete_endpoint(self, name: str): :param name: str Full resource name of the endpoint to delete. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}`` """ @@ -1450,7 +1454,7 @@ def delete_index(self, name: str): :param name: str Full resource name of the index to delete. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` """ @@ -1469,7 +1473,7 @@ def get_endpoint(self, name: str) -> Endpoint: """Get details for a single AI Search endpoint. :param name: str - Full resource name of the endpoint. Format: `workspaces/{workspace_id}/endpoints/{endpoint_id}` + Full resource name of the endpoint. Format: ``workspaces/{workspace_id}/endpoints/{endpoint_id}`` :returns: :class:`Endpoint` """ @@ -1490,7 +1494,7 @@ def get_index(self, name: str) -> Index: :param name: str Full resource name of the index. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :returns: :class:`Index` """ @@ -1512,11 +1516,11 @@ def list_endpoints( """List AI Search endpoints in a workspace. :param parent: str - The Workspace that owns this collection of endpoints. Format: `workspaces/{workspace_id}` + The Workspace that owns this collection of endpoints. Format: ``workspaces/{workspace_id}`` :param page_size: int (optional) Best-effort upper bound on the number of results to return. Honored as an upper bound by the shim: - `page_size` only narrows the legacy backend's response, never widens it, so the practical cap is - `min(page_size, legacy_fixed_page_size)`. + ``page_size`` only narrows the legacy backend's response, never widens it, so the practical cap is + ``min(page_size, legacy_fixed_page_size)``. :param page_token: str (optional) Page token from a previous response. If not provided, returns the first page. @@ -1552,11 +1556,11 @@ def list_indexes( :param parent: str The Endpoint that owns this collection of indexes. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}`` :param page_size: int (optional) Best-effort upper bound on the number of results to return. Honored as an upper bound by the shim: - `page_size` only narrows the legacy backend's response, never widens it, so the practical cap is - `min(page_size, legacy_fixed_page_size)`. + ``page_size`` only narrows the legacy backend's response, never widens it, so the practical cap is + ``min(page_size, legacy_fixed_page_size)``. :param page_token: str (optional) Page token from a previous response. If not provided, returns the first page. @@ -1606,23 +1610,23 @@ def query_index( :param name: str Full resource name of the index to query. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :param columns: List[str] Column names to include in each result row. :param columns_to_rerank: List[str] (optional) Columns whose values are sent to the reranker. :param facets: List[str] (optional) - Facets to compute over the matched results (e.g. `"category TOP 5"`). + Facets to compute over the matched results (e.g. ``"category TOP 5"``). :param filters_json: str (optional) - JSON string describing query filters (e.g. `{"id >": 5}`). + JSON string describing query filters (e.g. ``{"id >": 5}``). :param max_results: int (optional) - Maximum number of results to return (the legacy `num_results`). Defaults to 10. + Maximum number of results to return (the legacy ``num_results``). Defaults to 10. :param query_columns: List[str] (optional) - Text columns to search for `query_text`. When empty, all text columns are searched. + Text columns to search for ``query_text``. When empty, all text columns are searched. :param query_text: str (optional) Query text. Required for Delta Sync indexes that compute embeddings from a model endpoint. :param query_type: str (optional) - Query type: `ANN`, `HYBRID`, or `FULL_TEXT`. Defaults to `ANN`. + Query type: ``ANN``, ``HYBRID``, or ``FULL_TEXT``. Defaults to ``ANN``. :param query_vector: List[float] (optional) Query vector. Required for Direct Access indexes and Delta Sync indexes with self-managed vectors. :param reranker: :class:`RerankerConfig` (optional) @@ -1630,7 +1634,7 @@ def query_index( :param score_threshold: float (optional) Score threshold for the approximate nearest-neighbor search. Defaults to 0.0. :param sort_columns: List[str] (optional) - Sort clauses, e.g. `["rating DESC", "price ASC"]`. Overrides relevance ordering. + Sort clauses, e.g. ``["rating DESC", "price ASC"]``. Overrides relevance ordering. :returns: :class:`QueryIndexResponse` """ @@ -1677,7 +1681,7 @@ def remove_data(self, name: str, primary_keys: List[str]) -> RemoveDataResponse: :param name: str Full resource name of the index. Must be a Direct Access index. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :param primary_keys: List[str] Primary keys of the rows to remove. @@ -1706,7 +1710,7 @@ def scan_index( :param name: str Full resource name of the index to scan. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :param page_size: int (optional) Maximum number of rows to return in this page. :param page_token: str (optional) @@ -1738,7 +1742,7 @@ def sync_index(self, name: str) -> SyncIndexResponse: :param name: str Full resource name of the index to synchronize. Must be a Delta Sync index. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :returns: :class:`SyncIndexResponse` """ @@ -1763,11 +1767,11 @@ def update_endpoint(self, name: str, endpoint: Endpoint, update_mask: FieldMask) :param name: str Name of the AI Search endpoint. Server-assigned full resource path - (`workspaces/{workspace}/endpoints/{endpoint}`) on output. On create, the user-supplied short name - is conveyed via `CreateEndpointRequest.endpoint_id`; the server composes the full `name` and returns - it on the response. + (``workspaces/{workspace}/endpoints/{endpoint}``) on output. On create, the user-supplied short name + is conveyed via ``CreateEndpointRequest.endpoint_id``; the server composes the full ``name`` and + returns it on the response. :param endpoint: :class:`Endpoint` - The Endpoint resource to update. `endpoint.name` carries the full resource path. + The Endpoint resource to update. ``endpoint.name`` carries the full resource path. :param update_mask: FieldMask The list of fields to update. @@ -1795,7 +1799,7 @@ def upsert_data(self, name: str, inputs_json: str) -> UpsertDataResponse: :param name: str Full resource name of the index. Must be a Direct Access index. Format: - `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}` + ``workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`` :param inputs_json: str JSON document describing the rows to upsert. diff --git a/databricks/sdk/service/apps.py b/databricks/sdk/service/apps.py index 44108700d..1dcdd35a4 100755 --- a/databricks/sdk/service/apps.py +++ b/databricks/sdk/service/apps.py @@ -49,10 +49,10 @@ class App: budget_policy_id: Optional[str] = None compute_max_instances: Optional[int] = None - """Maximum number of app instances. Must be set together with `compute_min_instances`.""" + """Maximum number of app instances. Must be set together with ``compute_min_instances``.""" compute_min_instances: Optional[int] = None - """Minimum number of app instances. Must be set together with `compute_max_instances`.""" + """Minimum number of app instances. Must be set together with ``compute_max_instances``.""" compute_size: Optional[ComputeSize] = None @@ -441,7 +441,7 @@ class AppDeployment: source_code_path: Optional[str] = None """The workspace file system path of the source code used to create the app deployment. This is - different from `deployment_artifacts.source_code_path`, which is the path used by the deployed + different from ``deployment_artifacts.source_code_path``, which is the path used by the deployed app. The former refers to the original source code location of the app in the workspace during deployment creation, whereas the latter provides a system generated stable snapshotted source code path used by the deployment.""" @@ -1641,10 +1641,10 @@ class AppUpdate: budget_policy_id: Optional[str] = None compute_max_instances: Optional[int] = None - """Maximum number of app instances. Must be set together with `compute_min_instances`.""" + """Maximum number of app instances. Must be set together with ``compute_min_instances``.""" compute_min_instances: Optional[int] = None - """Minimum number of app instances. Must be set together with `compute_max_instances`.""" + """Minimum number of app instances. Must be set together with ``compute_max_instances``.""" compute_size: Optional[ComputeSize] = None @@ -2391,8 +2391,8 @@ class Operation: """This resource represents a long-running operation that is the result of a network API call.""" done: Optional[bool] = None - """If the value is `false`, it means the operation is still in progress. If `true`, the operation - is completed, and either `error` or `response` is available.""" + """If the value is ``false``, it means the operation is still in progress. If ``true``, the + operation is completed, and either ``error`` or ``response`` is available.""" error: Optional[DatabricksServiceExceptionWithDetailsProto] = None """The error result of the operation in case of failure or cancellation.""" @@ -2404,8 +2404,8 @@ class Operation: name: Optional[str] = None """The server-assigned name, which is only unique within the same service that originally returns - it. If you use the default HTTP mapping, the `name` should be a resource name ending with - `operations/{unique_id}`.""" + it. If you use the default HTTP mapping, the ``name`` should be a resource name ending with + ``operations/{unique_id}``.""" response: Optional[dict] = None """The normal, successful response of the operation.""" @@ -3007,14 +3007,14 @@ def create_update(self, app_name: str, update_mask: str, *, app: Optional[App] = :param app_name: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :param app: :class:`App` (optional) :returns: @@ -3560,14 +3560,14 @@ def update_space(self, name: str, space: Space, update_mask: FieldMask) -> Updat :param space: :class:`Space` :param update_mask: FieldMask The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`Operation` """ diff --git a/databricks/sdk/service/billing.py b/databricks/sdk/service/billing.py index aeaebd2cd..66ebef0a1 100755 --- a/databricks/sdk/service/billing.py +++ b/databricks/sdk/service/billing.py @@ -84,10 +84,10 @@ class AlertConfiguration: quantity_threshold: Optional[str] = None """The threshold for the budget alert to determine if it is in a triggered state. The number is - evaluated based on `quantity_type`.""" + evaluated based on ``quantity_type``.""" quantity_type: Optional[AlertConfigurationQuantityType] = None - """The way to calculate cost for this budget alert. This is what `quantity_threshold` is measured + """The way to calculate cost for this budget alert. This is what ``quantity_threshold`` is measured in.""" time_period: Optional[AlertConfigurationTimePeriod] = None @@ -379,9 +379,11 @@ class BudgetPolicy: """The Id of the policy. This field is generated by Databricks and globally unique.""" policy_name: Optional[str] = None - """The name of the policy. - Must be unique among active policies. - Can contain only characters - from the ISO 8859-1 (latin1) set. - Can't start with reserved keywords such as - `databricks:default-policy`.""" + """The name of the policy. + + - Must be unique among active policies. + - Can contain only characters from the ISO 8859-1 (latin1) set. + - Can't start with reserved keywords such as ``databricks:default-policy``.""" def as_dict(self) -> dict: """Serializes the BudgetPolicy into a dictionary suitable for use as a JSON request body.""" @@ -541,10 +543,10 @@ class CreateBudgetConfigurationBudgetAlertConfigurations: quantity_threshold: Optional[str] = None """The threshold for the budget alert to determine if it is in a triggered state. The number is - evaluated based on `quantity_type`.""" + evaluated based on ``quantity_type``.""" quantity_type: Optional[AlertConfigurationQuantityType] = None - """The way to calculate cost for this budget alert. This is what `quantity_threshold` is measured + """The way to calculate cost for this budget alert. This is what ``quantity_threshold`` is measured in.""" time_period: Optional[AlertConfigurationTimePeriod] = None @@ -624,40 +626,40 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateBudgetConfigurationResponse: @dataclass class CreateLogDeliveryConfigurationParams: - """* Log Delivery Configuration""" + """Log Delivery Configuration""" log_type: LogType - """Log delivery type. Supported values are: * `BILLABLE_USAGE` — Configure [billable usage log - delivery]. For the CSV schema, see the [View billable usage]. * `AUDIT_LOGS` — Configure - [audit log delivery]. For the JSON schema, see [Configure audit logging] + """Log delivery type. Supported values are: - [Configure audit logging]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html - [View billable usage]: https://docs.databricks.com/administration-guide/account-settings/usage.html - [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""" + - ``BILLABLE_USAGE`` — Configure `billable usage log delivery + `__. + For the CSV schema, see the `View billable usage + `__. + - ``AUDIT_LOGS`` — Configure `audit log delivery + `__. For + the JSON schema, see `Configure audit logging + `__""" output_format: OutputFormat - """The file type of log delivery. * If `log_type` is `BILLABLE_USAGE`, this value must be `CSV`. - Only the CSV (comma-separated values) format is supported. For the schema, see the [View - billable usage] * If `log_type` is `AUDIT_LOGS`, this value must be `JSON`. Only the JSON - (JavaScript Object Notation) format is supported. For the schema, see the [Configuring audit - logs]. + """The file type of log delivery. - [Configuring audit logs]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html - [View billable usage]: https://docs.databricks.com/administration-guide/account-settings/usage.html""" + - If ``log_type`` is ``BILLABLE_USAGE``, this value must be ``CSV``. Only the CSV + (comma-separated values) format is supported. For the schema, see the `View billable usage + `__ + - If ``log_type`` is ``AUDIT_LOGS``, this value must be ``JSON``. Only the JSON (JavaScript + Object Notation) format is supported. For the schema, see the `Configuring audit logs + `__.""" credentials_id: str """The ID for a method:credentials/create that represents the AWS IAM role with policy and trust - relationship as described in the main billable usage documentation page. See [Configure billable - usage delivery]. - - [Configure billable usage delivery]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html""" + relationship as described in the main billable usage documentation page. See `Configure billable + usage delivery + `__.""" storage_configuration_id: str """The ID for a method:storage/create that represents the S3 bucket with bucket policy as described - in the main billable usage documentation page. See [Configure billable usage delivery]. - - [Configure billable usage delivery]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html""" + in the main billable usage documentation page. See `Configure billable usage delivery + `__.""" config_name: Optional[str] = None """The optional human-readable name of the log delivery configuration. Defaults to empty.""" @@ -673,16 +675,16 @@ class CreateLogDeliveryConfigurationParams: logs are not available for usage before March 2019 (2019-03).""" status: Optional[LogDeliveryConfigStatus] = None - """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.""" + """Status of log delivery configuration. Set to ``ENABLED`` (enabled) or ``DISABLED`` (disabled). + Defaults to ``ENABLED``. You can enable or disable the configuration later. Deletion of a + configuration is not supported, so disable a log delivery configuration that is no longer + needed.""" workspace_ids_filter: Optional[List[int]] = None """Optional filter that specifies workspace IDs to deliver logs for. By default the workspace filter is empty and log delivery applies at the account level, delivering workspace-level logs for all workspaces in your account, plus account level logs. You can optionally set this field - to an array of workspace IDs (each one is an `int64`) to which log delivery should apply, in + to an array of workspace IDs (each one is an ``int64``) to which log delivery should apply, in which case only workspace-level logs relating to the specified workspaces are delivered. If you plan to use different log delivery configurations for different workspaces, set this field explicitly. Be aware that delivery configurations mentioning specific workspaces won't apply to @@ -771,12 +773,12 @@ def from_dict(cls, d: Dict[str, Any]) -> DeleteBudgetConfigurationResponse: class DeliveryStatus(Enum): - """* The status string for log delivery. Possible values are: `CREATED`: There were no log delivery - attempts since the config was created. `SUCCEEDED`: The latest attempt of log delivery has - succeeded completely. `USER_FAILURE`: The latest attempt of log delivery failed because of - misconfiguration of customer provided permissions on role or storage. `SYSTEM_FAILURE`: The + """The status string for log delivery. Possible values are: ``CREATED``: There were no log delivery + attempts since the config was created. ``SUCCEEDED``: The latest attempt of log delivery has + succeeded completely. ``USER_FAILURE``: The latest attempt of log delivery failed because of + misconfiguration of customer provided permissions on role or storage. ``SYSTEM_FAILURE``: The latest attempt of log delivery failed because of an Databricks internal error. Contact support - if it doesn't go away soon. `NOT_FOUND`: The log delivery status as the configuration has been + if it doesn't go away soon. ``NOT_FOUND``: The log delivery status as the configuration has been disabled since the release of this feature or there are no workspaces in the account.""" CREATED = "CREATED" @@ -963,7 +965,7 @@ class ListBudgetConfigurationsResponse: budgets: Optional[List[BudgetConfiguration]] = None next_page_token: Optional[str] = None - """Token which can be sent as `page_token` to retrieve the next page of results. If this field is + """Token which can be sent as ``page_token`` to retrieve the next page of results. If this field is omitted, there are no subsequent budgets.""" def as_dict(self) -> dict: @@ -997,13 +999,13 @@ class ListBudgetPoliciesResponse: """A list of policies.""" next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" policies: Optional[List[BudgetPolicy]] = None previous_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the previous page. In this field is + """A token that can be sent as ``page_token`` to retrieve the previous page. In this field is omitted, there are no previous pages.""" def as_dict(self) -> dict: @@ -1039,10 +1041,10 @@ def from_dict(cls, d: Dict[str, Any]) -> ListBudgetPoliciesResponse: class LogDeliveryConfigStatus(Enum): - """* Log Delivery Status + """Log Delivery Status - `ENABLED`: All dependencies have executed and succeeded `DISABLED`: At least one dependency has - succeeded""" + ``ENABLED``: All dependencies have executed and succeeded ``DISABLED``: At least one dependency + has succeeded""" DISABLED = "DISABLED" ENABLED = "ENABLED" @@ -1050,40 +1052,40 @@ class LogDeliveryConfigStatus(Enum): @dataclass class LogDeliveryConfiguration: - """* Log Delivery Configuration""" + """Log Delivery Configuration""" log_type: LogType - """Log delivery type. Supported values are: * `BILLABLE_USAGE` — Configure [billable usage log - delivery]. For the CSV schema, see the [View billable usage]. * `AUDIT_LOGS` — Configure - [audit log delivery]. For the JSON schema, see [Configure audit logging] + """Log delivery type. Supported values are: - [Configure audit logging]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html - [View billable usage]: https://docs.databricks.com/administration-guide/account-settings/usage.html - [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""" + - ``BILLABLE_USAGE`` — Configure `billable usage log delivery + `__. + For the CSV schema, see the `View billable usage + `__. + - ``AUDIT_LOGS`` — Configure `audit log delivery + `__. For + the JSON schema, see `Configure audit logging + `__""" output_format: OutputFormat - """The file type of log delivery. * If `log_type` is `BILLABLE_USAGE`, this value must be `CSV`. - Only the CSV (comma-separated values) format is supported. For the schema, see the [View - billable usage] * If `log_type` is `AUDIT_LOGS`, this value must be `JSON`. Only the JSON - (JavaScript Object Notation) format is supported. For the schema, see the [Configuring audit - logs]. + """The file type of log delivery. - [Configuring audit logs]: https://docs.databricks.com/administration-guide/account-settings/audit-logs.html - [View billable usage]: https://docs.databricks.com/administration-guide/account-settings/usage.html""" + - If ``log_type`` is ``BILLABLE_USAGE``, this value must be ``CSV``. Only the CSV + (comma-separated values) format is supported. For the schema, see the `View billable usage + `__ + - If ``log_type`` is ``AUDIT_LOGS``, this value must be ``JSON``. Only the JSON (JavaScript + Object Notation) format is supported. For the schema, see the `Configuring audit logs + `__.""" credentials_id: str """The ID for a method:credentials/create that represents the AWS IAM role with policy and trust - relationship as described in the main billable usage documentation page. See [Configure billable - usage delivery]. - - [Configure billable usage delivery]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html""" + relationship as described in the main billable usage documentation page. See `Configure billable + usage delivery + `__.""" storage_configuration_id: str """The ID for a method:storage/create that represents the S3 bucket with bucket policy as described - in the main billable usage documentation page. See [Configure billable usage delivery]. - - [Configure billable usage delivery]: https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html""" + in the main billable usage documentation page. See `Configure billable usage delivery + `__.""" account_id: Optional[str] = None """Databricks account ID.""" @@ -1111,10 +1113,10 @@ class LogDeliveryConfiguration: """The LogDeliveryStatus of this log delivery configuration""" status: Optional[LogDeliveryConfigStatus] = None - """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.""" + """Status of log delivery configuration. Set to ``ENABLED`` (enabled) or ``DISABLED`` (disabled). + Defaults to ``ENABLED``. You can enable or disable the configuration later. Deletion of a + configuration is not supported, so disable a log delivery configuration that is no longer + needed.""" update_time: Optional[int] = None """Time in epoch milliseconds when the log delivery configuration was updated.""" @@ -1123,7 +1125,7 @@ class LogDeliveryConfiguration: """Optional filter that specifies workspace IDs to deliver logs for. By default the workspace filter is empty and log delivery applies at the account level, delivering workspace-level logs for all workspaces in your account, plus account level logs. You can optionally set this field - to an array of workspace IDs (each one is an `int64`) to which log delivery should apply, in + to an array of workspace IDs (each one is an ``int64``) to which log delivery should apply, in which case only workspace-level logs relating to the specified workspaces are delivered. If you plan to use different log delivery configurations for different workspaces, set this field explicitly. Be aware that delivery configurations mentioning specific workspaces won't apply to @@ -1221,13 +1223,16 @@ def from_dict(cls, d: Dict[str, Any]) -> LogDeliveryConfiguration: @dataclass class LogDeliveryStatus: status: DeliveryStatus - """Enum that describes the status. Possible values are: * `CREATED`: There were no log delivery - attempts since the config was created. * `SUCCEEDED`: The latest attempt of log delivery has - succeeded completely. * `USER_FAILURE`: The latest attempt of log delivery failed because of - misconfiguration of customer provided permissions on role or storage. * `SYSTEM_FAILURE`: The - latest attempt of log delivery failed because of an Databricks internal error. Contact support - if it doesn't go away soon. * `NOT_FOUND`: The log delivery status as the configuration has been - disabled since the release of this feature or there are no workspaces in the account.""" + """Enum that describes the status. Possible values are: + + - ``CREATED``: There were no log delivery attempts since the config was created. + - ``SUCCEEDED``: The latest attempt of log delivery has succeeded completely. + - ``USER_FAILURE``: The latest attempt of log delivery failed because of misconfiguration of + customer provided permissions on role or storage. + - ``SYSTEM_FAILURE``: The latest attempt of log delivery failed because of an Databricks + internal error. Contact support if it doesn't go away soon. + - ``NOT_FOUND``: The log delivery status as the configuration has been disabled since the + release of this feature or there are no workspaces in the account.""" message: str """Informative message about the latest log delivery attempt. If the log delivery fails with @@ -1277,14 +1282,14 @@ def from_dict(cls, d: Dict[str, Any]) -> LogDeliveryStatus: class LogType(Enum): - """* Log Delivery Type""" + """Log Delivery Type""" AUDIT_LOGS = "AUDIT_LOGS" BILLABLE_USAGE = "BILLABLE_USAGE" class OutputFormat(Enum): - """* Log Delivery Output Format""" + """Log Delivery Output Format""" CSV = "CSV" JSON = "JSON" @@ -1472,7 +1477,7 @@ class WrappedLogDeliveryConfigurations: """Log delivery configurations were returned successfully.""" next_page_token: Optional[str] = None - """Token which can be sent as `page_token` to retrieve the next page of results. If this field is + """Token which can be sent as ``page_token`` to retrieve the next page of results. If this field is omitted, there are no subsequent budgets.""" def as_dict(self) -> dict: @@ -1513,7 +1518,10 @@ def download(self, start_month: str, end_month: str, *, personal_data: Optional[ """Returns billable usage logs in CSV format for the specified account and date range. For the data schema, see: - - AWS: [CSV file schema]. - GCP: [CSV file schema]. + - AWS: `CSV file schema + `__. + - GCP: `CSV file schema + `__. Note that this method might take multiple minutes to complete. @@ -1521,14 +1529,12 @@ def download(self, start_month: str, end_month: str, *, personal_data: Optional[ 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.gcp.databricks.com/administration-guide/account-settings/usage-analysis.html#csv-file-schema - :param start_month: str - Format specification for month in the format `YYYY-MM`. This is used to specify billable usage - `start_month` and `end_month` properties. **Note**: Billable usage logs are unavailable before March - 2019 (`2019-03`). + Format specification for month in the format ``YYYY-MM``. This is used to specify billable usage + ``start_month`` and ``end_month`` properties. **Note**: Billable usage logs are unavailable before + March 2019 (``2019-03``). :param end_month: str - Format: `YYYY-MM`. Last month to return billable usage logs for. This field is required. + 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 @@ -1564,12 +1570,12 @@ def create(self, *, policy: Optional[BudgetPolicy] = None, request_id: Optional[ """Creates a new policy. :param policy: :class:`BudgetPolicy` (optional) - The policy to create. `policy_id` needs to be empty as it will be generated `policy_name` must be - provided, custom_tags may need to be provided depending on the cloud provider. All other fields are - optional. + The policy to create. ``policy_id`` needs to be empty as it will be generated ``policy_name`` must + be provided, custom_tags may need to be provided depending on the cloud provider. All other fields + are optional. :param request_id: str (optional) A unique identifier for this request. Restricted to 36 ASCII characters. A random UUID is - recommended. This request is only idempotent if a `request_id` is provided. + recommended. This request is only idempotent if a ``request_id`` is provided. :returns: :class:`BudgetPolicy` """ @@ -1640,10 +1646,10 @@ def list( The maximum number of budget policies to return. If unspecified, at most 100 budget policies will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. :param page_token: str (optional) - A page token, received from a previous `ListServerlessPolicies` call. Provide this to retrieve the + A page token, received from a previous ``ListServerlessPolicies`` call. Provide this to retrieve the subsequent page. If unspecified, the first page will be returned. - When paginating, all other parameters provided to `ListServerlessPoliciesRequest` must match the + When paginating, all other parameters provided to ``ListServerlessPoliciesRequest`` must match the call that provided the page token. :param sort_spec: :class:`SortSpec` (optional) The sort specification. @@ -1683,8 +1689,8 @@ def update( :param policy_id: str The Id of the policy. This field is generated by Databricks and globally unique. :param policy: :class:`BudgetPolicy` - The policy to update. `creator_user_id` cannot be specified in the request. All other fields must be - specified even if not changed. The `policy_id` is used to identify the policy to update. + The policy to update. ``creator_user_id`` cannot be specified in the request. All other fields must + be specified even if not changed. The ``policy_id`` is used to identify the policy to update. :param limit_config: :class:`LimitConfig` (optional) DEPRECATED. This is redundant field as LimitConfig is part of the BudgetPolicy @@ -1827,7 +1833,7 @@ def update(self, budget_id: str, budget: UpdateBudgetConfigurationBudget) -> Upd class LogDeliveryAPI: """These APIs manage log delivery configurations for this account. The two supported log types for this API - are _billable usage logs_ (AWS only) and _audit logs_ (AWS and GCP). This feature is in Public Preview. + are *billable usage logs* (AWS only) and *audit logs* (AWS and GCP). 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 @@ -1837,47 +1843,53 @@ class LogDeliveryAPI: The high-level flow of billable usage delivery (AWS only): - 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. - + 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 + 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 (AWS only): * 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 (AWS and GCP): * For more information about about audit log delivery, see Audit log - delivery [AWS] or [GCP], 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 [AWS] or [GCP] for - details. * Auditable events are typically available in logs within 15 minutes. - - [AWS]: 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 - [GCP]: https://docs.databricks.com/gcp/en/admin/account-settings/audit-logs - [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""" + 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 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 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 (AWS only): + + - 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 (AWS and GCP): + + - For more information about about audit log delivery, see Audit log delivery `AWS + `__ or `GCP + `__, 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 `AWS + `__ or `GCP + `__ for details. + - Auditable events are typically available in logs within 15 minutes.""" def __init__(self, api_client): self._api = api_client @@ -1886,12 +1898,15 @@ def create( self, log_delivery_configuration: CreateLogDeliveryConfigurationParams ) -> 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). + to your storage location. This requires that you already created a credential object (which + encapsulates a cross-account service IAM role) and a storage configuration object (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]. + 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 @@ -1900,11 +1915,8 @@ def create( 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 + You cannot delete a log delivery configuration, but you can disable it (see Enable or disable log + delivery configuration). :param log_delivery_configuration: :class:`CreateLogDeliveryConfigurationParams` @@ -1993,15 +2005,14 @@ def patch_status(self, log_delivery_configuration_id: str, status: LogDeliveryCo """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). + under Create log delivery. :param log_delivery_configuration_id: str The log delivery configuration id of customer :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. + Status of log delivery configuration. Set to ``ENABLED`` (enabled) or ``DISABLED`` (disabled). + Defaults to ``ENABLED``. You can enable or disable the configuration later. Deletion of a + configuration is not supported, so disable a log delivery configuration that is no longer needed. """ diff --git a/databricks/sdk/service/catalog.py b/databricks/sdk/service/catalog.py index b7810b3c4..0063ed7e7 100755 --- a/databricks/sdk/service/catalog.py +++ b/databricks/sdk/service/catalog.py @@ -802,14 +802,14 @@ class AzureManagedIdentity: access_connector_id: str """The Azure resource ID of the Azure Databricks Access Connector. Use the format - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}`.""" + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}``.""" credential_id: Optional[str] = None """The Databricks internal ID that represents this managed identity.""" managed_identity_id: Optional[str] = None """The Azure resource ID of the managed identity. Use the format, - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}` + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}`` This is only available for user-assgined identities. For system-assigned identities, the access_connector_id is used to identify the identity. If this field is not provided, then we assume the AzureManagedIdentity is using the system-assigned identity.""" @@ -852,11 +852,11 @@ class AzureManagedIdentityRequest: access_connector_id: str """The Azure resource ID of the Azure Databricks Access Connector. Use the format - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}`.""" + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}``.""" managed_identity_id: Optional[str] = None """The Azure resource ID of the managed identity. Use the format, - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}` + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}`` This is only available for user-assgined identities. For system-assigned identities, the access_connector_id is used to identify the identity. If this field is not provided, then we assume the AzureManagedIdentity is using the system-assigned identity.""" @@ -894,14 +894,14 @@ class AzureManagedIdentityResponse: access_connector_id: str """The Azure resource ID of the Azure Databricks Access Connector. Use the format - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}`.""" + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.Databricks/accessConnectors/{connector-name}``.""" credential_id: Optional[str] = None """The Databricks internal ID that represents this managed identity.""" managed_identity_id: Optional[str] = None """The Azure resource ID of the managed identity. Use the format, - `/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}` + ``/subscriptions/{guid}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}`` This is only available for user-assgined identities. For system-assigned identities, the access_connector_id is used to identify the identity. If this field is not provided, then we assume the AzureManagedIdentity is using the system-assigned identity.""" @@ -1661,7 +1661,7 @@ class ConnectionDependency: """A connection that is dependent on a SQL object.""" connection_name: Optional[str] = None - """Full name of the dependent connection, in the form of __connection_name__.""" + """Full name of the dependent connection, in the form of **connection_name**.""" def as_dict(self) -> dict: """Serializes the ConnectionDependency into a dictionary suitable for use as a JSON request body.""" @@ -1853,7 +1853,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ConnectionInfo: class ConnectionType(Enum): - """Next Id: 127""" + """Next Id: 126""" BIGQUERY = "BIGQUERY" CONFLUENCE = "CONFLUENCE" @@ -1935,7 +1935,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ContinuousUpdateStatus: @dataclass class CreateAccessRequest: behalf_of: Optional[Principal] = None - """Optional. The principal this request is for. Empty `behalf_of` defaults to the requester's + """Optional. The principal this request is for. Empty ``behalf_of`` defaults to the requester's identity. Principals must be unique across the API call.""" @@ -2028,7 +2028,7 @@ class CreateAccountsMetastore: """Whether to allow non-DBR clients to directly access entities under the metastore.""" region: Optional[str] = None - """Cloud region which the metastore serves (e.g., `us-west-2`, `westus`).""" + """Cloud region which the metastore serves (e.g., ``us-west-2``, ``westus``).""" storage_root: Optional[str] = None """The storage root URL for metastore""" @@ -2474,7 +2474,7 @@ class CredentialDependency: """A credential that is dependent on a SQL object.""" credential_name: Optional[str] = None - """Full name of the dependent credential, in the form of __credential_name__.""" + """Full name of the dependent credential, in the form of **credential_name**.""" def as_dict(self) -> dict: """Serializes the CredentialDependency into a dictionary suitable for use as a JSON request body.""" @@ -2990,7 +2990,7 @@ def from_dict(cls, d: Dict[str, Any]) -> DeleteTableConstraintResponse: @dataclass class DeltaRuntimePropertiesKvPairs: """Properties pertaining to the current state of the delta table as given by the commit server. - This does not contain **delta.*** (input) properties in __TableInfo.properties__.""" + This does not contain **delta.*** (input) properties in **TableInfo.properties**.""" delta_runtime_properties: Dict[str, str] """A map of key-value properties attached to the securable.""" @@ -3022,8 +3022,8 @@ class DeltaSharingScopeEnum(Enum): @dataclass class Dependency: - """A dependency of a SQL object. One of the following fields must be defined: __table__, - __function__, __connection__, __credential__, __volume__, or __secret__.""" + """A dependency of a SQL object. One of the following fields must be defined: **table**, + **function**, **connection**, **credential**, **volume**, or **secret**.""" connection: Optional[ConnectionDependency] = None @@ -3127,7 +3127,7 @@ def from_dict(cls, d: Dict[str, Any]) -> DisableResponse: class EffectivePermissionsList: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" privilege_assignments: Optional[List[EffectivePrivilegeAssignment]] = None """The privileges conveyed to each principal (either directly or via inheritance)""" @@ -4052,18 +4052,18 @@ class ExternalLocationInfo: """Name of the storage credential used with this location.""" effective_enable_file_events: Optional[bool] = None - """The effective value of `enable_file_events` after applying server-side defaults.""" + """The effective value of ``enable_file_events`` after applying server-side defaults.""" effective_file_event_queue: Optional[FileEventQueue] = None """The effective file event queue configuration after applying server-side defaults. Always populated when a queue is provisioned, regardless of whether the user explicitly set - `enable_file_events`. Use this field instead of `file_event_queue` for reading the actual queue - state.""" + ``enable_file_events``. Use this field instead of ``file_event_queue`` for reading the actual + queue state.""" enable_file_events: Optional[bool] = None - """Whether to enable file events on this external location. Default to `true`. Set to `false` to - disable file events. The actual applied value may differ due to server-side defaults; check - `effective_enable_file_events` for the effective state.""" + """Whether to enable file events on this external location. Default to ``true``. Set to ``false`` + to disable file events. The actual applied value may differ due to server-side defaults; check + ``effective_enable_file_events`` for the effective state.""" encryption_details: Optional[EncryptionDetails] = None @@ -4073,7 +4073,7 @@ class ExternalLocationInfo: sufficient.""" file_event_queue: Optional[FileEventQueue] = None - """File event queue settings. If `enable_file_events` is not `false`, must be defined and have + """File event queue settings. If ``enable_file_events`` is not ``false``, must be defined and have exactly one of the documented properties.""" isolation_mode: Optional[IsolationMode] = None @@ -4546,7 +4546,7 @@ class FunctionDependency: function_full_name: str """Full name of the dependent function, in the form of - __catalog_name__.__schema_name__.__function_name__.""" + **catalog_name**.**schema_name**.**function_name**.""" def as_dict(self) -> dict: """Serializes the FunctionDependency into a dictionary suitable for use as a JSON request body.""" @@ -5359,7 +5359,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GetCatalogWorkspaceBindingsResponse: @dataclass class GetMetastoreSummaryResponse: cloud: Optional[str] = None - """Cloud vendor of the metastore home shard (e.g., `aws`, `azure`, `gcp`).""" + """Cloud vendor of the metastore home shard (e.g., ``aws``, ``azure``, ``gcp``).""" created_at: Optional[int] = None """Time at which this metastore was created, in epoch milliseconds.""" @@ -5384,7 +5384,8 @@ class GetMetastoreSummaryResponse: """Whether to allow non-DBR clients to directly access entities under the metastore.""" global_metastore_id: Optional[str] = None - """Globally unique metastore ID across clouds and regions, of the form `cloud:region:metastore_id`.""" + """Globally unique metastore ID across clouds and regions, of the form + ``cloud:region:metastore_id``.""" metastore_id: Optional[str] = None """Unique identifier of metastore.""" @@ -5396,10 +5397,10 @@ class GetMetastoreSummaryResponse: """The owner of the metastore.""" privilege_model_version: Optional[str] = None - """Privilege model version of the metastore, of the form `major.minor` (e.g., `1.0`).""" + """Privilege model version of the metastore, of the form ``major.minor`` (e.g., ``1.0``).""" region: Optional[str] = None - """Cloud region which the metastore serves (e.g., `us-west-2`, `westus`).""" + """Cloud region which the metastore serves (e.g., ``us-west-2``, ``westus``).""" storage_root: Optional[str] = None """The storage root URL for metastore""" @@ -5538,7 +5539,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GetMetastoreSummaryResponse: class GetPermissionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" privilege_assignments: Optional[List[PrivilegeAssignment]] = None """The privileges assigned to each principal""" @@ -5602,7 +5603,7 @@ class GetWorkspaceBindingsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the GetWorkspaceBindingsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5700,7 +5701,7 @@ class ListCatalogsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListCatalogsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5733,7 +5734,7 @@ class ListConnectionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListConnectionsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5767,7 +5768,7 @@ class ListCredentialsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListCredentialsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5870,7 +5871,7 @@ class ListExternalLocationsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListExternalLocationsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5939,7 +5940,7 @@ class ListFunctionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListFunctionsResponse into a dictionary suitable for use as a JSON request body.""" @@ -5974,7 +5975,7 @@ class ListMetastoresResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListMetastoresResponse into a dictionary suitable for use as a JSON request body.""" @@ -6008,7 +6009,7 @@ class ListModelVersionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" def as_dict(self) -> dict: """Serializes the ListModelVersionsResponse into a dictionary suitable for use as a JSON request body.""" @@ -6040,7 +6041,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListModelVersionsResponse: @dataclass class ListPoliciesResponse: next_page_token: Optional[str] = None - """Optional opaque token for continuing pagination. `page_token` should be set to this value for + """Optional opaque token for continuing pagination. ``page_token`` should be set to this value for the next request to retrieve the next page of results.""" policies: Optional[List[PolicyInfo]] = None @@ -6074,7 +6075,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListPoliciesResponse: class ListQuotasResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request.""" + **page_token** should be set to this value for the next request.""" quotas: Optional[List[QuotaInfo]] = None """An array of returned QuotaInfos.""" @@ -6142,7 +6143,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListRegisteredModelsResponse: class ListSchemasResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" schemas: Optional[List[SchemaInfo]] = None """An array of schema information objects.""" @@ -6210,7 +6211,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListSecretsResponse: class ListStorageCredentialsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" storage_credentials: Optional[List[StorageCredentialInfo]] = None @@ -6245,7 +6246,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListStorageCredentialsResponse: class ListSystemSchemasResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" schemas: Optional[List[SystemSchemaInfo]] = None """An array of system schema information objects.""" @@ -6280,7 +6281,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListSystemSchemasResponse: class ListTableSummariesResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" tables: Optional[List[TableSummary]] = None """List of table summaries.""" @@ -6313,7 +6314,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListTableSummariesResponse: class ListTablesResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" tables: Optional[List[TableInfo]] = None """An array of table information objects.""" @@ -6346,7 +6347,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListTablesResponse: class ListVolumesResponseContent: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request to retrieve the next page of + **page_token** should be set to this value for the next request to retrieve the next page of results.""" volumes: Optional[List[VolumeInfo]] = None @@ -6460,7 +6461,7 @@ def from_dict(cls, d: Dict[str, Any]) -> MetastoreAssignment: @dataclass class MetastoreInfo: cloud: Optional[str] = None - """Cloud vendor of the metastore home shard (e.g., `aws`, `azure`, `gcp`).""" + """Cloud vendor of the metastore home shard (e.g., ``aws``, ``azure``, ``gcp``).""" created_at: Optional[int] = None """Time at which this metastore was created, in epoch milliseconds.""" @@ -6485,7 +6486,8 @@ class MetastoreInfo: """Whether to allow non-DBR clients to directly access entities under the metastore.""" global_metastore_id: Optional[str] = None - """Globally unique metastore ID across clouds and regions, of the form `cloud:region:metastore_id`.""" + """Globally unique metastore ID across clouds and regions, of the form + ``cloud:region:metastore_id``.""" metastore_id: Optional[str] = None """Unique identifier of metastore.""" @@ -6497,10 +6499,10 @@ class MetastoreInfo: """The owner of the metastore.""" privilege_model_version: Optional[str] = None - """Privilege model version of the metastore, of the form `major.minor` (e.g., `1.0`).""" + """Privilege model version of the metastore, of the form ``major.minor`` (e.g., ``1.0``).""" region: Optional[str] = None - """Cloud region which the metastore serves (e.g., `us-west-2`, `westus`).""" + """Cloud region which the metastore serves (e.g., ``us-west-2``, ``westus``).""" storage_root: Optional[str] = None """The storage root URL for metastore""" @@ -6810,9 +6812,8 @@ class ModelVersionInfoStatus(Enum): @dataclass class MonitorCronSchedule: quartz_cron_expression: str - """The expression that determines when to run the monitor. See [examples]. - - [examples]: https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html""" + """The expression that determines when to run the monitor. See `examples + `__.""" timezone_id: str """The timezone id (e.g., ``PST``) in which to evaluate the quartz expression.""" @@ -7002,18 +7003,18 @@ class MonitorInfo: {catalog}.{schema}""" table_name: str - """[Create:ERR Update:IGN] UC table to monitor. Format: `catalog.schema.table_name`""" + """[Create:ERR Update:IGN] UC table to monitor. Format: ``catalog.schema.table_name``""" status: MonitorInfoStatus """[Create:ERR Update:IGN] The monitor status.""" profile_metrics_table_name: str """[Create:ERR Update:IGN] Table that stores profile metrics data. Format: - `catalog.schema.table_name`.""" + ``catalog.schema.table_name``.""" drift_metrics_table_name: str """[Create:ERR Update:IGN] Table that stores drift metrics data. Format: - `catalog.schema.table_name`.""" + ``catalog.schema.table_name``.""" monitor_version: int """[Create:ERR Update:IGN] Represents the current monitor configuration version in use. The version @@ -7026,7 +7027,7 @@ class MonitorInfo: baseline_table_name: Optional[str] = None """[Create:OPT Update:OPT] Baseline table name. Baseline data is used to compute drift from the - data in the monitored `table_name`. The baseline table and the monitored table shall have the + data in the monitored ``table_name``. The baseline table and the monitored table shall have the same schema.""" custom_metrics: Optional[List[MonitorMetric]] = None @@ -7053,10 +7054,10 @@ class MonitorInfo: slicing_exprs: Optional[List[str]] = None """[Create:OPT Update:OPT] 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 example `slicing_exprs=[“col_1”, “col_2 > 10”]` will - generate the following slices: two slices for `col_2 > 10` (True and False), and one slice per - unique value in `col1`. For high-cardinality columns, only the top 100 unique values by - frequency will generate slices.""" + predicate and its complements. For example ``slicing_exprs=[“col_1”, “col_2 > 10”]`` + will generate the following slices: two slices for ``col_2 > 10`` (True and False), and one + slice per unique value in ``col1``. For high-cardinality columns, only the top 100 unique values + by frequency will generate slices.""" snapshot: Optional[MonitorSnapshot] = None """Configuration for monitoring snapshot tables.""" @@ -7187,10 +7188,9 @@ class MonitorMetric: """Name of the metric in the output tables.""" definition: str - """Jinja template for a SQL expression that specifies how to compute the metric. See [create metric - definition]. - - [create metric definition]: https://docs.databricks.com/en/lakehouse-monitoring/custom-metrics.html#create-definition""" + """Jinja template for a SQL expression that specifies how to compute the metric. See `create metric + definition + `__.""" input_columns: List[str] """A list of column names in the input table the metric should be computed for. Can use @@ -7204,9 +7204,11 @@ class MonitorMetric: ``"CUSTOM_METRIC_TYPE_DRIFT"``. The ``"CUSTOM_METRIC_TYPE_AGGREGATE"`` and ``"CUSTOM_METRIC_TYPE_DERIVED"`` metrics are computed on a single table, whereas the ``"CUSTOM_METRIC_TYPE_DRIFT"`` compare metrics across baseline and input table, or across the - two consecutive time windows. - CUSTOM_METRIC_TYPE_AGGREGATE: only depend on the existing - columns in your table - CUSTOM_METRIC_TYPE_DERIVED: depend on previously computed aggregate - metrics - CUSTOM_METRIC_TYPE_DRIFT: depend on previously computed aggregate or derived metrics""" + two consecutive time windows. + + - CUSTOM_METRIC_TYPE_AGGREGATE: only depend on the existing columns in your table + - CUSTOM_METRIC_TYPE_DERIVED: depend on previously computed aggregate metrics + - CUSTOM_METRIC_TYPE_DRIFT: depend on previously computed aggregate or derived metrics""" def as_dict(self) -> dict: """Serializes the MonitorMetric into a dictionary suitable for use as a JSON request body.""" @@ -7255,9 +7257,11 @@ class MonitorMetricType(Enum): ``\"CUSTOM_METRIC_TYPE_DRIFT\"``. The ``\"CUSTOM_METRIC_TYPE_AGGREGATE\"`` and ``\"CUSTOM_METRIC_TYPE_DERIVED\"`` metrics are computed on a single table, whereas the ``\"CUSTOM_METRIC_TYPE_DRIFT\"`` compare metrics across baseline and input table, or across the - two consecutive time windows. - CUSTOM_METRIC_TYPE_AGGREGATE: only depend on the existing - columns in your table - CUSTOM_METRIC_TYPE_DERIVED: depend on previously computed aggregate - metrics - CUSTOM_METRIC_TYPE_DRIFT: depend on previously computed aggregate or derived metrics""" + two consecutive time windows. + + - CUSTOM_METRIC_TYPE_AGGREGATE: only depend on the existing columns in your table + - CUSTOM_METRIC_TYPE_DERIVED: depend on previously computed aggregate metrics + - CUSTOM_METRIC_TYPE_DRIFT: depend on previously computed aggregate or derived metrics""" CUSTOM_METRIC_TYPE_AGGREGATE = "CUSTOM_METRIC_TYPE_AGGREGATE" CUSTOM_METRIC_TYPE_DERIVED = "CUSTOM_METRIC_TYPE_DERIVED" @@ -8118,14 +8122,14 @@ class PolicyInfo: update.""" for_securable_type: SecurableType - """Type of securables that the policy should take effect on. Only `TABLE` is supported at this + """Type of securables that the policy should take effect on. Only ``TABLE`` is supported at this moment. Required on create and optional on update.""" policy_type: PolicyType """Type of the policy. Required on create.""" column_mask: Optional[ColumnMaskOptions] = None - """Options for column mask policies. Valid only if `policy_type` is `POLICY_TYPE_COLUMN_MASK`. + """Options for column mask policies. Valid only if ``policy_type`` is ``POLICY_TYPE_COLUMN_MASK``. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.""" @@ -8146,22 +8150,22 @@ class PolicyInfo: match_columns: Optional[List[MatchColumn]] = None """Optional list of condition expressions used to match table columns. Only valid when - `for_securable_type` is `TABLE`. When specified, the policy only applies to tables whose columns - satisfy all match conditions.""" + ``for_securable_type`` is ``TABLE``. When specified, the policy only applies to tables whose + columns satisfy all match conditions.""" name: Optional[str] = None - """Name of the policy. Required on create and optional on update. To rename the policy, set `name` - to a different value on update.""" + """Name of the policy. Required on create and optional on update. To rename the policy, set + ``name`` to a different value on update.""" on_securable_fullname: Optional[str] = None """Full name of the securable on which the policy is defined. Required on create.""" on_securable_type: Optional[SecurableType] = None - """Type of the securable on which the policy is defined. Only `CATALOG`, `SCHEMA` and `TABLE` are - supported at this moment. Required on create.""" + """Type of the securable on which the policy is defined. Only ``CATALOG``, ``SCHEMA`` and ``TABLE`` + are supported at this moment. Required on create.""" row_filter: Optional[RowFilterOptions] = None - """Options for row filter policies. Valid only if `policy_type` is `POLICY_TYPE_ROW_FILTER`. + """Options for row filter policies. Valid only if ``policy_type`` is ``POLICY_TYPE_ROW_FILTER``. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.""" @@ -8425,8 +8429,8 @@ class Privilege(Enum): @dataclass class PrivilegeAssignment: principal: Optional[str] = None - """The principal (user email address or group name). For deleted principals, `principal` is empty - while `principal_id` is populated.""" + """The principal (user email address or group name). For deleted principals, ``principal`` is empty + while ``principal_id`` is populated.""" privileges: Optional[List[Privilege]] = None """The privileges assigned to the principal.""" @@ -8931,7 +8935,7 @@ class SchemaInfo: """Whether predictive optimization should be enabled for this object and objects under it.""" full_name: Optional[str] = None - """Full name of schema, in form of __catalog_name__.__schema_name__.""" + """Full name of schema, in form of **catalog_name**.**schema_name**.""" metastore_id: Optional[str] = None """Unique identifier of parent metastore.""" @@ -9290,8 +9294,8 @@ def from_dict(cls, d: Dict[str, Any]) -> Securable: class SecurableKind(Enum): - """Latest kind: CONNECTION_CONFLUENT_SCHEMA_REGISTRY_BASIC = 346; Next id: 347. Reserved numbers: - 316, 317, 327, 330, 341 (former ENDPOINT_LLM_*, MODEL_SERVICE_STANDARD, + """Latest kind: CONNECTION_ADOBE_CAMPAIGNS_OAUTH_M2M = 345; Next id: 346. Reserved numbers: 316, + 317, 327, 330, 341 (former ENDPOINT_LLM_*, MODEL_SERVICE_STANDARD, MODEL_SERVICE_SYSTEM_DELTASHARING, MCP_SERVICE_STANDARD).""" TABLE_DB_STORAGE = "TABLE_DB_STORAGE" @@ -9763,7 +9767,7 @@ class SystemType(Enum): @dataclass class TableConstraint: """A table constraint, as defined by *one* of the following fields being set: - __primary_key_constraint__, __foreign_key_constraint__, __named_table_constraint__.""" + **primary_key_constraint**, **foreign_key_constraint**, **named_table_constraint**.""" foreign_key_constraint: Optional[ForeignKeyConstraint] = None @@ -9809,7 +9813,7 @@ class TableDependency: table_full_name: str """Full name of the dependent table, in the form of - __catalog_name__.__schema_name__.__table_name__.""" + **catalog_name**.**schema_name**.**table_name**.""" def as_dict(self) -> dict: """Serializes the TableDependency into a dictionary suitable for use as a JSON request body.""" @@ -9869,7 +9873,7 @@ class TableInfo: """Name of parent catalog.""" columns: Optional[List[ColumnInfo]] = None - """The array of __ColumnInfo__ definitions of the table's columns.""" + """The array of **ColumnInfo** definitions of the table's columns.""" comment: Optional[str] = None """User-provided free-form text description.""" @@ -9899,7 +9903,7 @@ class TableInfo: encryption_details: Optional[EncryptionDetails] = None full_name: Optional[str] = None - """Full name of table, in form of __catalog_name__.__schema_name__.__table_name__""" + """Full name of table, in form of **catalog_name**.**schema_name**.**table_name**""" metastore_id: Optional[str] = None """Unique identifier of parent metastore.""" @@ -9935,7 +9939,7 @@ class TableInfo: """Storage root URL for table (for **MANAGED**, **EXTERNAL** tables).""" table_constraints: Optional[List[TableConstraint]] = None - """List of table constraints. Note: this field is not set in the output of the __listTables__ API.""" + """List of table constraints. Note: this field is not set in the output of the **listTables** API.""" table_id: Optional[str] = None """The unique identifier of the table.""" @@ -9949,15 +9953,16 @@ class TableInfo: """Username of user who last modified the table.""" view_definition: Optional[str] = None - """View definition SQL (when __table_type__ is **VIEW**, **MATERIALIZED_VIEW**, or + """View definition SQL (when **table_type** is **VIEW**, **MATERIALIZED_VIEW**, or **STREAMING_TABLE**)""" view_dependencies: Optional[DependencyList] = None - """View dependencies (when table_type == **VIEW** or **MATERIALIZED_VIEW**, **STREAMING_TABLE**) - - when DependencyList is None, the dependency is not provided; - when DependencyList is an empty - list, the dependency is provided but is empty; - when DependencyList is not an empty list, - dependencies are provided and recorded. Note: this field is not set in the output of the - __listTables__ API.""" + """View dependencies (when table_type == **VIEW** or **MATERIALIZED_VIEW**, **STREAMING_TABLE**) + + - when DependencyList is None, the dependency is not provided; + - when DependencyList is an empty list, the dependency is provided but is empty; + - when DependencyList is not an empty list, dependencies are provided and recorded. Note: this + field is not set in the output of the **listTables** API.""" def as_dict(self) -> dict: """Serializes the TableInfo into a dictionary suitable for use as a JSON request body.""" @@ -10429,7 +10434,7 @@ class UpdateAccountsMetastore: """The owner of the metastore.""" privilege_model_version: Optional[str] = None - """Privilege model version of the metastore, of the form `major.minor` (e.g., `1.0`).""" + """Privilege model version of the metastore, of the form ``major.minor`` (e.g., ``1.0``).""" storage_root_credential_id: Optional[str] = None """UUID of storage credential to access the metastore storage_root.""" @@ -10988,9 +10993,8 @@ class VolumeInfo: volume_type: Optional[VolumeType] = None """The type of the volume. An external volume is located in the specified external location. A managed volume is located in the default location which is specified by the parent schema, or - the parent catalog, or the Metastore. [Learn more] - - [Learn more]: https://docs.databricks.com/aws/en/volumes/managed-vs-external""" + the parent catalog, or the Metastore. `Learn more + `__""" def as_dict(self) -> dict: """Serializes the VolumeInfo into a dictionary suitable for use as a JSON request body.""" @@ -11139,8 +11143,8 @@ def from_dict(cls, d: Dict[str, Any]) -> WorkspaceBinding: class WorkspaceBindingBindingType(Enum): - """Using `BINDING_TYPE_` prefix here to avoid conflict with `TableOperation` enum in - `credentials_common.proto`.""" + """Using ``BINDING_TYPE_`` prefix here to avoid conflict with ``TableOperation`` enum in + ``credentials_common.proto``.""" BINDING_TYPE_READ_ONLY = "BINDING_TYPE_READ_ONLY" BINDING_TYPE_READ_WRITE = "BINDING_TYPE_READ_WRITE" @@ -11400,11 +11404,13 @@ def create( credential_info: Optional[CreateAccountsStorageCredential] = None, skip_validation: Optional[bool] = None, ) -> AccountsCreateStorageCredentialInfo: - """Creates a new storage credential. The request object is specific to the cloud: - **AwsIamRole** for - AWS credentials - **AzureServicePrincipal** for Azure credentials - **GcpServiceAccountKey** for GCP - credentials + """Creates a new storage credential. The request object is specific to the cloud: + + - **AwsIamRole** for AWS credentials + - **AzureServicePrincipal** for Azure credentials + - **GcpServiceAccountKey** for GCP credentials - The caller must be a metastore admin and have the `CREATE_STORAGE_CREDENTIAL` privilege on the + The caller must be a metastore admin and have the ``CREATE_STORAGE_CREDENTIAL`` privilege on the metastore. :param metastore_id: str @@ -11552,7 +11558,7 @@ def update( class ArtifactAllowlistsAPI: - """In Databricks Runtime 13.3 and above, you can add libraries and init scripts to the `allowlist` in UC so + """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.""" def __init__(self, api_client): @@ -11796,13 +11802,16 @@ def list( Whether to include catalogs not bound to the workspace. Effective only if the user has permission to update the catalog–workspace binding. :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. + 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. @@ -12034,10 +12043,13 @@ def list(self, *, max_results: Optional[int] = None, page_token: Optional[str] = absent, which is the only indication that the end of results has been reached. :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; + 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. @@ -12120,7 +12132,7 @@ class CredentialsAPI: tenant. Each credential is subject to Unity Catalog access-control policies that control which users and groups can access the credential. - To create credentials, you must be a Databricks account admin or have the `CREATE SERVICE CREDENTIAL` + To create credentials, you must be a Databricks account admin or have the ``CREATE SERVICE CREDENTIAL`` privilege. The user who creates the credential can delegate ownership to another user or group to manage permissions on it.""" @@ -12293,7 +12305,7 @@ def list_credentials( page_token: Optional[str] = None, purpose: Optional[CredentialPurpose] = None, ) -> Iterator[CredentialInfo]: - """Gets an array of credentials (as __CredentialInfo__ objects). + """Gets an array of credentials (as **CredentialInfo** objects). The array is limited to only the credentials that the caller has permission to access. If the caller is a metastore admin, retrieval of credentials is unrestricted. There is no guarantee of a specific @@ -12307,10 +12319,13 @@ def list_credentials( Whether to include credentials not bound to the workspace. Effective only if the user has permission to update the credential–workspace binding. :param max_results: int (optional) - Maximum number of credentials to return. - If not set, the default max page size is used. - When set - to a value greater than 0, the page length is the minimum of this value and a server-configured - 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. + Maximum number of credentials to return. + + - If not set, the default max page size is used. + - When set to a value greater than 0, the page length is the minimum of this value and a + server-configured 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 token to retrieve the next page of results. :param purpose: :class:`CredentialPurpose` (optional) @@ -12363,8 +12378,8 @@ def update_credential( ) -> CredentialInfo: """Updates a service or storage credential on the metastore. - The caller must be the owner of the credential or a metastore admin or have the `MANAGE` permission. - If the caller is a metastore admin, only the __owner__ field can be changed. + The caller must be the owner of the credential or a metastore admin or have the ``MANAGE`` permission. + If the caller is a metastore admin, only the **owner** field can be changed. :param name_arg: str Name of the credential. @@ -12445,13 +12460,13 @@ def validate_credential( ) -> ValidateCredentialResponse: """Validates a credential. - For service credentials (purpose is **SERVICE**), either the __credential_name__ or the cloud-specific + For service credentials (purpose is **SERVICE**), either the **credential_name** or the cloud-specific credential must be provided. - For storage credentials (purpose is **STORAGE**), at least one of __external_location_name__ and - __url__ need to be provided. If only one of them is provided, it will be used for validation. And if - both are provided, the __url__ will be used for validation, and __external_location_name__ will be - ignored when checking overlapping urls. Either the __credential_name__ or the cloud-specific + For storage credentials (purpose is **STORAGE**), at least one of **external_location_name** and + **url** need to be provided. If only one of them is provided, it will be used for validation. And if + both are provided, the **url** will be used for validation, and **external_location_name** will be + ignored when checking overlapping urls. Either the **credential_name** or the cloud-specific credential must be provided. The caller must be a metastore admin or the credential owner or have the required permission on the @@ -12518,14 +12533,15 @@ def __init__(self, api_client): def create(self, tag_assignment: EntityTagAssignment) -> EntityTagAssignment: """Creates a tag assignment for an Unity Catalog entity. - To add tags to Unity Catalog entities, you must own the entity or have the following privileges: - - **APPLY TAG** on the entity - **USE SCHEMA** on the entity's parent schema - **USE CATALOG** on the - entity's parent catalog + To add tags to Unity Catalog entities, you must own the entity or have the following privileges: - To add a governed tag to Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** - permission on the tag policy. See [Manage tag policy permissions]. + - **APPLY TAG** on the entity + - **USE SCHEMA** on the entity's parent schema + - **USE CATALOG** on the entity's parent catalog - [Manage tag policy permissions]: https://docs.databricks.com/aws/en/admin/tag-policies/manage-permissions + To add a governed tag to Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** + permission on the tag policy. See `Manage tag policy permissions + `__. :param tag_assignment: :class:`EntityTagAssignment` @@ -12550,13 +12566,14 @@ def delete(self, entity_type: str, entity_name: str, tag_key: str): """Deletes a tag assignment for an Unity Catalog entity by its key. To delete tags from Unity Catalog entities, you must own the entity or have the following privileges: - - **APPLY TAG** on the entity - **USE_SCHEMA** on the entity's parent schema - **USE_CATALOG** on the - entity's parent catalog - To delete a governed tag from Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** - permission on the tag policy. See [Manage tag policy permissions]. + - **APPLY TAG** on the entity + - **USE_SCHEMA** on the entity's parent schema + - **USE_CATALOG** on the entity's parent catalog - [Manage tag policy permissions]: https://docs.databricks.com/aws/en/admin/tag-policies/manage-permissions + To delete a governed tag from Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** + permission on the tag policy. See `Manage tag policy permissions + `__. :param entity_type: str The type of the entity to which the tag is assigned. @@ -12663,14 +12680,15 @@ def update( ) -> EntityTagAssignment: """Updates an existing tag assignment for an Unity Catalog entity. - To update tags to Unity Catalog entities, you must own the entity or have the following privileges: - - **APPLY TAG** on the entity - **USE SCHEMA** on the entity's parent schema - **USE CATALOG** on the - entity's parent catalog + To update tags to Unity Catalog entities, you must own the entity or have the following privileges: - To update a governed tag to Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** - permission on the tag policy. See [Manage tag policy permissions]. + - **APPLY TAG** on the entity + - **USE SCHEMA** on the entity's parent schema + - **USE CATALOG** on the entity's parent catalog - [Manage tag policy permissions]: https://docs.databricks.com/aws/en/admin/tag-policies/manage-permissions + To update a governed tag to Unity Catalog entities, you must also have the **ASSIGN** or **MANAGE** + permission on the tag policy. See `Manage tag policy permissions + `__. :param entity_type: str The type of the entity to which the tag is assigned. @@ -12681,14 +12699,14 @@ def update( :param tag_assignment: :class:`EntityTagAssignment` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EntityTagAssignment` """ @@ -12788,7 +12806,7 @@ def list_external_lineage_relationships( :param object_info: :class:`ExternalLineageObject` The object to query external lineage relationships for. Since this field is a query parameter, please flatten the nested fields. For example, if the object is a table, the query parameter should - look like: `object_info.table.name=main.sales.customers` + look like: ``object_info.table.name=main.sales.customers`` :param lineage_direction: :class:`LineageDirection` The lineage direction to filter on. :param page_size: int (optional) @@ -12835,14 +12853,14 @@ def update_external_lineage_relationship( :param external_lineage_relationship: :class:`UpdateRequestExternalLineage` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`ExternalLineageRelationship` """ @@ -12910,23 +12928,23 @@ def create( :param comment: str (optional) User-provided free-form text description. :param effective_enable_file_events: bool (optional) - The effective value of `enable_file_events` after applying server-side defaults. + The effective value of ``enable_file_events`` after applying server-side defaults. :param effective_file_event_queue: :class:`FileEventQueue` (optional) The effective file event queue configuration after applying server-side defaults. Always populated - when a queue is provisioned, regardless of whether the user explicitly set `enable_file_events`. Use - this field instead of `file_event_queue` for reading the actual queue state. + when a queue is provisioned, regardless of whether the user explicitly set ``enable_file_events``. + Use this field instead of ``file_event_queue`` for reading the actual queue state. :param enable_file_events: bool (optional) - Whether to enable file events on this external location. Default to `true`. Set to `false` to + Whether to enable file events on this external location. Default to ``true``. Set to ``false`` to disable file events. The actual applied value may differ due to server-side defaults; check - `effective_enable_file_events` for the effective state. + ``effective_enable_file_events`` for the effective state. :param encryption_details: :class:`EncryptionDetails` (optional) :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 file_event_queue: :class:`FileEventQueue` (optional) - File event queue settings. If `enable_file_events` is not `false`, must be defined and have exactly - one of the documented properties. + File event queue settings. If ``enable_file_events`` is not ``false``, must be defined and have + exactly one of the documented properties. :param read_only: bool (optional) Indicates whether the external location is read-only. :param skip_validation: bool (optional) @@ -13032,7 +13050,7 @@ def list( max_results: Optional[int] = None, page_token: Optional[str] = None, ) -> Iterator[ExternalLocationInfo]: - """Gets an array of external locations (__ExternalLocationInfo__ objects) from the metastore. The caller + """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. @@ -13051,9 +13069,12 @@ def list( permission to update the location–workspace binding. :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; + (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. @@ -13119,23 +13140,23 @@ def update( :param credential_name: str (optional) Name of the storage credential used with this location. :param effective_enable_file_events: bool (optional) - The effective value of `enable_file_events` after applying server-side defaults. + The effective value of ``enable_file_events`` after applying server-side defaults. :param effective_file_event_queue: :class:`FileEventQueue` (optional) The effective file event queue configuration after applying server-side defaults. Always populated - when a queue is provisioned, regardless of whether the user explicitly set `enable_file_events`. Use - this field instead of `file_event_queue` for reading the actual queue state. + when a queue is provisioned, regardless of whether the user explicitly set ``enable_file_events``. + Use this field instead of ``file_event_queue`` for reading the actual queue state. :param enable_file_events: bool (optional) - Whether to enable file events on this external location. Default to `true`. Set to `false` to + Whether to enable file events on this external location. Default to ``true``. Set to ``false`` to disable file events. The actual applied value may differ due to server-side defaults; check - `effective_enable_file_events` for the effective state. + ``effective_enable_file_events`` for the effective state. :param encryption_details: :class:`EncryptionDetails` (optional) :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 file_event_queue: :class:`FileEventQueue` (optional) - File event queue settings. If `enable_file_events` is not `false`, must be defined and have exactly - one of the documented properties. + File event queue settings. If ``enable_file_events`` is not ``false``, must be defined and have + exactly one of the documented properties. :param force: bool (optional) Force update even if changing url invalidates dependent external tables or mounts. :param isolation_mode: :class:`IsolationMode` (optional) @@ -13323,14 +13344,14 @@ def update_external_metadata( :param external_metadata: :class:`ExternalMetadata` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`ExternalMetadata` """ @@ -13359,7 +13380,7 @@ class FunctionsAPI: 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__.""" + can be referenced with the form **catalog_name**.**schema_name**.**function_name**.""" def __init__(self, api_client): self._api = api_client @@ -13369,12 +13390,13 @@ def create(self, function_info: CreateFunction) -> FunctionInfo: 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 + 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. + Partial **FunctionInfo** specifying the function to be created. :returns: :class:`FunctionInfo` """ @@ -13396,14 +13418,17 @@ def create(self, function_info: CreateFunction) -> FunctionInfo: def delete(self, name: str, *, force: Optional[bool] = None): """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 + 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__) . + **catalog_name**.**schema_name**.**function__name**) . :param force: bool (optional) Force deletion even if the function is notempty. @@ -13423,15 +13448,17 @@ def delete(self, name: str, *, force: Optional[bool] = None): def get(self, name: str, *, include_browse: Optional[bool] = None) -> 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 + 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__). + **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 @@ -13484,9 +13511,11 @@ def list( 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; + 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. @@ -13526,14 +13555,18 @@ def list( def update(self, name: str, *, owner: Optional[str] = None) -> FunctionInfo: """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. + 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__). + **catalog_name**.**schema_name**.**function__name**). :param owner: str (optional) Username of current owner of the function. @@ -13597,11 +13630,14 @@ def get( present in a single page response is guaranteed to contain all the privileges granted on the requested Securable for the respective principal. - If not set, all the permissions are returned. If set to - lesser than 0: invalid parameter error - - 0: page length is set to a server configured value - lesser than 150 but greater than 0: invalid - parameter error (this is to ensure that server is able to return at least one complete - PrivilegeAssignment in a single page response) - greater than (or equal to) 150: page length is the - minimum of this value and a server configured value + If not set, all the permissions are returned. If set to + + - lesser than 0: invalid parameter error + - 0: page length is set to a server configured value + - lesser than 150 but greater than 0: invalid parameter error (this is to ensure that server is able + to return at least one complete PrivilegeAssignment in a single page response) + - greater than (or equal to) 150: page length is the minimum of this value and a server configured + value :param page_token: str (optional) Opaque pagination token to go to next page based on previous query. :param principal: str (optional) @@ -13659,11 +13695,14 @@ def get_effective( effective privileges granted on (or inherited by) the requested Securable for the respective principal. - If not set, all the effective permissions are returned. If set to - lesser than 0: invalid parameter - error - 0: page length is set to a server configured value - lesser than 150 but greater than 0: - invalid parameter error (this is to ensure that server is able to return at least one complete - EffectivePrivilegeAssignment in a single page response) - greater than (or equal to) 150: page - length is the minimum of this value and a server configured value + If not set, all the effective permissions are returned. If set to + + - lesser than 0: invalid parameter error + - 0: page length is set to a server configured value + - lesser than 150 but greater than 0: invalid parameter error (this is to ensure that server is able + to return at least one complete EffectivePrivilegeAssignment in a single page response) + - greater than (or equal to) 150: page length is the minimum of this value and a server configured + value :param page_token: str (optional) Opaque token for the next page of results (pagination). :param principal: str (optional) @@ -13746,8 +13785,8 @@ def __init__(self, api_client): self._api = api_client def assign(self, workspace_id: int, metastore_id: str, default_catalog_name: str): - """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 + """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 @@ -13786,8 +13825,8 @@ def create( storage_root: Optional[str] = None, ) -> 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 + **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 @@ -13795,7 +13834,7 @@ def create( :param external_access_enabled: bool (optional) Whether to allow non-DBR clients to directly access entities under the metastore. :param region: str (optional) - Cloud region which the metastore serves (e.g., `us-west-2`, `westus`). + Cloud region which the metastore serves (e.g., ``us-west-2``, ``westus``). :param storage_root: str (optional) The storage root URL for metastore @@ -13887,7 +13926,7 @@ def get(self, id: str) -> MetastoreInfo: return MetastoreInfo.from_dict(res) def list(self, *, max_results: Optional[int] = None, page_token: Optional[str] = None) -> Iterator[MetastoreInfo]: - """Gets an array of the available metastores (as __MetastoreInfo__ objects). The caller must be an admin + """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. NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls @@ -13898,13 +13937,16 @@ def list(self, *, max_results: Optional[int] = None, page_token: Optional[str] = absent, which is the only indication that the end of results has been reached. :param max_results: int (optional) - Maximum number of metastores to return. - 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; - If not set, all the metastores are returned (not recommended). - Note: The number of - returned metastores might be less than the specified max_results size, even zero. The only - definitive indication that no further metastores can be fetched is when the next_page_token is unset - from the response. + Maximum number of metastores to return. + + - 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; + - If not set, all the metastores are returned (not recommended). + - Note: The number of returned metastores might be less than the specified max_results size, even + zero. The only definitive indication that no further metastores 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. @@ -13993,7 +14035,7 @@ def update( privilege_model_version: Optional[str] = None, storage_root_credential_id: Optional[str] = None, ) -> MetastoreInfo: - """Updates information for a specific metastore. The caller must be a metastore admin. If the __owner__ + """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 @@ -14012,7 +14054,7 @@ def update( :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`). + 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. @@ -14053,9 +14095,9 @@ def update( def update_assignment( self, workspace_id: int, *, default_catalog_name: Optional[str] = None, metastore_id: Optional[str] = None ): - """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 + """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 @@ -14092,7 +14134,7 @@ class ModelVersionsAPI: 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).""" + details, see the registered models API docs.""" def __init__(self, api_client): self._api = api_client @@ -14230,10 +14272,13 @@ def list( 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; + 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. @@ -14503,8 +14548,8 @@ class PoliciesAPI: in Unity Catalog. With ABAC policies, access is controlled in a hierarchical and scalable manner, based on data attributes rather than specific resources, enabling more flexible and comprehensive access control. ABAC policies in Unity Catalog support conditions on securable properties, governance tags, and - environment contexts. Callers must have the `MANAGE` privilege on a securable to view, create, update, or - delete ABAC policies.""" + environment contexts. Callers must have the ``MANAGE`` privilege on a securable to view, create, update, + or delete ABAC policies.""" def __init__(self, api_client): self._api = api_client @@ -14612,9 +14657,11 @@ def list_policies( Optional. Whether to include policies defined on parent securables. By default, the inherited policies are not included. :param max_results: int (optional) - Optional. Maximum number of policies to return on a single page (page length). - When not set or 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; + Optional. Maximum number of policies to return on a single page (page length). + + - When not set or 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; :param page_token: str (optional) Optional. Opaque pagination token to go to next page based on previous query. @@ -14668,12 +14715,14 @@ def update_policy( :param name: str Required. The name of the policy to update. :param policy_info: :class:`PolicyInfo` - Optional fields to update. This is the request body for updating a policy. Use `update_mask` field - to specify which fields in the request is to be updated. - If `update_mask` is empty or "*", all - specified fields will be updated. - If `update_mask` is specified, only the fields specified in the - `update_mask` will be updated. If a field is specified in `update_mask` and not set in the request, - the field will be cleared. Users can use the update mask to explicitly unset optional fields such as - `exception_principals` and `when_condition`. + Optional fields to update. This is the request body for updating a policy. Use ``update_mask`` field + to specify which fields in the request is to be updated. + + - If ``update_mask`` is empty or "*", all specified fields will be updated. + - If ``update_mask`` is specified, only the fields specified in the ``update_mask`` will be updated. + If a field is specified in ``update_mask`` and not set in the request, the field will be cleared. + Users can use the update mask to explicitly unset optional fields such as ``exception_principals`` + and ``when_condition``. :param update_mask: str (optional) Optional. The update mask field for specifying user intentions on which fields to update in the request. @@ -14722,7 +14771,7 @@ def cancel_refresh(self, table_name: str, refresh_id: int): already-initiated refresh job. :param table_name: str - UC table name in format `catalog.schema.table_name`. table_name is case insensitive and spaces are + UC table name in format ``catalog.schema.table_name``. table_name is case insensitive and spaces are disallowed. :param refresh_id: int @@ -14764,16 +14813,22 @@ def create( """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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. + 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 - UC table name in format `catalog.schema.table_name`. This field corresponds to the + UC table name in format ``catalog.schema.table_name``. This field corresponds to the {full_table_name_arg} arg in the endpoint path. :param output_schema_name: str [Create:REQ Update:REQ] Schema where output tables are created. Needs to be in 2-level format @@ -14783,7 +14838,7 @@ def create( data-monitoring assets. Normally prepopulated to a default user location via UI and Python APIs. :param baseline_table_name: str (optional) [Create:OPT Update:OPT] Baseline table name. Baseline data is used to compute drift from the data in - the monitored `table_name`. The baseline table and the monitored table shall have the same schema. + the monitored ``table_name``. The baseline table and the monitored table shall have the same schema. :param custom_metrics: List[:class:`MonitorMetric`] (optional) [Create:OPT Update:OPT] Custom metrics. :param data_classification_config: :class:`MonitorDataClassificationConfig` (optional) @@ -14800,9 +14855,9 @@ def create( :param slicing_exprs: List[str] (optional) [Create:OPT Update:OPT] 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 example `slicing_exprs=[“col_1”, “col_2 > 10”]` will generate the - following slices: two slices for `col_2 > 10` (True and False), and one slice per unique value in - `col1`. For high-cardinality columns, only the top 100 unique values by frequency will generate + and its complements. For example ``slicing_exprs=[“col_1”, “col_2 > 10”]`` will generate the + following slices: two slices for ``col_2 > 10`` (True and False), and one slice per unique value in + ``col1``. 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. @@ -14860,10 +14915,15 @@ def delete(self, table_name: str) -> DeleteMonitorResponse: """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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. + 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. @@ -14871,7 +14931,7 @@ def delete(self, table_name: str) -> DeleteMonitorResponse: be manually cleaned up (if desired). :param table_name: str - UC table name in format `catalog.schema.table_name`. This field corresponds to the + UC table name in format ``catalog.schema.table_name``. This field corresponds to the {full_table_name_arg} arg in the endpoint path. :returns: :class:`DeleteMonitorResponse` @@ -14892,17 +14952,22 @@ def get(self, table_name: str) -> MonitorInfo: """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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 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 - UC table name in format `catalog.schema.table_name`. This field corresponds to the + UC table name in format ``catalog.schema.table_name``. This field corresponds to the {full_table_name_arg} arg in the endpoint path. :returns: :class:`MonitorInfo` @@ -14923,10 +14988,15 @@ def get_refresh(self, table_name: str, refresh_id: int) -> MonitorRefreshInfo: """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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. + 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. @@ -14955,15 +15025,20 @@ def list_refreshes(self, table_name: str) -> MonitorRefreshListResponse: """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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. + 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 - UC table name in format `catalog.schema.table_name`. table_name is case insensitive and spaces are + UC table name in format ``catalog.schema.table_name``. table_name is case insensitive and spaces are disallowed. :returns: :class:`MonitorRefreshListResponse` @@ -14986,16 +15061,21 @@ def regenerate_dashboard( """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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 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 - UC table name in format `catalog.schema.table_name`. This field corresponds to the + UC table name in format ``catalog.schema.table_name``. This field corresponds to the {full_table_name_arg} arg in the endpoint path. :param warehouse_id: str (optional) Optional argument to specify the warehouse for dashboard regeneration. If not specified, the first @@ -15025,15 +15105,20 @@ def run_refresh(self, table_name: str) -> MonitorRefreshInfo: """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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 + 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 - UC table name in format `catalog.schema.table_name`. table_name is case insensitive and spaces are + UC table name in format ``catalog.schema.table_name``. table_name is case insensitive and spaces are disallowed. :returns: :class:`MonitorRefreshInfo` @@ -15071,10 +15156,15 @@ def update( """Deprecated: Use Data Quality Monitors API instead (/api/data-quality/v1/monitors). 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. + 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. @@ -15082,14 +15172,14 @@ def update( Certain configuration fields, such as output asset identifiers, cannot be updated. :param table_name: str - UC table name in format `catalog.schema.table_name`. This field corresponds to the + UC table name in format ``catalog.schema.table_name``. This field corresponds to the {full_table_name_arg} arg in the endpoint path. :param output_schema_name: str [Create:REQ Update:REQ] Schema where output tables are created. Needs to be in 2-level format {catalog}.{schema} :param baseline_table_name: str (optional) [Create:OPT Update:OPT] Baseline table name. Baseline data is used to compute drift from the data in - the monitored `table_name`. The baseline table and the monitored table shall have the same schema. + the monitored ``table_name``. The baseline table and the monitored table shall have the same schema. :param custom_metrics: List[:class:`MonitorMetric`] (optional) [Create:OPT Update:OPT] Custom metrics. :param dashboard_id: str (optional) @@ -15107,9 +15197,9 @@ def update( :param slicing_exprs: List[str] (optional) [Create:OPT Update:OPT] 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 example `slicing_exprs=[“col_1”, “col_2 > 10”]` will generate the - following slices: two slices for `col_2 > 10` (True and False), and one slice per unique value in - `col1`. For high-cardinality columns, only the top 100 unique values by frequency will generate + and its complements. For example ``slicing_exprs=[“col_1”, “col_2 > 10”]`` will generate the + following slices: two slices for ``col_2 > 10`` (True and False), and one slice per unique value in + ``col1``. 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. @@ -15172,13 +15262,14 @@ class RegisteredModelsAPI: 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. + - 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.""" @@ -15209,9 +15300,11 @@ def create( 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. + 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 aliases: List[:class:`RegisteredModelAlias`] (optional) @@ -15401,17 +15494,23 @@ def list( :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; + 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) @@ -15591,9 +15690,8 @@ 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""" + limits. For more information on resource quotas see the `Unity Catalog documentation + `__.""" def __init__(self, api_client): self._api = api_client @@ -15760,14 +15858,14 @@ def update_access_request_destinations( **destination_id** and **destination_type** must be defined. :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AccessRequestDestinations` """ @@ -15930,10 +16028,12 @@ def list( 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; + 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. @@ -15980,8 +16080,8 @@ def update( properties: Optional[Dict[str, str]] = None, ) -> SchemaInfo: """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** + 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 @@ -16150,9 +16250,10 @@ def list_secrets( :param page_size: int (optional) Maximum number of secrets to return. - - If not specified, at most 10000 secrets are returned. - If set to a value greater than 0, the page - length is the minimum of this value and 10000. - If set to 0, the page length is set to 10000. - If - set to a value less than 0, an invalid parameter error is returned. + - If not specified, at most 10000 secrets are returned. + - If set to a value greater than 0, the page length is the minimum of this value and 10000. + - If set to 0, the page length is set to 10000. + - If set to a value less than 0, an invalid parameter error is returned. :param page_token: str (optional) Opaque pagination token to go to the next page based on previous query. The maximum page length is determined by a server configured value. @@ -16374,7 +16475,7 @@ def list( max_results: Optional[int] = None, page_token: Optional[str] = None, ) -> Iterator[StorageCredentialInfo]: - """Gets an array of storage credentials (as __StorageCredentialInfo__ objects). The array is limited to + """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. @@ -16391,10 +16492,12 @@ def list( to update the credential–workspace binding. :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; + 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. @@ -16530,12 +16633,12 @@ def validate( storage_credential_name: Optional[str] = None, url: Optional[str] = None, ) -> ValidateStorageCredentialResponse: - """Validates a storage credential. At least one of __external_location_name__ and __url__ need to be + """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 + 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. + 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. @@ -16674,10 +16777,13 @@ def list( :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). + 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. @@ -16729,12 +16835,13 @@ def __init__(self, api_client): def create(self, full_name_arg: str, constraint: TableConstraint) -> 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. + 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. @@ -16763,12 +16870,13 @@ def create(self, full_name_arg: str, constraint: TableConstraint) -> TableConstr def delete(self, full_name: str, constraint_name: str, cascade: bool): """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. + 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. @@ -16804,7 +16912,7 @@ class TablesAPI: 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 + 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).""" def __init__(self, api_client): @@ -16852,7 +16960,7 @@ def create( :param storage_location: str Storage root URL for table (for **MANAGED**, **EXTERNAL** tables). :param columns: List[:class:`ColumnInfo`] (optional) - The array of __ColumnInfo__ definitions of the table's columns. + The array of **ColumnInfo** definitions of the table's columns. :param properties: Dict[str,str] (optional) A map of key-value properties attached to the securable. @@ -16912,11 +17020,15 @@ def delete(self, full_name: str): def exists(self, full_name: str) -> 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 + 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. @@ -16944,10 +17056,13 @@ def get( include_manifest_capabilities: Optional[bool] = None, ) -> 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. + 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. @@ -17018,10 +17133,12 @@ def list( :param include_manifest_capabilities: bool (optional) Whether to include a manifest containing table capabilities in the response. :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; + 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) @@ -17086,11 +17203,12 @@ def list_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. + - 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. @@ -17104,10 +17222,13 @@ def list_summaries( Whether to include a manifest containing table capabilities in the response. :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; + 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) @@ -17378,15 +17499,19 @@ def create( 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 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. + 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 @@ -17397,9 +17522,8 @@ def create( :param volume_type: :class:`VolumeType` The type of the volume. An external volume is located in the specified external location. A managed volume is located in the default location which is specified by the parent schema, or the parent - catalog, or the Metastore. [Learn more] - - [Learn more]: https://docs.databricks.com/aws/en/volumes/managed-vs-external + catalog, or the Metastore. `Learn more + `__ :param comment: str (optional) The comment attached to the volume :param storage_location: str (optional) @@ -17487,11 +17611,13 @@ def list( :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; + 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 @@ -17605,12 +17731,12 @@ def update( 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 + """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__. + 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. @@ -17618,7 +17744,12 @@ class WorkspaceBindingsAPI: 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 - credential - external_location""" + Securable types that support binding: + + - catalog + - storage_credential + - credential + - external_location""" def __init__(self, api_client): self._api = api_client @@ -17668,10 +17799,13 @@ def get_bindings( :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). + 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. diff --git a/databricks/sdk/service/cleanrooms.py b/databricks/sdk/service/cleanrooms.py index a6d412cf8..6779afa9e 100755 --- a/databricks/sdk/service/cleanrooms.py +++ b/databricks/sdk/service/cleanrooms.py @@ -31,9 +31,8 @@ @dataclass class CleanRoom: access_restricted: Optional[CleanRoomAccessRestricted] = None - """Whether clean room access is restricted due to [CSP] - - [CSP]: https://docs.databricks.com/en/security/privacy/security-profile.html""" + """Whether clean room access is restricted due to `CSP + `__""" comment: Optional[str] = None @@ -44,9 +43,8 @@ class CleanRoom: """The alias of the collaborator tied to the local clean room.""" name: Optional[str] = None - """The name of the clean room. It should follow [UC securable naming requirements]. - - [UC securable naming requirements]: https://docs.databricks.com/en/data-governance/unity-catalog/index.html#securable-object-naming-requirements""" + """The name of the clean room. It should follow `UC securable naming requirements + `__.""" output_catalog: Optional[CleanRoomOutputCatalog] = None """Output catalog of the clean room. It is an output only field. Output catalog is manipulated @@ -552,12 +550,12 @@ def from_dict(cls, d: Dict[str, Any]) -> CleanRoomAssetVolumeLocalDetails: @dataclass class CleanRoomAutoApprovalRule: author_collaborator_alias: Optional[str] = None - """Collaborator alias of the author covered by the rule. Only one of `author_collaborator_alias` - and `author_scope` can be set.""" + """Collaborator alias of the author covered by the rule. Only one of ``author_collaborator_alias`` + and ``author_scope`` can be set.""" author_scope: Optional[CleanRoomAutoApprovalRuleAuthorScope] = None - """Scope of authors covered by the rule. Only one of `author_collaborator_alias` and `author_scope` - can be set.""" + """Scope of authors covered by the rule. Only one of ``author_collaborator_alias`` and + ``author_scope`` can be set.""" clean_room_name: Optional[str] = None """The name of the clean room this auto-approval rule belongs to.""" @@ -637,9 +635,8 @@ class CleanRoomCollaborator: collaborator_alias: str """Collaborator alias specified by the clean room creator. It is unique across all collaborators of this clean room, and used to derive multiple values internally such as catalog alias and clean - room name for single metastore clean rooms. It should follow [UC securable naming requirements]. - - [UC securable naming requirements]: https://docs.databricks.com/en/data-governance/unity-catalog/index.html#securable-object-naming-requirements""" + room name for single metastore clean rooms. It should follow `UC securable naming requirements + `__.""" display_name: Optional[str] = None """Generated display name for the collaborator. In the case of a single metastore clean room, it is @@ -661,8 +658,7 @@ class CleanRoomCollaborator: the clean room.""" organization_name: Optional[str] = None - """[Organization name](:method:metastores/list#metastores-delta_sharing_organization_name) - configured in the metastore""" + """Organization name configured in the metastore""" def as_dict(self) -> dict: """Serializes the CleanRoomCollaborator into a dictionary suitable for use as a JSON request body.""" @@ -879,10 +875,9 @@ def from_dict(cls, d: Dict[str, Any]) -> CleanRoomNotebookTaskRun: @dataclass class CleanRoomOutputCatalog: catalog_name: Optional[str] = None - """The name of the output catalog in UC. It should follow [UC securable naming requirements]. The - field will always exist if status is CREATED. - - [UC securable naming requirements]: https://docs.databricks.com/en/data-governance/unity-catalog/index.html#securable-object-naming-requirements""" + """The name of the output catalog in UC. It should follow `UC securable naming requirements + `__. + The field will always exist if status is CREATED.""" status: Optional[CleanRoomOutputCatalogOutputCatalogStatus] = None @@ -934,7 +929,6 @@ class CleanRoomRemoteDetail: that satisfies the owner condition: 1. It has the creator's global_metastore_id (determined by caller of CreateCleanRoom). - 2. Its invite_recipient_email is empty.""" compliance_security_profile: Optional[ComplianceSecurityProfile] = None @@ -1661,8 +1655,8 @@ def update( For notebooks, the name is the notebook file name. For jar analyses, the name is the jar analysis name. :param asset: :class:`CleanRoomAsset` - The asset to update. The asset's `name` and `asset_type` fields are used to identify the asset to - update. + The asset to update. The asset's ``name`` and ``asset_type`` fields are used to identify the asset + to update. :returns: :class:`CleanRoomAsset` """ @@ -2059,7 +2053,7 @@ def update(self, name: str, *, clean_room: Optional[CleanRoom] = None) -> CleanR """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. + When the caller is a metastore admin, only the **owner** field can be updated. :param name: str Name of the clean room. diff --git a/databricks/sdk/service/compute.py b/databricks/sdk/service/compute.py index 2a570e0d6..ad43bd3e4 100755 --- a/databricks/sdk/service/compute.py +++ b/databricks/sdk/service/compute.py @@ -53,7 +53,7 @@ class Adlsgen2Info: destination: str """abfss destination, e.g. - `abfss://@.dfs.core.windows.net/`.""" + ``abfss://@.dfs.core.windows.net/``.""" def as_dict(self) -> dict: """Serializes the Adlsgen2Info into a dictionary suitable for use as a JSON request body.""" @@ -79,7 +79,7 @@ def from_dict(cls, d: Dict[str, Any]) -> Adlsgen2Info: class AutoScale: max_workers: Optional[int] = None """The maximum number of workers to which the cluster can scale up when overloaded. Note that - `max_workers` must be strictly greater than `min_workers`.""" + ``max_workers`` must be strictly greater than ``min_workers``.""" min_workers: Optional[int] = None """The minimum number of workers to which the cluster can scale down when underutilized. It is also @@ -121,15 +121,15 @@ class AwsAttributes: volumes. For node types with no instance store, at least one EBS volume needs to be specified; otherwise, cluster creation will fail. - These EBS volumes will be mounted at `/ebs0`, `/ebs1`, and etc. Instance store volumes will be - mounted at `/local_disk0`, `/local_disk1`, and etc. + These EBS volumes will be mounted at ``/ebs0``, ``/ebs1``, and etc. Instance store volumes will + be mounted at ``/local_disk0``, ``/local_disk1``, and etc. If EBS volumes are attached, Databricks will configure Spark to use only the EBS volumes for scratch storage because heterogenously sized scratch devices can lead to inefficient disk utilization. If no EBS volumes are attached, Databricks will configure Spark to use instance store volumes. - Please note that if EBS volumes are specified, then the Spark configuration `spark.local.dir` + Please note that if EBS volumes are specified, then the Spark configuration ``spark.local.dir`` will be overridden.""" ebs_volume_iops: Optional[int] = None @@ -149,13 +149,13 @@ class AwsAttributes: """The type of EBS volumes that will be launched with this cluster.""" first_on_demand: Optional[int] = None - """The first `first_on_demand` nodes of the cluster will be placed on on-demand instances. If this - value is greater than 0, the cluster driver node in particular will be placed on an on-demand - instance. If this value is greater than or equal to the current cluster size, all nodes will be - placed on on-demand instances. If this value is less than the current cluster size, - `first_on_demand` nodes will be placed on on-demand instances and the remainder will be placed - on `availability` instances. Note that this value does not affect cluster size and cannot - currently be mutated over the lifetime of a cluster.""" + """The first ``first_on_demand`` nodes of the cluster will be placed on on-demand instances. If + this value is greater than 0, the cluster driver node in particular will be placed on an + on-demand instance. If this value is greater than or equal to the current cluster size, all + nodes will be placed on on-demand instances. If this value is less than the current cluster + size, ``first_on_demand`` nodes will be placed on on-demand instances and the remainder will be + placed on ``availability`` instances. Note that this value does not affect cluster size and + cannot currently be mutated over the lifetime of a cluster.""" instance_profile_arn: Optional[str] = None """Nodes for this cluster will only be placed on AWS instances with this instance profile. If @@ -168,9 +168,9 @@ class AwsAttributes: spot_bid_price_percent: Optional[int] = None """The bid price for AWS spot instances, as a percentage of the corresponding instance type's on-demand price. For example, if this field is set to 50, and the cluster needs a new - `r3.xlarge` spot instance, then the bid price is half of the price of on-demand `r3.xlarge` + ``r3.xlarge`` spot instance, then the bid price is half of the price of on-demand ``r3.xlarge`` instances. Similarly, if this field is set to 200, the bid price is twice the price of on-demand - `r3.xlarge` instances. If not specified, the default value is 100. When spot instances are + ``r3.xlarge`` instances. If not specified, the default value is 100. When spot instances are requested for this cluster, only spot instances whose bid price percentage matches this field will be considered. Note that, for safety, we enforce this field to be no more than 10000.""" @@ -183,8 +183,8 @@ class AwsAttributes: place cluster in a zone with high availability, and will retry placement in a different AZ if there is not enough capacity. - The list of available zones as well as the default value can be found by using the `List Zones` - method.""" + The list of available zones as well as the default value can be found by using the ``List + Zones`` method.""" def as_dict(self) -> dict: """Serializes the AwsAttributes into a dictionary suitable for use as a JSON request body.""" @@ -254,9 +254,10 @@ def from_dict(cls, d: Dict[str, Any]) -> AwsAttributes: class AwsAvailability(Enum): - """Availability type used for all subsequent nodes past the `first_on_demand` ones. + """Availability type used for all subsequent nodes past the ``first_on_demand`` ones. - Note: If `first_on_demand` is zero, this availability type will be used for the entire cluster.""" + Note: If ``first_on_demand`` is zero, this availability type will be used for the entire + cluster.""" ON_DEMAND = "ON_DEMAND" SPOT = "SPOT" @@ -268,16 +269,16 @@ class AzureAttributes: """Attributes set during cluster creation which are related to Microsoft Azure.""" availability: Optional[AzureAvailability] = None - """Availability type used for all subsequent nodes past the `first_on_demand` ones. Note: If - `first_on_demand` is zero, this availability type will be used for the entire cluster.""" + """Availability type used for all subsequent nodes past the ``first_on_demand`` ones. Note: If + ``first_on_demand`` is zero, this availability type will be used for the entire cluster.""" first_on_demand: Optional[int] = None - """The first `first_on_demand` nodes of the cluster will be placed on on-demand instances. This + """The first ``first_on_demand`` nodes of the cluster will be placed on on-demand instances. This value should be greater than 0, to make sure the cluster driver node is placed on an on-demand instance. If this value is greater than or equal to the current cluster size, all nodes will be placed on on-demand instances. If this value is less than the current cluster size, - `first_on_demand` nodes will be placed on on-demand instances and the remainder will be placed - on `availability` instances. Note that this value does not affect cluster size and cannot + ``first_on_demand`` nodes will be placed on on-demand instances and the remainder will be placed + on ``availability`` instances. Note that this value does not affect cluster size and cannot currently be mutated over the lifetime of a cluster.""" log_analytics_info: Optional[LogAnalyticsInfo] = None @@ -327,8 +328,8 @@ def from_dict(cls, d: Dict[str, Any]) -> AzureAttributes: class AzureAvailability(Enum): - """Availability type used for all subsequent nodes past the `first_on_demand` ones. Note: If - `first_on_demand` is zero, this availability type will be used for the entire cluster.""" + """Availability type used for all subsequent nodes past the ``first_on_demand`` ones. Note: If + ``first_on_demand`` is zero, this availability type will be used for the entire cluster.""" ON_DEMAND_AZURE = "ON_DEMAND_AZURE" SPOT_AZURE = "SPOT_AZURE" @@ -573,8 +574,8 @@ class ClusterAttributes: the lifetime of a cluster.""" 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.""" + """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.""" autotermination_minutes: Optional[int] = None """Automatically terminates the cluster after it is inactive for this time in minutes. If not set, @@ -594,8 +595,8 @@ class ClusterAttributes: """The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`.""" + every ``5 mins``. The destination of driver logs is ``$destination/$clusterId/driver``, while + the destination of executor logs is ``$destination/$clusterId/executor``.""" cluster_name: Optional[str] = None """Cluster name requested by the user. This doesn't have to be unique. If not specified at @@ -604,12 +605,11 @@ class ClusterAttributes: custom_tags: Optional[Dict[str, str]] = None """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: + 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""" + tags""" data_security_mode: Optional[DataSecurityMode] = None @@ -625,7 +625,7 @@ class ClusterAttributes: driver_node_type_id: Optional[str] = None """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. + type will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id @@ -644,17 +644,17 @@ class ClusterAttributes: init_scripts: Optional[List[InitScriptInfo]] = None """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`.""" + scripts are executed sequentially in the order provided. If ``cluster_log_conf`` is specified, + init script logs are sent to ``//init_scripts``.""" 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 when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, - `spark_conf`, and `num_workers`""" + When set to true, Databricks will automatically set single node related ``custom_tags``, + ``spark_conf``, and ``num_workers``""" kind: Optional[Kind] = None @@ -674,47 +674,47 @@ class ClusterAttributes: runtime_engine: Optional[RuntimeEngine] = None """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`. + 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.""" single_user_name: Optional[str] = None - """Single user name if data_security_mode is `SINGLE_USER`""" + """Single user name if data_security_mode is ``SINGLE_USER``""" spark_conf: Optional[Dict[str, str]] = None """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.""" + ``spark.driver.extraJavaOptions`` and ``spark.executor.extraJavaOptions`` respectively.""" spark_env_vars: Optional[Dict[str, str]] = None """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. + 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 + 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"}`""" + 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"}``""" ssh_public_keys: Optional[List[str]] = None """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.""" + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys + can be specified.""" total_initial_remote_disk_size: Optional[int] = None """If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks.""" use_ml_runtime: Optional[bool] = None - """This field can only be used when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" + ``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.""" worker_node_type_flexibility: Optional[NodeTypeFlexibility] = None """Flexible node type configuration for worker nodes.""" @@ -973,8 +973,8 @@ class ClusterDetails: """The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`.""" + every ``5 mins``. The destination of driver logs is ``$destination/$clusterId/driver``, while + the destination of executor logs is ``$destination/$clusterId/executor``.""" cluster_log_status: Optional[LogSyncStatus] = None """Cluster log delivery status.""" @@ -997,26 +997,21 @@ class ClusterDetails: custom_tags: Optional[Dict[str, str]] = None """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: + 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""" + tags""" data_security_mode: Optional[DataSecurityMode] = None default_tags: Optional[Dict[str, str]] = None - """Tags that are added by Databricks regardless of any `custom_tags`, including: + """Tags that are added by Databricks regardless of any ``custom_tags``, including: - Vendor: Databricks - - Creator: - - ClusterName: - - ClusterId: - - Name: """ docker_image: Optional[DockerImage] = None @@ -1035,7 +1030,7 @@ class ClusterDetails: driver_node_type_id: Optional[str] = None """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. + type will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id @@ -1057,17 +1052,17 @@ class ClusterDetails: init_scripts: Optional[List[InitScriptInfo]] = None """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`.""" + scripts are executed sequentially in the order provided. If ``cluster_log_conf`` is specified, + init script logs are sent to ``//init_scripts``.""" 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 when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, - `spark_conf`, and `num_workers`""" + 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 @@ -1089,13 +1084,13 @@ class ClusterDetails: num_workers: Optional[int] = None """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. + ``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.""" + workers, whereas the workers listed in ``spark_info`` will gradually increase from 5 to 10 as + the new nodes are provisioned.""" policy_id: Optional[str] = None """The ID of the cluster policy used to create the cluster if applicable.""" @@ -1107,41 +1102,41 @@ class ClusterDetails: runtime_engine: Optional[RuntimeEngine] = None """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`. + 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.""" single_user_name: Optional[str] = None - """Single user name if data_security_mode is `SINGLE_USER`""" + """Single user name if data_security_mode is ``SINGLE_USER``""" spark_conf: Optional[Dict[str, str]] = None """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.""" + ``spark.driver.extraJavaOptions`` and ``spark.executor.extraJavaOptions`` respectively.""" spark_context_id: Optional[int] = None """A canonical SparkContext identifier. This value *does* change when the Spark driver restarts. - The pair `(cluster_id, spark_context_id)` is a globally unique identifier over all Spark + The pair ``(cluster_id, spark_context_id)`` is a globally unique identifier over all Spark contexts.""" spark_env_vars: Optional[Dict[str, str]] = None """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. + 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 + 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"}`""" + 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"}``""" spark_version: Optional[str] = None - """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.""" + """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.""" spec: Optional[ClusterSpec] = None """The spec contains a snapshot of the latest user specified settings that were used to create/edit @@ -1149,36 +1144,36 @@ class ClusterDetails: ssh_public_keys: Optional[List[str]] = None """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.""" + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys + can be specified.""" start_time: Optional[int] = None """Time (in epoch milliseconds) when the cluster creation request was received (when the cluster - entered a `PENDING` state).""" + entered a ``PENDING`` state).""" state: Optional[State] = None """Current state of the cluster.""" state_message: Optional[str] = None """A message associated with the most recent state transition (e.g., the reason why the cluster - entered a `TERMINATED` state).""" + entered a ``TERMINATED`` state).""" terminated_time: Optional[int] = None """Time (in epoch milliseconds) when the cluster was terminated, if applicable.""" termination_reason: Optional[TerminationReason] = None """Information about why the cluster was terminated. This field only appears when the cluster is in - a `TERMINATING` or `TERMINATED` state.""" + a ``TERMINATING`` or ``TERMINATED`` state.""" total_initial_remote_disk_size: Optional[int] = None """If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks.""" use_ml_runtime: Optional[bool] = None - """This field can only be used when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" + ``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.""" worker_node_type_flexibility: Optional[NodeTypeFlexibility] = None """Flexible node type configuration for worker nodes.""" @@ -1558,18 +1553,18 @@ class ClusterLogConf: """Cluster log delivery config""" dbfs: Optional[DbfsStorageInfo] = None - """destination needs to be provided. e.g. `{ "dbfs" : { "destination" : "dbfs:/home/cluster_log" } - }`""" + """destination needs to be provided. e.g. ``{ "dbfs" : { "destination" : "dbfs:/home/cluster_log" } + }``""" s3: Optional[S3StorageInfo] = None - """destination and either the region or endpoint need to be provided. e.g. `{ "s3": { "destination" - : "s3://cluster_log_bucket/prefix", "region" : "us-west-2" } }` Cluster iam role is used to - access s3, please make sure the cluster iam role in `instance_profile_arn` has permission to - write data to the s3 destination.""" + """destination and either the region or endpoint need to be provided. e.g. ``{ "s3": { + "destination" : "s3://cluster_log_bucket/prefix", "region" : "us-west-2" } }`` Cluster iam role + is used to access s3, please make sure the cluster iam role in ``instance_profile_arn`` has + permission to write data to the s3 destination.""" volumes: Optional[VolumesStorageInfo] = None - """destination needs to be provided, e.g. `{ "volumes": { "destination": - "/Volumes/catalog/schema/volume/cluster_log" } }`""" + """destination needs to be provided, e.g. ``{ "volumes": { "destination": + "/Volumes/catalog/schema/volume/cluster_log" } }``""" def as_dict(self) -> dict: """Serializes the ClusterLogConf into a dictionary suitable for use as a JSON request body.""" @@ -2008,13 +2003,13 @@ class ClusterSize: num_workers: Optional[int] = None """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. + ``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.""" + workers, whereas the workers listed in ``spark_info`` will gradually increase from 5 to 10 as + the new nodes are provisioned.""" def as_dict(self) -> dict: """Serializes the ClusterSize into a dictionary suitable for use as a JSON request body.""" @@ -2084,8 +2079,8 @@ class ClusterSpec: """The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`.""" + every ``5 mins``. The destination of driver logs is ``$destination/$clusterId/driver``, while + the destination of executor logs is ``$destination/$clusterId/executor``.""" cluster_name: Optional[str] = None """Cluster name requested by the user. This doesn't have to be unique. If not specified at @@ -2094,12 +2089,11 @@ class ClusterSpec: custom_tags: Optional[Dict[str, str]] = None """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: + 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""" + tags""" data_security_mode: Optional[DataSecurityMode] = None @@ -2115,7 +2109,7 @@ class ClusterSpec: driver_node_type_id: Optional[str] = None """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. + type will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id @@ -2134,17 +2128,17 @@ class ClusterSpec: init_scripts: Optional[List[InitScriptInfo]] = None """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`.""" + scripts are executed sequentially in the order provided. If ``cluster_log_conf`` is specified, + init script logs are sent to ``//init_scripts``.""" 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 when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, - `spark_conf`, and `num_workers`""" + When set to true, Databricks will automatically set single node related ``custom_tags``, + ``spark_conf``, and ``num_workers``""" kind: Optional[Kind] = None @@ -2156,13 +2150,13 @@ class ClusterSpec: num_workers: Optional[int] = None """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. + ``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.""" + workers, whereas the workers listed in ``spark_info`` will gradually increase from 5 to 10 as + the new nodes are provisioned.""" policy_id: Optional[str] = None """The ID of the cluster policy used to create the cluster if applicable.""" @@ -2174,51 +2168,51 @@ class ClusterSpec: runtime_engine: Optional[RuntimeEngine] = None """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`. + 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.""" single_user_name: Optional[str] = None - """Single user name if data_security_mode is `SINGLE_USER`""" + """Single user name if data_security_mode is ``SINGLE_USER``""" spark_conf: Optional[Dict[str, str]] = None """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.""" + ``spark.driver.extraJavaOptions`` and ``spark.executor.extraJavaOptions`` respectively.""" spark_env_vars: Optional[Dict[str, str]] = None """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. + 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 + 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"}`""" + 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"}``""" spark_version: Optional[str] = None - """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.""" + """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.""" ssh_public_keys: Optional[List[str]] = None """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.""" + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys + can be specified.""" total_initial_remote_disk_size: Optional[int] = None """If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks.""" use_ml_runtime: Optional[bool] = None - """This field can only be used when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" + ``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.""" worker_node_type_flexibility: Optional[NodeTypeFlexibility] = None """Flexible node type configuration for worker nodes.""" @@ -2631,9 +2625,11 @@ def from_dict(cls, d: Dict[str, Any]) -> Created: @dataclass class CustomPolicyTag: key: str - """The key of the tag. - Must be unique among all custom tags of the same policy - Cannot be - “budget-policy-name”, “budget-policy-id” or "budget-policy-resolution-result" - these - tags are preserved.""" + """The key of the tag. + + - Must be unique among all custom tags of the same policy + - Cannot be “budget-policy-name”, “budget-policy-id” or + "budget-policy-resolution-result" - these tags are preserved.""" value: Optional[str] = None """The value of the tag.""" @@ -2717,28 +2713,31 @@ class DataPlaneEventDetailsEventType(Enum): class DataSecurityMode(Enum): """Data security mode decides what data governance model to use when accessing data from a cluster. - * `DATA_SECURITY_MODE_AUTO`: Databricks will choose the most appropriate access mode depending - on your compute configuration. * `DATA_SECURITY_MODE_STANDARD`: 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. * `DATA_SECURITY_MODE_DEDICATED`: 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. + - ``DATA_SECURITY_MODE_AUTO``: Databricks will choose the most appropriate access mode depending + on your compute configuration. + - ``DATA_SECURITY_MODE_STANDARD``: 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. + - ``DATA_SECURITY_MODE_DEDICATED``: 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. The following modes are legacy aliases for the above modes: - * `USER_ISOLATION`: Legacy alias for `DATA_SECURITY_MODE_STANDARD`. * `SINGLE_USER`: Legacy - alias for `DATA_SECURITY_MODE_DEDICATED`. + - ``USER_ISOLATION``: Legacy alias for ``DATA_SECURITY_MODE_STANDARD``. + - ``SINGLE_USER``: Legacy alias for ``DATA_SECURITY_MODE_DEDICATED``. 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.""" + - ``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.""" DATA_SECURITY_MODE_AUTO = "DATA_SECURITY_MODE_AUTO" DATA_SECURITY_MODE_DEDICATED = "DATA_SECURITY_MODE_DEDICATED" @@ -2757,7 +2756,7 @@ class DbfsStorageInfo: """A storage location in DBFS""" destination: str - """dbfs destination, e.g. `dbfs:/my/path`""" + """dbfs destination, e.g. ``dbfs:/my/path``""" def as_dict(self) -> dict: """Serializes the DbfsStorageInfo into a dictionary suitable for use as a JSON request body.""" @@ -2876,19 +2875,24 @@ class DiskSpec: Databricks will launch a total of 6 disks, 100 GiB each, for this cluster.""" disk_count: Optional[int] = None - """The number of disks launched for each instance: - This feature is only enabled for supported - node types. - Users can choose up to the limit of the disks supported by the node type. - For - node types with no OS disk, at least one disk must be specified; otherwise, cluster creation - will fail. + """The number of disks launched for each instance: + + - This feature is only enabled for supported node types. + - Users can choose up to the limit of the disks supported by the node type. + - For node types with no OS disk, at least one disk must be specified; otherwise, cluster + creation will fail. If disks are attached, Databricks will configure Spark to use only the disks for scratch storage, because heterogenously sized scratch devices can lead to inefficient disk utilization. If no disks are attached, Databricks will configure Spark to use instance store disks. - Note: If disks are specified, then the Spark configuration `spark.local.dir` will be overridden. + Note: If disks are specified, then the Spark configuration ``spark.local.dir`` will be + overridden. + + Disks will be mounted at: - Disks will be mounted at: - For AWS: `/ebs0`, `/ebs1`, and etc. - For Azure: `/remote_volume0`, - `/remote_volume1`, and etc.""" + - For AWS: ``/ebs0``, ``/ebs1``, and etc. + - For Azure: ``/remote_volume0``, ``/remote_volume1``, and etc.""" disk_iops: Optional[int] = None @@ -2896,9 +2900,15 @@ class DiskSpec: """The size of each disk (in GiB) launched for each instance. Values must fall into the supported range for a particular instance type. - For AWS: - General Purpose SSD: 100 - 4096 GiB - Throughput Optimized HDD: 500 - 4096 GiB + For AWS: - For Azure: - Premium LRS (SSD): 1 - 1023 GiB - Standard LRS (HDD): 1- 1023 GiB""" + - General Purpose SSD: 100 - 4096 GiB + - Throughput Optimized HDD: 500 - 4096 GiB + + For Azure: + + - Premium LRS (SSD): 1 - 1023 GiB + - Standard LRS (HDD): 1- 1023 GiB""" disk_throughput: Optional[int] = None @@ -3185,16 +3195,16 @@ class Environment: base_environment: Optional[str] = None """The base environment this environment is built on top of. A base environment defines the environment version and a list of dependencies for serverless compute. The value can be a file - path to a custom `env.yaml` file (e.g., `/Workspace/path/to/env.yaml`). Support for a - Databricks-provided base environment ID (e.g., `workspace-base-environments/databricks_ai_v4`) + path to a custom ``env.yaml`` file (e.g., ``/Workspace/path/to/env.yaml``). Support for a + Databricks-provided base environment ID (e.g., ``workspace-base-environments/databricks_ai_v4``) and workspace base environment ID (e.g., - `workspace-base-environments/dbe_b849b66e-b31a-4cb5-b161-1f2b10877fb7`) is in Beta. Either - `environment_version` or `base_environment` can be provided. For more information about - Databricks-provided base environments, see the [list workspace base - environments](:method:Environments/ListWorkspaceBaseEnvironments) API. For more information, see""" + ``workspace-base-environments/dbe_b849b66e-b31a-4cb5-b161-1f2b10877fb7``) is in Beta. Either + ``environment_version`` or ``base_environment`` can be provided. For more information about + Databricks-provided base environments, see the list workspace base environments API. For more + information, see""" client: Optional[str] = None - """Use `environment_version` instead.""" + """Use ``environment_version`` instead.""" dependencies: Optional[List[str]] = None """List of pip dependencies, as supported by the version of pip in this environment. Each @@ -3204,13 +3214,13 @@ class Environment: Databricks), or a VCS project URL.""" environment_version: Optional[str] = None - """Either `environment_version` or `base_environment` needs to be provided. Environment version + """Either ``environment_version`` or ``base_environment`` needs to be provided. Environment version used by the environment. Each version comes with a specific Python version and a set of Python packages. The version is a string, consisting of an integer.""" java_dependencies: Optional[List[str]] = None """List of java dependencies. Each dependency is a string representing a java library path. For - example: `/Volumes/path/to/test.jar`.""" + example: ``/Volumes/path/to/test.jar``.""" def as_dict(self) -> dict: """Serializes the Environment into a dictionary suitable for use as a JSON request body.""" @@ -3257,8 +3267,8 @@ def from_dict(cls, d: Dict[str, Any]) -> Environment: @dataclass class EventDetails: attributes: Optional[ClusterAttributes] = None - """* For created clusters, the attributes of the cluster. * For edited clusters, the new attributes - of the cluster.""" + """- For created clusters, the attributes of the cluster. + - For edited clusters, the new attributes of the cluster.""" cause: Optional[EventDetailsCause] = None """The cause of a change in target size.""" @@ -3292,8 +3302,9 @@ class EventDetails: """Instance Id where the event originated from""" job_run_name: Optional[str] = None - """Unique identifier of the specific job run associated with this cluster event * For clusters - created for jobs, this will be the same as the cluster name""" + """Unique identifier of the specific job run associated with this cluster event + + - For clusters created for jobs, this will be the same as the cluster name""" previous_attributes: Optional[ClusterAttributes] = None """The cluster attributes before a cluster was edited.""" @@ -3305,8 +3316,10 @@ class EventDetails: """Previous disk size in bytes""" reason: Optional[TerminationReason] = None - """A termination reason: * On a TERMINATED event, this is the reason of the termination. * On a - RESIZE_COMPLETE event, this indicates the reason that we failed to acquire some nodes.""" + """A termination reason: + + - On a TERMINATED event, this is the reason of the termination. + - On a RESIZE_COMPLETE event, this indicates the reason that we failed to acquire some nodes.""" target_num_vcpus: Optional[int] = None """The targeted number of vCPUs in the cluster.""" @@ -3497,12 +3510,12 @@ class GcpAttributes: supported, and only on N2D instance types. When not set, no confidential computing is applied.""" first_on_demand: Optional[int] = None - """The first `first_on_demand` nodes of the cluster will be placed on on-demand instances. This + """The first ``first_on_demand`` nodes of the cluster will be placed on on-demand instances. This value should be greater than 0, to make sure the cluster driver node is placed on an on-demand instance. If this value is greater than or equal to the current cluster size, all nodes will be placed on on-demand instances. If this value is less than the current cluster size, - `first_on_demand` nodes will be placed on on-demand instances and the remainder will be placed - on `availability` instances. Note that this value does not affect cluster size and cannot + ``first_on_demand`` nodes will be placed on on-demand instances and the remainder will be placed + on ``availability`` instances. Note that this value does not affect cluster size and cannot currently be mutated over the lifetime of a cluster.""" google_service_account: Optional[str] = None @@ -3512,10 +3525,9 @@ class GcpAttributes: local_ssd_count: Optional[int] = None """If provided, each node (workers and driver) in the cluster will have this number of local SSDs - attached. Each local SSD is 375GB in size. Refer to [GCP documentation] for the supported number - of local SSDs for each instance type. - - [GCP documentation]: https://cloud.google.com/compute/docs/disks/local-ssd#choose_number_local_ssds""" + attached. Each local SSD is 375GB in size. Refer to `GCP documentation + `__ for the + supported number of local SSDs for each instance type.""" use_preemptible_executors: Optional[bool] = None """This field determines whether the spark executors will be scheduled to run on preemptible VMs @@ -3524,10 +3536,13 @@ class GcpAttributes: zone_id: Optional[str] = None """Identifier for the availability zone in which the cluster resides. This can be one of the - following: - "HA" => High availability, spread nodes across availability zones for a Databricks - deployment region [default]. - "AUTO" => Databricks picks an availability zone to schedule the - cluster on. - A GCP availability zone => Pick One of the available zones for (machine type + - region) from https://cloud.google.com/compute/docs/regions-zones.""" + following: + + - "HA" => High availability, spread nodes across availability zones for a Databricks deployment + region [default]. + - "AUTO" => Databricks picks an availability zone to schedule the cluster on. + - A GCP availability zone => Pick One of the available zones for (machine type + region) from + https://cloud.google.com/compute/docs/regions-zones.""" def as_dict(self) -> dict: """Serializes the GcpAttributes into a dictionary suitable for use as a JSON request body.""" @@ -3600,7 +3615,7 @@ class GcsStorageInfo: """A storage location in Google Cloud Platform's GCS""" destination: str - """GCS destination/URI, e.g. `gs://my-bucket/some-prefix`""" + """GCS destination/URI, e.g. ``gs://my-bucket/some-prefix``""" def as_dict(self) -> dict: """Serializes the GcsStorageInfo into a dictionary suitable for use as a JSON request body.""" @@ -3895,7 +3910,7 @@ class GetInstancePool: custom_tags: Optional[Dict[str, str]] = None """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: + and EBS volumes) with these tags in addition to ``default_tags``. Notes: - Currently, Databricks allows at most 45 custom tags""" @@ -3903,11 +3918,8 @@ class GetInstancePool: """Tags that are added by Databricks regardless of any ``custom_tags``, including: - Vendor: Databricks - - InstancePoolCreator: - - InstancePoolName: - - InstancePoolId: """ disk_spec: Optional[DiskSpec] = None @@ -4398,31 +4410,33 @@ class InitScriptInfo: abfss: Optional[Adlsgen2Info] = None """destination needs to be provided, e.g. - `abfss://@.dfs.core.windows.net/`""" + ``abfss://@.dfs.core.windows.net/``""" dbfs: Optional[DbfsStorageInfo] = None - """destination needs to be provided. e.g. `{ "dbfs": { "destination" : "dbfs:/home/cluster_log" } - }`""" + """destination needs to be provided. e.g. ``{ "dbfs": { "destination" : "dbfs:/home/cluster_log" } + }``""" file: Optional[LocalFileInfo] = None - """destination needs to be provided, e.g. `{ "file": { "destination": "file:/my/local/file.sh" } }`""" + """destination needs to be provided, e.g. ``{ "file": { "destination": "file:/my/local/file.sh" } + }``""" gcs: Optional[GcsStorageInfo] = None - """destination needs to be provided, e.g. `{ "gcs": { "destination": "gs://my-bucket/file.sh" } }`""" + """destination needs to be provided, e.g. ``{ "gcs": { "destination": "gs://my-bucket/file.sh" } + }``""" s3: Optional[S3StorageInfo] = None - """destination and either the region or endpoint need to be provided. e.g. `{ \"s3\": { - \"destination\": \"s3://cluster_log_bucket/prefix\", \"region\": \"us-west-2\" } }` Cluster iam - role is used to access s3, please make sure the cluster iam role in `instance_profile_arn` has + """destination and either the region or endpoint need to be provided. e.g. ``{ \"s3\": { + \"destination\": \"s3://cluster_log_bucket/prefix\", \"region\": \"us-west-2\" } }`` Cluster iam + role is used to access s3, please make sure the cluster iam role in ``instance_profile_arn`` has permission to write data to the s3 destination.""" volumes: Optional[VolumesStorageInfo] = None - """destination needs to be provided. e.g. `{ \"volumes\" : { \"destination\" : - \"/Volumes/my-init.sh\" } }`""" + """destination needs to be provided. e.g. ``{ \"volumes\" : { \"destination\" : + \"/Volumes/my-init.sh\" } }``""" workspace: Optional[WorkspaceStorageInfo] = None - """destination needs to be provided, e.g. `{ "workspace": { "destination": - "/cluster-init-scripts/setup-datadog.sh" } }`""" + """destination needs to be provided, e.g. ``{ "workspace": { "destination": + "/cluster-init-scripts/setup-datadog.sh" } }``""" def as_dict(self) -> dict: """Serializes the InitScriptInfo into a dictionary suitable for use as a JSON request body.""" @@ -4480,11 +4494,11 @@ def from_dict(cls, d: Dict[str, Any]) -> InitScriptInfo: class InitScriptInfoAndExecutionDetails: abfss: Optional[Adlsgen2Info] = None """destination needs to be provided, e.g. - `abfss://@.dfs.core.windows.net/`""" + ``abfss://@.dfs.core.windows.net/``""" dbfs: Optional[DbfsStorageInfo] = None - """destination needs to be provided. e.g. `{ "dbfs": { "destination" : "dbfs:/home/cluster_log" } - }`""" + """destination needs to be provided. e.g. ``{ "dbfs": { "destination" : "dbfs:/home/cluster_log" } + }``""" error_message: Optional[str] = None """Additional details regarding errors (such as a file not found message if the status is @@ -4495,15 +4509,17 @@ class InitScriptInfoAndExecutionDetails: """The number duration of the script execution in seconds""" file: Optional[LocalFileInfo] = None - """destination needs to be provided, e.g. `{ "file": { "destination": "file:/my/local/file.sh" } }`""" + """destination needs to be provided, e.g. ``{ "file": { "destination": "file:/my/local/file.sh" } + }``""" gcs: Optional[GcsStorageInfo] = None - """destination needs to be provided, e.g. `{ "gcs": { "destination": "gs://my-bucket/file.sh" } }`""" + """destination needs to be provided, e.g. ``{ "gcs": { "destination": "gs://my-bucket/file.sh" } + }``""" s3: Optional[S3StorageInfo] = None - """destination and either the region or endpoint need to be provided. e.g. `{ \"s3\": { - \"destination\": \"s3://cluster_log_bucket/prefix\", \"region\": \"us-west-2\" } }` Cluster iam - role is used to access s3, please make sure the cluster iam role in `instance_profile_arn` has + """destination and either the region or endpoint need to be provided. e.g. ``{ \"s3\": { + \"destination\": \"s3://cluster_log_bucket/prefix\", \"region\": \"us-west-2\" } }`` Cluster iam + role is used to access s3, please make sure the cluster iam role in ``instance_profile_arn`` has permission to write data to the s3 destination.""" status: Optional[InitScriptExecutionDetailsInitScriptExecutionStatus] = None @@ -4514,12 +4530,12 @@ class InitScriptInfoAndExecutionDetails: enabled and script execution fails.""" volumes: Optional[VolumesStorageInfo] = None - """destination needs to be provided. e.g. `{ \"volumes\" : { \"destination\" : - \"/Volumes/my-init.sh\" } }`""" + """destination needs to be provided. e.g. ``{ \"volumes\" : { \"destination\" : + \"/Volumes/my-init.sh\" } }``""" workspace: Optional[WorkspaceStorageInfo] = None - """destination needs to be provided, e.g. `{ "workspace": { "destination": - "/cluster-init-scripts/setup-datadog.sh" } }`""" + """destination needs to be provided, e.g. ``{ "workspace": { "destination": + "/cluster-init-scripts/setup-datadog.sh" } }``""" def as_dict(self) -> dict: """Serializes the InitScriptInfoAndExecutionDetails into a dictionary suitable for use as a JSON request body.""" @@ -4732,7 +4748,7 @@ class InstancePoolAndStats: custom_tags: Optional[Dict[str, str]] = None """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: + and EBS volumes) with these tags in addition to ``default_tags``. Notes: - Currently, Databricks allows at most 45 custom tags""" @@ -4740,11 +4756,8 @@ class InstancePoolAndStats: """Tags that are added by Databricks regardless of any ``custom_tags``, including: - Vendor: Databricks - - InstancePoolCreator: - - InstancePoolName: - - InstancePoolId: """ disk_spec: Optional[DiskSpec] = None @@ -4958,9 +4971,9 @@ class InstancePoolAwsAttributes: spot_bid_price_percent: Optional[int] = None """Calculates the bid price for AWS spot instances, as a percentage of the corresponding instance type's on-demand price. For example, if this field is set to 50, and the cluster needs a new - `r3.xlarge` spot instance, then the bid price is half of the price of on-demand `r3.xlarge` + ``r3.xlarge`` spot instance, then the bid price is half of the price of on-demand ``r3.xlarge`` instances. Similarly, if this field is set to 200, the bid price is twice the price of on-demand - `r3.xlarge` instances. If not specified, the default value is 100. When spot instances are + ``r3.xlarge`` instances. If not specified, the default value is 100. When spot instances are requested for this cluster, only spot instances whose bid price percentage matches this field will be considered. Note that, for safety, we enforce this field to be no more than 10000.""" @@ -4970,7 +4983,7 @@ class InstancePoolAwsAttributes: Databricks deployment. For example, "us-west-2a" is not a valid zone id if the Databricks deployment resides in the "us-east-1" region. This is an optional field at cluster creation, and if not specified, a default zone will be used. The list of available zones as well as the - default value can be found by using the `List Zones` method.""" + default value can be found by using the ``List Zones`` method.""" def as_dict(self) -> dict: """Serializes the InstancePoolAwsAttributes into a dictionary suitable for use as a JSON request body.""" @@ -5071,10 +5084,9 @@ class InstancePoolGcpAttributes: local_ssd_count: Optional[int] = None """If provided, each node in the instance pool will have this number of local SSDs attached. Each - local SSD is 375GB in size. Refer to [GCP documentation] for the supported number of local SSDs - for each instance type. - - [GCP documentation]: https://cloud.google.com/compute/docs/disks/local-ssd#choose_number_local_ssds""" + local SSD is 375GB in size. Refer to `GCP documentation + `__ for the + supported number of local SSDs for each instance type.""" zone_id: Optional[str] = None """Identifier for the availability zone/datacenter in which the cluster resides. This string will @@ -5083,10 +5095,12 @@ class InstancePoolGcpAttributes: workspace resides in the "us-east1" region. This is an optional field at instance pool creation, and if not specified, a default zone will be used. - This field can be one of the following: - "HA" => High availability, spread nodes across - availability zones for a Databricks deployment region - A GCP availability zone => Pick One of - the available zones for (machine type + region) from - https://cloud.google.com/compute/docs/regions-zones (e.g. "us-west1-a"). + This field can be one of the following: + + - "HA" => High availability, spread nodes across availability zones for a Databricks deployment + region + - A GCP availability zone => Pick One of the available zones for (machine type + region) from + https://cloud.google.com/compute/docs/regions-zones (e.g. "us-west1-a"). If empty, Databricks picks an availability zone to schedule the cluster on.""" @@ -5245,8 +5259,10 @@ def from_dict(cls, d: Dict[str, Any]) -> InstancePoolPermissionsDescription: class InstancePoolState(Enum): """The state of a Cluster. The current allowable state transitions are as follows: - - ``ACTIVE`` -> ``STOPPED`` - ``ACTIVE`` -> ``DELETED`` - ``STOPPED`` -> ``ACTIVE`` - - ``STOPPED`` -> ``DELETED``""" + - ``ACTIVE`` -> ``STOPPED`` + - ``ACTIVE`` -> ``DELETED`` + - ``STOPPED`` -> ``ACTIVE`` + - ``STOPPED`` -> ``DELETED``""" ACTIVE = "ACTIVE" DELETED = "DELETED" @@ -5339,17 +5355,15 @@ class InstanceProfile: iam_role_arn: Optional[str] = None """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. + with `Databricks SQL Serverless `__. - [Databricks SQL Serverless]: https://docs.databricks.com/sql/admin/serverless.html""" + Otherwise, this field is optional.""" is_meta_instance_profile: Optional[bool] = None """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`.""" + field is optional, the default value is ``false``.""" def as_dict(self) -> dict: """Serializes the InstanceProfile into a dictionary suitable for use as a JSON request body.""" @@ -5386,15 +5400,16 @@ def from_dict(cls, d: Dict[str, Any]) -> InstanceProfile: class Kind(Enum): """The kind of compute described by this compute specification. - Depending on `kind`, different validations and default values will be applied. + Depending on ``kind``, different validations and default values will be applied. - Clusters with `kind = CLASSIC_PREVIEW` support the following fields, whereas clusters with no - specified `kind` do not. * [is_single_node](/api/workspace/clusters/create#is_single_node) * - [use_ml_runtime](/api/workspace/clusters/create#use_ml_runtime) + Clusters with ``kind = CLASSIC_PREVIEW`` support the following fields, whereas clusters with no + specified ``kind`` do not. - By using the [simple form], your clusters are automatically using `kind = CLASSIC_PREVIEW`. + - is_single_node + - use_ml_runtime - [simple form]: https://docs.databricks.com/compute/simple-form.html""" + By using the `simple form `__, your + clusters are automatically using ``kind = CLASSIC_PREVIEW``.""" CLASSIC_PREVIEW = "CLASSIC_PREVIEW" @@ -5417,29 +5432,29 @@ class Library: jar: Optional[str] = None """URI of the JAR library to install. Supported URIs include Workspace paths, Unity Catalog Volumes - paths, and S3 URIs. For example: `{ "jar": "/Workspace/path/to/library.jar" }`, `{ "jar" : - "/Volumes/path/to/library.jar" }` or `{ "jar": "s3://my-bucket/library.jar" }`. If S3 is used, - please make sure the cluster has read access on the library. You may need to launch the cluster - with an IAM role to access the S3 URI.""" + paths, and S3 URIs. For example: ``{ "jar": "/Workspace/path/to/library.jar" }``, ``{ "jar" : + "/Volumes/path/to/library.jar" }`` or ``{ "jar": "s3://my-bucket/library.jar" }``. If S3 is + used, please make sure the cluster has read access on the library. You may need to launch the + cluster with an IAM role to access the S3 URI.""" maven: Optional[MavenLibrary] = None - """Specification of a maven library to be installed. For example: `{ "coordinates": - "org.jsoup:jsoup:1.7.2" }`""" + """Specification of a maven library to be installed. For example: ``{ "coordinates": + "org.jsoup:jsoup:1.7.2" }``""" pypi: Optional[PythonPyPiLibrary] = None - """Specification of a PyPi library to be installed. For example: `{ "package": "simplejson" }`""" + """Specification of a PyPi library to be installed. For example: ``{ "package": "simplejson" }``""" requirements: Optional[str] = None """URI of the requirements.txt file to install. Only Workspace paths and Unity Catalog Volumes - paths are supported. For example: `{ "requirements": "/Workspace/path/to/requirements.txt" }` or - `{ "requirements" : "/Volumes/path/to/requirements.txt" }`""" + paths are supported. For example: ``{ "requirements": "/Workspace/path/to/requirements.txt" }`` + or ``{ "requirements" : "/Volumes/path/to/requirements.txt" }``""" whl: Optional[str] = None """URI of the wheel library to install. Supported URIs include Workspace paths, Unity Catalog - Volumes paths, and S3 URIs. For example: `{ "whl": "/Workspace/path/to/library.whl" }`, `{ "whl" - : "/Volumes/path/to/library.whl" }` or `{ "whl": "s3://my-bucket/library.whl" }`. If S3 is used, - please make sure the cluster has read access on the library. You may need to launch the cluster - with an IAM role to access the S3 URI.""" + Volumes paths, and S3 URIs. For example: ``{ "whl": "/Workspace/path/to/library.whl" }``, ``{ + "whl" : "/Volumes/path/to/library.whl" }`` or ``{ "whl": "s3://my-bucket/library.whl" }``. If S3 + is used, please make sure the cluster has read access on the library. You may need to launch the + cluster with an IAM role to access the S3 URI.""" def as_dict(self) -> dict: """Serializes the Library into a dictionary suitable for use as a JSON request body.""" @@ -5974,7 +5989,7 @@ class ListSortOrder(Enum): @dataclass class LocalFileInfo: destination: str - """local file destination, e.g. `file:/my/local/file.sh`""" + """local file destination, e.g. ``file:/my/local/file.sh``""" def as_dict(self) -> dict: """Serializes the LocalFileInfo into a dictionary suitable for use as a JSON request body.""" @@ -6034,7 +6049,7 @@ class LogSyncStatus: """The log delivery status""" last_attempted: Optional[int] = None - """The timestamp of last attempt. If the last attempt fails, `last_exception` will contain the + """The timestamp of last attempt. If the last attempt fails, ``last_exception`` will contain the exception in the last attempt.""" last_exception: Optional[str] = None @@ -6074,7 +6089,7 @@ class MavenLibrary: """Gradle-style maven coordinates. For example: "org.jsoup:jsoup:1.7.2".""" exclusions: Optional[List[str]] = None - """List of dependences to exclude. For example: `["slf4j:slf4j", "*:hadoop-client"]`. + """List of dependences to exclude. For example: ``["slf4j:slf4j", "*:hadoop-client"]``. Maven dependency exclusions: https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html.""" @@ -6470,9 +6485,8 @@ class Policy: deleted.""" definition: Optional[str] = None - """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""" + """Policy definition document expressed in `Databricks Cluster Policy Definition Language + `__.""" description: Optional[str] = None """Additional human-readable description of the cluster policy.""" @@ -6494,20 +6508,19 @@ class Policy: 100 characters.""" policy_family_definition_overrides: Optional[str] = None - """Policy definition JSON document expressed in [Databricks Policy Definition Language]. The JSON + """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""" + rules specified here are merged into the inherited policy definition.""" policy_family_id: Optional[str] = None """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.""" + Cannot be used with ``definition``. Use ``policy_family_definition_overrides`` instead to + customize the policy definition.""" policy_id: Optional[str] = None """Canonical unique identifier for the Cluster Policy.""" @@ -6587,9 +6600,8 @@ def from_dict(cls, d: Dict[str, Any]) -> Policy: @dataclass class PolicyFamily: definition: Optional[str] = None - """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""" + """Policy definition document expressed in `Databricks Cluster Policy Definition Language + `__.""" description: Optional[str] = None """Human-readable description of the purpose of the policy family.""" @@ -6774,11 +6786,10 @@ class Results: file_name: Optional[str] = None """The image data in one of the following formats: - 1. A Data URL with base64-encoded image data: `data:image/{type};base64,{base64-data}`. Example: - `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...` - - 2. A FileStore file path for large images: `/plots/{filename}.png`. Example: - `/plots/b6a7ad70-fb2c-4353-8aed-3f1e015174a4.png`""" + 1. A Data URL with base64-encoded image data: ``data:image/{type};base64,{base64-data}``. + Example: ``data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...`` + 2. A FileStore file path for large images: ``/plots/{filename}.png``. Example: + ``/plots/b6a7ad70-fb2c-4353-8aed-3f1e015174a4.png``""" file_names: Optional[List[str]] = None """List of image data for multiple images. Each element follows the same format as file_name.""" @@ -6878,36 +6889,36 @@ class S3StorageInfo: """A storage location in Amazon S3""" destination: str - """S3 destination, e.g. `s3://my-bucket/some-prefix` Note that logs will be delivered using cluster - iam role, please make sure you set cluster iam role and the role has write access to the + """S3 destination, e.g. ``s3://my-bucket/some-prefix`` Note that logs will be delivered using + cluster iam role, please make sure you set cluster iam role and the role has write access to the destination. Please also note that you cannot use AWS keys to deliver logs.""" canned_acl: Optional[str] = None - """(Optional) Set canned access control list for the logs, e.g. `bucket-owner-full-control`. If - `canned_cal` is set, please make sure the cluster iam role has `s3:PutObjectAcl` permission on - the destination bucket and prefix. The full list of possible canned acl can be found at + """(Optional) Set canned access control list for the logs, e.g. ``bucket-owner-full-control``. If + ``canned_cal`` is set, please make sure the cluster iam role has ``s3:PutObjectAcl`` permission + on the destination bucket and prefix. The full list of possible canned acl can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl. Please also note that by default only the object owner gets full controls. If you are using cross account role - for writing data, you may want to set `bucket-owner-full-control` to make bucket owner able to + for writing data, you may want to set ``bucket-owner-full-control`` to make bucket owner able to read the logs.""" enable_encryption: Optional[bool] = None - """(Optional) Flag to enable server side encryption, `false` by default.""" + """(Optional) Flag to enable server side encryption, ``false`` by default.""" encryption_type: Optional[str] = None - """(Optional) The encryption type, it could be `sse-s3` or `sse-kms`. It will be used only when - encryption is enabled and the default type is `sse-s3`.""" + """(Optional) The encryption type, it could be ``sse-s3`` or ``sse-kms``. It will be used only when + encryption is enabled and the default type is ``sse-s3``.""" endpoint: Optional[str] = None - """S3 endpoint, e.g. `https://s3-us-west-2.amazonaws.com`. Either region or endpoint needs to be + """S3 endpoint, e.g. ``https://s3-us-west-2.amazonaws.com``. Either region or endpoint needs to be set. If both are set, endpoint will be used.""" kms_key: Optional[str] = None """(Optional) Kms key which will be used if encryption is enabled and encryption type is set to - `sse-kms`.""" + ``sse-kms``.""" region: Optional[str] = None - """S3 region, e.g. `us-west-2`. Either region or endpoint needs to be set. If both are set, + """S3 region, e.g. ``us-west-2``. Either region or endpoint needs to be set. If both are set, endpoint will be used.""" def as_dict(self) -> dict: @@ -7125,10 +7136,16 @@ def from_dict(cls, d: Dict[str, Any]) -> StartClusterResponse: class State(Enum): """The state of a Cluster. The current allowable state transitions are as follows: - - `PENDING` -> `RUNNING` - `PENDING` -> `TERMINATING` - `RUNNING` -> `RESIZING` - `RUNNING` -> - `RESTARTING` - `RUNNING` -> `TERMINATING` - `RESTARTING` -> `RUNNING` - `RESTARTING` -> - `TERMINATING` - `RESIZING` -> `RUNNING` - `RESIZING` -> `TERMINATING` - `TERMINATING` -> - `TERMINATED`""" + - ``PENDING`` -> ``RUNNING`` + - ``PENDING`` -> ``TERMINATING`` + - ``RUNNING`` -> ``RESIZING`` + - ``RUNNING`` -> ``RESTARTING`` + - ``RUNNING`` -> ``TERMINATING`` + - ``RESTARTING`` -> ``RUNNING`` + - ``RESTARTING`` -> ``TERMINATING`` + - ``RESIZING`` -> ``RUNNING`` + - ``RESIZING`` -> ``TERMINATING`` + - ``TERMINATING`` -> ``TERMINATED``""" ERROR = "ERROR" PENDING = "PENDING" @@ -7448,8 +7465,8 @@ class UpdateClusterResource: """The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`.""" + every ``5 mins``. The destination of driver logs is ``$destination/$clusterId/driver``, while + the destination of executor logs is ``$destination/$clusterId/executor``.""" cluster_name: Optional[str] = None """Cluster name requested by the user. This doesn't have to be unique. If not specified at @@ -7458,12 +7475,11 @@ class UpdateClusterResource: custom_tags: Optional[Dict[str, str]] = None """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: + 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""" + tags""" data_security_mode: Optional[DataSecurityMode] = None @@ -7479,7 +7495,7 @@ class UpdateClusterResource: driver_node_type_id: Optional[str] = None """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. + type will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id @@ -7498,17 +7514,17 @@ class UpdateClusterResource: init_scripts: Optional[List[InitScriptInfo]] = None """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`.""" + scripts are executed sequentially in the order provided. If ``cluster_log_conf`` is specified, + init script logs are sent to ``//init_scripts``.""" 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 when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, - `spark_conf`, and `num_workers`""" + When set to true, Databricks will automatically set single node related ``custom_tags``, + ``spark_conf``, and ``num_workers``""" kind: Optional[Kind] = None @@ -7520,13 +7536,13 @@ class UpdateClusterResource: num_workers: Optional[int] = None """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. + ``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.""" + workers, whereas the workers listed in ``spark_info`` will gradually increase from 5 to 10 as + the new nodes are provisioned.""" policy_id: Optional[str] = None """The ID of the cluster policy used to create the cluster if applicable.""" @@ -7538,51 +7554,51 @@ class UpdateClusterResource: runtime_engine: Optional[RuntimeEngine] = None """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`. + 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.""" single_user_name: Optional[str] = None - """Single user name if data_security_mode is `SINGLE_USER`""" + """Single user name if data_security_mode is ``SINGLE_USER``""" spark_conf: Optional[Dict[str, str]] = None """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.""" + ``spark.driver.extraJavaOptions`` and ``spark.executor.extraJavaOptions`` respectively.""" spark_env_vars: Optional[Dict[str, str]] = None """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. + 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 + 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"}`""" + 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"}``""" spark_version: Optional[str] = None - """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.""" + """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.""" ssh_public_keys: Optional[List[str]] = None """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.""" + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys + can be specified.""" total_initial_remote_disk_size: Optional[int] = None """If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks.""" use_ml_runtime: Optional[bool] = None - """This field can only be used when `kind = CLASSIC_PREVIEW`. + """This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not.""" + ``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.""" worker_node_type_flexibility: Optional[NodeTypeFlexibility] = None """Flexible node type configuration for worker nodes.""" @@ -7812,8 +7828,8 @@ class VolumesStorageInfo: """A storage location back by UC Volumes.""" destination: str - """UC Volumes destination, e.g. `/Volumes/catalog/schema/vol1/init-scripts/setup-datadog.sh` or - `dbfs:/Volumes/catalog/schema/vol1/init-scripts/setup-datadog.sh`""" + """UC Volumes destination, e.g. ``/Volumes/catalog/schema/vol1/init-scripts/setup-datadog.sh`` or + ``dbfs:/Volumes/catalog/schema/vol1/init-scripts/setup-datadog.sh``""" def as_dict(self) -> dict: """Serializes the VolumesStorageInfo into a dictionary suitable for use as a JSON request body.""" @@ -7867,7 +7883,7 @@ class WorkspaceStorageInfo: """A storage location in Workspace Filesystem (WSFS)""" destination: str - """wsfs destination, e.g. `workspace:/cluster-init-scripts/setup-datadog.sh`""" + """wsfs destination, e.g. ``workspace:/cluster-init-scripts/setup-datadog.sh``""" def as_dict(self) -> dict: """Serializes the WorkspaceStorageInfo into a dictionary suitable for use as a JSON request body.""" @@ -7894,16 +7910,22 @@ class ClusterPoliciesAPI: 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. + 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. + 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.""" @@ -7925,9 +7947,8 @@ def create( """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 + Policy definition document expressed in `Databricks Cluster Policy Definition Language + `__. :param description: str (optional) Additional human-readable description of the cluster policy. :param libraries: List[:class:`Library`] (optional) @@ -7940,19 +7961,18 @@ def create( 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 + 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. + Cannot be used with ``definition``. Use ``policy_family_definition_overrides`` instead to customize + the policy definition. :returns: :class:`CreatePolicyResponse` """ @@ -8025,9 +8045,8 @@ def edit( :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 + Policy definition document expressed in `Databricks Cluster Policy Definition Language + `__. :param description: str (optional) Additional human-readable description of the cluster policy. :param libraries: List[:class:`Library`] (optional) @@ -8040,19 +8059,18 @@ def edit( 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 + 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. + Cannot be used with ``definition``. Use ``policy_family_definition_overrides`` instead to customize + the policy definition. """ @@ -8157,11 +8175,15 @@ def list( """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. + 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. + 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` """ @@ -8339,7 +8361,7 @@ def wait_get_cluster_terminated( def change_owner(self, cluster_id: str, owner_username: str): """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`. + ``owner_username``. :param cluster_id: str :param owner_username: str @@ -8414,13 +8436,12 @@ def create( 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 + the `create compute UI `__ and then copying the + generated JSON definition from the UI. :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. + 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. @@ -8443,18 +8464,17 @@ def create( The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`. + ``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. For job clusters, the cluster name is automatically set based on the job and job run IDs. :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: + 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) :param docker_image: :class:`DockerImage` (optional) @@ -8466,7 +8486,7 @@ def create( Flexible node type configuration for the driver node. :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. + will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id and @@ -8481,15 +8501,15 @@ def create( 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`. + 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 when `kind = CLASSIC_PREVIEW`. + This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, - and `num_workers` + When set to true, Databricks will automatically set single node related ``custom_tags``, + ``spark_conf``, and ``num_workers`` :param kind: :class:`Kind` (optional) :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in @@ -8498,12 +8518,12 @@ def create( :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. + ``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 + 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. @@ -8513,41 +8533,41 @@ def create( :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`. + 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` + 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. + ``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 + 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 + 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"}` + 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. + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys can + be specified. :param total_initial_remote_disk_size: int (optional) If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks. :param use_ml_runtime: bool (optional) - This field can only be used when `kind = CLASSIC_PREVIEW`. + This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not. + ``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 worker_node_type_flexibility: :class:`NodeTypeFlexibility` (optional) Flexible node type configuration for worker nodes. :param workload_type: :class:`WorkloadType` (optional) @@ -8724,8 +8744,8 @@ def create_and_wait( def delete(self, cluster_id: str) -> Wait[ClusterDetails]: """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. + 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. @@ -8793,22 +8813,22 @@ def edit( workload_type: Optional[WorkloadType] = None, ) -> Wait[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. + 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 + 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. + 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. + 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. @@ -8829,18 +8849,17 @@ def edit( The configuration for delivering spark logs to a long-term storage destination. Three kinds of destinations (DBFS, S3 and Unity Catalog volumes) 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`. + ``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. For job clusters, the cluster name is automatically set based on the job and job run IDs. :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: + 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) :param docker_image: :class:`DockerImage` (optional) @@ -8852,7 +8871,7 @@ def edit( Flexible node type configuration for the driver node. :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. + will be set as the same value as ``node_type_id`` defined above. This field, along with node_type_id, should not be set if virtual_cluster_size is set. If both driver_node_type_id, node_type_id, and virtual_cluster_size are specified, driver_node_type_id and @@ -8867,15 +8886,15 @@ def edit( 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`. + 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 when `kind = CLASSIC_PREVIEW`. + This field can only be used when ``kind = CLASSIC_PREVIEW``. - When set to true, Databricks will automatically set single node related `custom_tags`, `spark_conf`, - and `num_workers` + When set to true, Databricks will automatically set single node related ``custom_tags``, + ``spark_conf``, and ``num_workers`` :param kind: :class:`Kind` (optional) :param node_type_id: str (optional) This field encodes, through a single value, the resources available to each of the Spark nodes in @@ -8884,12 +8903,12 @@ def edit( :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. + ``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 + 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. @@ -8899,41 +8918,41 @@ def edit( :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`. + 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` + 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. + ``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 + 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 + 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"}` + 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. + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys can + be specified. :param total_initial_remote_disk_size: int (optional) If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED disks. :param use_ml_runtime: bool (optional) - This field can only be used when `kind = CLASSIC_PREVIEW`. + This field can only be used when ``kind = CLASSIC_PREVIEW``. - `effective_spark_version` is determined by `spark_version` (DBR release), this field - `use_ml_runtime`, and whether `node_type_id` is gpu node or not. + ``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 worker_node_type_flexibility: :class:`NodeTypeFlexibility` (optional) Flexible node type configuration for worker nodes. :param workload_type: :class:`WorkloadType` (optional) @@ -9395,7 +9414,7 @@ def resize( self, cluster_id: str, *, autoscale: Optional[AutoScale] = None, num_workers: Optional[int] = None ) -> Wait[ClusterDetails]: """Resizes a cluster to have a desired number of workers. This will fail unless the cluster is in a - `RUNNING` state. + ``RUNNING`` state. :param cluster_id: str The cluster to be resized. @@ -9404,12 +9423,12 @@ def resize( 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. + ``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 + the workers listed in ``spark_info`` will gradually increase from 5 to 10 as the new nodes are provisioned. :returns: @@ -9447,7 +9466,7 @@ def resize_and_wait( return self.resize(autoscale=autoscale, cluster_id=cluster_id, num_workers=num_workers).result(timeout=timeout) def restart(self, cluster_id: str, *, restart_user: Optional[str] = None) -> Wait[ClusterDetails]: - """Restarts a Spark cluster with the supplied ID. If the cluster is not currently in a `RUNNING` state, + """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 @@ -9528,11 +9547,15 @@ def spark_versions(self) -> GetSparkVersionsResponse: return GetSparkVersionsResponse.from_dict(res) def start(self, cluster_id: str) -> Wait[ClusterDetails]: - """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. + """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. @@ -9588,13 +9611,13 @@ def update( self, cluster_id: str, update_mask: str, *, cluster: Optional[UpdateClusterResource] = None ) -> Wait[ClusterDetails]: """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. + 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. @@ -9603,14 +9626,14 @@ def update( for more details. The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :param cluster: :class:`UpdateClusterResource` (optional) The cluster to be updated. @@ -9797,7 +9820,7 @@ def cancel( ) -> Wait[CommandStatusResponse]: """Cancels a currently running command within an execution context. - The command ID is obtained from a prior successful call to __execute__. + The command ID is obtained from a prior successful call to **execute**. :param cluster_id: str (optional) :param command_id: str (optional) @@ -9845,7 +9868,7 @@ def cancel_and_wait( def command_status(self, cluster_id: str, context_id: str, command_id: str) -> 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__. + The command ID is obtained from a prior successful call to **execute**. :param cluster_id: str :param context_id: str @@ -10038,7 +10061,7 @@ class GlobalInitScriptsAPI: **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.""" + entire cluster fails with a ``GLOBAL_INIT_SCRIPT_FAILURE`` error code.""" def __init__(self, api_client): self._api = api_client @@ -10130,8 +10153,8 @@ def get(self, script_id: str) -> GlobalInitScriptDetailsWithContent: def list(self) -> Iterator[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. + but **not** the script contents. To retrieve the contents of a script, use the get a global init + script operation. :returns: Iterator over :class:`GlobalInitScriptDetails` @@ -10255,7 +10278,7 @@ def create( 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: + 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) @@ -10392,7 +10415,7 @@ def edit( :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: + 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) @@ -10593,10 +10616,10 @@ def update_permissions( 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.""" def __init__(self, api_client): self._api = api_client @@ -10619,16 +10642,14 @@ def add( :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]. + `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 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 @@ -10669,31 +10690,29 @@ def edit( """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]. + - 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]. + 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]. + `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 default value is ``false``. """ @@ -10804,10 +10823,12 @@ def all_cluster_statuses(self) -> Iterator[ClusterLibraryStatuses]: def cluster_status(self, cluster_id: str) -> Iterator[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. + 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. @@ -10904,13 +10925,13 @@ def enforce_compliance( self, cluster_id: str, *, validate_only: Optional[bool] = None ) -> 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. + 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 + 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. + 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, SDP, or Models services cannot be enforced by this API. Instead, use the "Enforce job policy compliance" API to enforce policy compliance on jobs. @@ -10978,7 +10999,7 @@ def list_compliance( 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`. + ``next_page_token`` or ``prev_page_token``. :returns: Iterator over :class:`ClusterCompliance` """ diff --git a/databricks/sdk/service/dashboards.py b/databricks/sdk/service/dashboards.py index b3cbaf296..190afe9c5 100755 --- a/databricks/sdk/service/dashboards.py +++ b/databricks/sdk/service/dashboards.py @@ -34,18 +34,19 @@ class AuthorizationDetails: grant_rules: Optional[List[AuthorizationDetailsGrantRule]] = None """Represents downscoped permission rules with specific access rights. This field is specific to - `workspace_rule_set` constraint.""" + ``workspace_rule_set`` constraint.""" resource_legacy_acl_path: Optional[str] = None """The acl path of the tree store resource resource.""" resource_name: Optional[str] = None """The resource name to which the authorization rule applies. This field is specific to - `workspace_rule_set` constraint. Format: `workspaces/{workspace_id}/dashboards/{dashboard_id}`""" + ``workspace_rule_set`` constraint. Format: + ``workspaces/{workspace_id}/dashboards/{dashboard_id}``""" type: Optional[str] = None - """The type of authorization downscoping policy. Ex: `workspace_rule_set` defines access rules for - a specific workspace resource""" + """The type of authorization downscoping policy. Ex: ``workspace_rule_set`` defines access rules + for a specific workspace resource""" def as_dict(self) -> dict: """Serializes the AuthorizationDetails into a dictionary suitable for use as a JSON request body.""" @@ -89,7 +90,7 @@ class AuthorizationDetailsGrantRule: permission_set: Optional[str] = None """Permission sets for dashboard are defined in iam-common/rbac-common/permission-sets/definitions/TreeStoreBasePermissionSets Ex: - `permissionSets/dashboard.runner`""" + ``permissionSets/dashboard.runner``""" def as_dict(self) -> dict: """Serializes the AuthorizationDetailsGrantRule into a dictionary suitable for use as a JSON request body.""" @@ -114,16 +115,14 @@ def from_dict(cls, d: Dict[str, Any]) -> AuthorizationDetailsGrantRule: @dataclass class CronSchedule: quartz_cron_expression: str - """A cron expression using quartz syntax. EX: `0 0 8 * * ?` represents everyday at 8am. See [Cron - Trigger] for details. - - [Cron Trigger]: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html""" + """A cron expression using quartz syntax. EX: ``0 0 8 * * ?`` represents everyday at 8am. See `Cron + Trigger + `__ for + details.""" timezone_id: str - """A Java timezone id. The schedule will be resolved with respect to this timezone. See [Java - TimeZone] for details. - - [Java TimeZone]: https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html""" + """A Java timezone id. The schedule will be resolved with respect to this timezone. See `Java + TimeZone `__ for details.""" def as_dict(self) -> dict: """Serializes the CronSchedule into a dictionary suitable for use as a JSON request body.""" @@ -173,15 +172,14 @@ class Dashboard: path: Optional[str] = None """The workspace path of the dashboard asset, including the file name. Exported dashboards always - have the file extension `.lvdash.json`. This field is excluded in List Dashboards responses.""" + have the file extension ``.lvdash.json``. This field is excluded in List Dashboards responses.""" serialized_dashboard: Optional[str] = None """The contents of the dashboard in serialized string form. This field is excluded in List - Dashboards responses. Use the [get dashboard API] to retrieve an example response, which - includes the `serialized_dashboard` field. This field provides the structure of the JSON string - that represents the dashboard's layout and components. - - [get dashboard API]: https://docs.databricks.com/api/workspace/lakeview/get""" + Dashboards responses. Use the `get dashboard API + `__ to retrieve an example response, + which includes the ``serialized_dashboard`` field. This field provides the structure of the JSON + string that represents the dashboard's layout and components.""" update_time: Optional[str] = None """The timestamp of when the dashboard was last updated by the user. This field is excluded in List @@ -595,42 +593,53 @@ class GenieEvalResultDetails: Assessment reasons describe why a Genie response was scored as BAD. - Deterministic values (compared against the ground truth result): - EMPTY_RESULT: Genie's - generated SQL results were empty for this benchmark question. - RESULT_MISSING_ROWS: Genie's - generated SQL response is missing rows from the provided ground truth SQL. - RESULT_EXTRA_ROWS: - Genie's generated SQL response has more rows than the provided ground truth SQL. - - RESULT_MISSING_COLUMNS: Genie's generated SQL response is missing columns from the provided - ground truth SQL. - RESULT_EXTRA_COLUMNS: Genie's generated SQL response has more columns than - the provided ground truth SQL. - SINGLE_CELL_DIFFERENCE: Single value result was produced but - differs from ground truth result. - EMPTY_GOOD_SQL: The benchmark SQL returned an empty result. + Deterministic values (compared against the ground truth result): + + - EMPTY_RESULT: Genie's generated SQL results were empty for this benchmark question. + - RESULT_MISSING_ROWS: Genie's generated SQL response is missing rows from the provided ground + truth SQL. + - RESULT_EXTRA_ROWS: Genie's generated SQL response has more rows than the provided ground truth + SQL. + - RESULT_MISSING_COLUMNS: Genie's generated SQL response is missing columns from the provided + ground truth SQL. + - RESULT_EXTRA_COLUMNS: Genie's generated SQL response has more columns than the provided ground + truth SQL. + - SINGLE_CELL_DIFFERENCE: Single value result was produced but differs from ground truth result. + - EMPTY_GOOD_SQL: The benchmark SQL returned an empty result. - COLUMN_TYPE_DIFFERENCE: The values between the results match but the column type is different. - LLM judge ratings explain the factors driving BAD results: - - LLM_JUDGE_MISSING_OR_INCORRECT_FILTER: Genie's generated SQL is missing a WHERE clause condition - or has incorrect filter logic that excludes/includes wrong data. - - LLM_JUDGE_INCOMPLETE_OR_PARTIAL_OUTPUT: Genie's generated SQL returns only some of the requested - data or columns, missing parts of what the ground truth SQL returns. - - LLM_JUDGE_MISINTERPRETATION_OF_USER_REQUEST: Genie's generated SQL fundamentally misunderstands - what the user is asking for, addressing the wrong question or goal. - - LLM_JUDGE_INSTRUCTION_COMPLIANCE_OR_MISSING_BUSINESS_LOGIC: Genie's generated SQL fails to apply - specified instructions or business logic that should be followed. - - LLM_JUDGE_INCORRECT_METRIC_CALCULATION: Genie's generated SQL uses incorrect logic or makes - wrong assumptions when calculating metrics. - LLM_JUDGE_INCORRECT_TABLE_OR_FIELD_USAGE: Genie's - generated SQL references wrong tables, columns, or uses fields that don't match the ground truth - SQL's intent. - LLM_JUDGE_INCORRECT_FUNCTION_USAGE: Genie's generated SQL uses SQL functions - incorrectly or inappropriately (wrong parameters, wrong function for the task, etc.). - - LLM_JUDGE_MISSING_OR_INCORRECT_JOIN: Genie's generated SQL is missing necessary joins between - tables or has incorrect join conditions/types that produce wrong results. - - LLM_JUDGE_MISSING_OR_INCORRECT_AGGREGATION: Genie's generated SQL is missing GROUP BY clauses or - has incorrect grouping that doesn't match the requested aggregation level. - - LLM_JUDGE_FORMATTING_ERROR: Genie's generated SQL output has incorrect formatting, ordering - (ORDER BY), or presentation issues that don't match expectations. - LLM_JUDGE_OTHER: LLM judge - identified an error that doesn't fall into other categories. + LLM judge ratings explain the factors driving BAD results: - Deprecated LLM judge values (kept for backward compatibility, do not use): - - LLM_JUDGE_MISSING_JOIN (deprecated) - LLM_JUDGE_WRONG_FILTER (deprecated) - - LLM_JUDGE_WRONG_AGGREGATION (deprecated) - LLM_JUDGE_WRONG_COLUMNS (deprecated) - - LLM_JUDGE_SYNTAX_ERROR (deprecated) - LLM_JUDGE_SEMANTIC_ERROR (deprecated)""" + - LLM_JUDGE_MISSING_OR_INCORRECT_FILTER: Genie's generated SQL is missing a WHERE clause + condition or has incorrect filter logic that excludes/includes wrong data. + - LLM_JUDGE_INCOMPLETE_OR_PARTIAL_OUTPUT: Genie's generated SQL returns only some of the + requested data or columns, missing parts of what the ground truth SQL returns. + - LLM_JUDGE_MISINTERPRETATION_OF_USER_REQUEST: Genie's generated SQL fundamentally + misunderstands what the user is asking for, addressing the wrong question or goal. + - LLM_JUDGE_INSTRUCTION_COMPLIANCE_OR_MISSING_BUSINESS_LOGIC: Genie's generated SQL fails to + apply specified instructions or business logic that should be followed. + - LLM_JUDGE_INCORRECT_METRIC_CALCULATION: Genie's generated SQL uses incorrect logic or makes + wrong assumptions when calculating metrics. + - LLM_JUDGE_INCORRECT_TABLE_OR_FIELD_USAGE: Genie's generated SQL references wrong tables, + columns, or uses fields that don't match the ground truth SQL's intent. + - LLM_JUDGE_INCORRECT_FUNCTION_USAGE: Genie's generated SQL uses SQL functions incorrectly or + inappropriately (wrong parameters, wrong function for the task, etc.). + - LLM_JUDGE_MISSING_OR_INCORRECT_JOIN: Genie's generated SQL is missing necessary joins between + tables or has incorrect join conditions/types that produce wrong results. + - LLM_JUDGE_MISSING_OR_INCORRECT_AGGREGATION: Genie's generated SQL is missing GROUP BY clauses + or has incorrect grouping that doesn't match the requested aggregation level. + - LLM_JUDGE_FORMATTING_ERROR: Genie's generated SQL output has incorrect formatting, ordering + (ORDER BY), or presentation issues that don't match expectations. + - LLM_JUDGE_OTHER: LLM judge identified an error that doesn't fall into other categories. + + Deprecated LLM judge values (kept for backward compatibility, do not use): + + - LLM_JUDGE_MISSING_JOIN (deprecated) + - LLM_JUDGE_WRONG_FILTER (deprecated) + - LLM_JUDGE_WRONG_AGGREGATION (deprecated) + - LLM_JUDGE_WRONG_COLUMNS (deprecated) + - LLM_JUDGE_SYNTAX_ERROR (deprecated) + - LLM_JUDGE_SEMANTIC_ERROR (deprecated)""" eval_run_status: Optional[EvaluationStatusType] = None """Current status of the evaluation run.""" @@ -871,8 +880,8 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieGenerateDownloadFullQueryResultRes @dataclass class GenieGetDownloadFullQueryResultResponse: statement_response: Optional[sql.StatementResponse] = None - """SQL Statement Execution response. See [Get status, manifest, and result first - chunk](:method:statementexecution/getstatement) for more details.""" + """SQL Statement Execution response. See Get status, manifest, and result first chunk for more + details.""" def as_dict(self) -> dict: """Serializes the GenieGetDownloadFullQueryResultResponse into a dictionary suitable for use as a JSON request body.""" @@ -897,8 +906,8 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieGetDownloadFullQueryResultResponse @dataclass class GenieGetMessageQueryResultResponse: statement_response: Optional[sql.StatementResponse] = None - """SQL Statement Execution response. See [Get status, manifest, and result first - chunk](:method:statementexecution/getstatement) for more details.""" + """SQL Statement Execution response. See Get status, manifest, and result first chunk for more + details.""" def as_dict(self) -> dict: """Serializes the GenieGetMessageQueryResultResponse into a dictionary suitable for use as a JSON request body.""" @@ -1191,7 +1200,7 @@ class GenieMessage: query_result: Optional[Result] = None """The result of SQL query if the message includes a query attachment. Deprecated. Use - `query_result_metadata` in `GenieQueryAttachment` instead.""" + ``query_result_metadata`` in ``GenieQueryAttachment`` instead.""" status: Optional[MessageStatus] = None @@ -1376,8 +1385,8 @@ class GenieQueryAttachment: """Metadata associated with the query result.""" statement_id: Optional[str] = None - """Statement Execution API statement id. Use [Get status, manifest, and result first - chunk](:method:statementexecution/getstatement) to get the full result data.""" + """Statement Execution API statement id. Use Get status, manifest, and result first chunk to get + the full result data.""" thoughts: Optional[List[Thought]] = None """Insights into how Genie came to generate the SQL.""" @@ -1499,9 +1508,9 @@ class GenieSpace: serialized_space: Optional[str] = None """The contents of the Genie Space in serialized string form. This field is excluded in List Genie - spaces responses. Use the [Get Genie Space](:method:genie/getspace) API to retrieve an example - response, which includes the `serialized_space` field. This field provides the structure of the - JSON string that represents the space's layout and components.""" + spaces responses. Use the Get Genie Space API to retrieve an example response, which includes + the ``serialized_space`` field. This field provides the structure of the JSON string that + represents the space's layout and components.""" warehouse_id: Optional[str] = None """Warehouse associated with the Genie Space""" @@ -1638,12 +1647,12 @@ def from_dict(cls, d: Dict[str, Any]) -> GenieSuggestedQuestionsAttachment: class GetPublishedDashboardTokenInfoResponse: authorization_details: Optional[List[AuthorizationDetails]] = None """Authorization constraints for accessing the published dashboard. Currently includes - `workspace_rule_set` and could be enriched with `unity_catalog_privileges` before oAuth token - generation.""" + ``workspace_rule_set`` and could be enriched with ``unity_catalog_privileges`` before oAuth + token generation.""" custom_claim: Optional[str] = None """Custom claim generated from external_value and external_viewer_id. Format: - `urn:aibi:external_data:::`""" + ``urn:aibi:external_data:::``""" scope: Optional[str] = None """Scope defining access permissions.""" @@ -1690,8 +1699,8 @@ class ListDashboardsResponse: dashboards: Optional[List[Dashboard]] = None next_page_token: Optional[str] = None - """A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, - there are no subsequent dashboards.""" + """A token, which can be sent as ``page_token`` to retrieve the next page. If this field is + omitted, there are no subsequent dashboards.""" def as_dict(self) -> dict: """Serializes the ListDashboardsResponse into a dictionary suitable for use as a JSON request body.""" @@ -1722,7 +1731,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListDashboardsResponse: @dataclass class ListSchedulesResponse: next_page_token: Optional[str] = None - """A token that can be used as a `page_token` in subsequent requests to retrieve the next page of + """A token that can be used as a ``page_token`` in subsequent requests to retrieve the next page of results. If this field is omitted, there are no subsequent schedules.""" schedules: Optional[List[Schedule]] = None @@ -1754,7 +1763,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListSchedulesResponse: @dataclass class ListSubscriptionsResponse: next_page_token: Optional[str] = None - """A token that can be used as a `page_token` in subsequent requests to retrieve the next page of + """A token that can be used as a ``page_token`` in subsequent requests to retrieve the next page of results. If this field is omitted, there are no subsequent subscriptions.""" subscriptions: Optional[List[Subscription]] = None @@ -1881,20 +1890,21 @@ class MessageErrorType(Enum): class MessageStatus(Enum): - """MessageStatus. The possible values are: * `FETCHING_METADATA`: Fetching metadata from the data - sources. * `FILTERING_CONTEXT`: Running smart context step to determine relevant context. * - `ASKING_AI`: Waiting for the LLM to respond to the user's question. * `PENDING_WAREHOUSE`: - Waiting for warehouse before the SQL query can start executing. * `EXECUTING_QUERY`: Executing a - generated SQL query. Get the SQL query result by calling - [getMessageAttachmentQueryResult](:method:genie/getMessageAttachmentQueryResult) API. * - `FAILED`: The response generation or query execution failed. See `error` field. * `COMPLETED`: - Message processing is completed. Results are in the `attachments` field. Get the SQL query - result by calling - [getMessageAttachmentQueryResult](:method:genie/getMessageAttachmentQueryResult) API. * - `SUBMITTED`: Message has been submitted. * `QUERY_RESULT_EXPIRED`: SQL result is not available - anymore. The user needs to rerun the query. Rerun the SQL query result by calling - [executeMessageAttachmentQuery](:method:genie/executeMessageAttachmentQuery) API. * `CANCELLED`: - Message has been cancelled.""" + """MessageStatus. The possible values are: + + - ``FETCHING_METADATA``: Fetching metadata from the data sources. + - ``FILTERING_CONTEXT``: Running smart context step to determine relevant context. + - ``ASKING_AI``: Waiting for the LLM to respond to the user's question. + - ``PENDING_WAREHOUSE``: Waiting for warehouse before the SQL query can start executing. + - ``EXECUTING_QUERY``: Executing a generated SQL query. Get the SQL query result by calling + getMessageAttachmentQueryResult API. + - ``FAILED``: The response generation or query execution failed. See ``error`` field. + - ``COMPLETED``: Message processing is completed. Results are in the ``attachments`` field. Get + the SQL query result by calling getMessageAttachmentQueryResult API. + - ``SUBMITTED``: Message has been submitted. + - ``QUERY_RESULT_EXPIRED``: SQL result is not available anymore. The user needs to rerun the + query. Rerun the SQL query result by calling executeMessageAttachmentQuery API. + - ``CANCELLED``: Message has been cancelled.""" ASKING_AI = "ASKING_AI" CANCELLED = "CANCELLED" @@ -2004,8 +2014,8 @@ class Result: """Row count of the result""" statement_id: Optional[str] = None - """Statement Execution API statement id. Use [Get status, manifest, and result first - chunk](:method:statementexecution/getstatement) to get the full result data.""" + """Statement Execution API statement id. Use Get status, manifest, and result first chunk to get + the full result data.""" statement_id_signature: Optional[str] = None """JWT corresponding to the statement contained in this result""" @@ -2206,11 +2216,11 @@ class ScoreReason(Enum): class Subscriber: destination_subscriber: Optional[SubscriptionSubscriberDestination] = None """The destination to receive the subscription email. This parameter is mutually exclusive with - `user_subscriber`.""" + ``user_subscriber``.""" user_subscriber: Optional[SubscriptionSubscriberUser] = None """The user to receive the subscription email. This parameter is mutually exclusive with - `destination_subscriber`.""" + ``destination_subscriber``.""" def as_dict(self) -> dict: """Serializes the Subscriber into a dictionary suitable for use as a JSON request body.""" @@ -2437,12 +2447,13 @@ class Thought: """The md formatted content for this thought.""" thought_type: Optional[ThoughtType] = None - """The category of this thought. The possible values are: * `THOUGHT_TYPE_DESCRIPTION`: A - high-level description of how the question was interpreted. * `THOUGHT_TYPE_UNDERSTANDING`: How - ambiguous parts of the question were resolved. * `THOUGHT_TYPE_DATA_SOURCING`: Which tables or - datasets were identified as relevant. * `THOUGHT_TYPE_INSTRUCTIONS`: Which author-defined - instructions were referenced. * `THOUGHT_TYPE_STEPS`: The logical steps taken to compute the - answer.""" + """The category of this thought. The possible values are: + + - ``THOUGHT_TYPE_DESCRIPTION``: A high-level description of how the question was interpreted. + - ``THOUGHT_TYPE_UNDERSTANDING``: How ambiguous parts of the question were resolved. + - ``THOUGHT_TYPE_DATA_SOURCING``: Which tables or datasets were identified as relevant. + - ``THOUGHT_TYPE_INSTRUCTIONS``: Which author-defined instructions were referenced. + - ``THOUGHT_TYPE_STEPS``: The logical steps taken to compute the answer.""" def as_dict(self) -> dict: """Serializes the Thought into a dictionary suitable for use as a JSON request body.""" @@ -2469,13 +2480,15 @@ def from_dict(cls, d: Dict[str, Any]) -> Thought: class ThoughtType(Enum): - """ThoughtType. The possible values are: * `THOUGHT_TYPE_UNSPECIFIED`: Default value that should - not be used. * `THOUGHT_TYPE_DESCRIPTION`: A high-level description of how the question was - interpreted. * `THOUGHT_TYPE_UNDERSTANDING`: How ambiguous parts of the question were resolved. - * `THOUGHT_TYPE_DATA_SOURCING`: Which tables or datasets were identified as relevant. * - `THOUGHT_TYPE_INSTRUCTIONS`: Which author-defined instructions were referenced. * - `THOUGHT_TYPE_STEPS`: The logical steps taken to compute the answer. The category of a Thought. - Additional values may be added in the future.""" + """ThoughtType. The possible values are: + + - ``THOUGHT_TYPE_UNSPECIFIED``: Default value that should not be used. + - ``THOUGHT_TYPE_DESCRIPTION``: A high-level description of how the question was interpreted. + - ``THOUGHT_TYPE_UNDERSTANDING``: How ambiguous parts of the question were resolved. + - ``THOUGHT_TYPE_DATA_SOURCING``: Which tables or datasets were identified as relevant. + - ``THOUGHT_TYPE_INSTRUCTIONS``: Which author-defined instructions were referenced. + - ``THOUGHT_TYPE_STEPS``: The logical steps taken to compute the answer. The category of a + Thought. Additional values may be added in the future.""" THOUGHT_TYPE_DATA_SOURCING = "THOUGHT_TYPE_DATA_SOURCING" THOUGHT_TYPE_DESCRIPTION = "THOUGHT_TYPE_DESCRIPTION" @@ -2564,8 +2577,8 @@ def wait_get_message_genie_completed( raise TimeoutError(f"timed out after {timeout}: {status_message}") def create_message(self, space_id: str, conversation_id: str, content: str) -> Wait[GenieMessage]: - """Create new message in a [conversation](:method:genie/startconversation). The AI response uses all - previously created messages in the conversation to respond. + """Create new message in a conversation. 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. @@ -2663,10 +2676,9 @@ def create_space( :param warehouse_id: str Warehouse to associate with the new space :param serialized_space: str - The contents of the Genie Space in serialized string form. Use the [Get Genie - Space](:method:genie/getspace) API to retrieve an example response, which includes the - `serialized_space` field. This field provides the structure of the JSON string that represents the - space's layout and components. + The contents of the Genie Space in serialized string form. Use the Get Genie Space API to retrieve + an example response, which includes the ``serialized_space`` field. This field provides the + structure of the JSON string that represents the space's layout and components. :param description: str (optional) Optional description :param parent_path: str (optional) @@ -2785,8 +2797,7 @@ def execute_message_attachment_query( def execute_message_query( self, space_id: str, conversation_id: str, message_id: str ) -> GenieGetMessageQueryResultResponse: - """DEPRECATED: Use [Execute Message Attachment Query](:method:genie/executemessageattachmentquery) - instead. + """DEPRECATED: Use Execute Message Attachment Query instead. :param space_id: str Genie space ID @@ -2817,26 +2828,21 @@ def execute_message_query( def generate_download_full_query_result( self, space_id: str, conversation_id: str, message_id: str, attachment_id: str ) -> GenieGenerateDownloadFullQueryResultResponse: - """Initiates a new SQL execution and returns a `download_id` and `download_id_signature` that you can use - to track the progress of the download. The query result is stored in an external link and can be - retrieved using the [Get Download Full Query Result](:method:genie/getdownloadfullqueryresult) API. - Both `download_id` and `download_id_signature` must be provided when calling the Get endpoint. + """Initiates a new SQL execution and returns a ``download_id`` and ``download_id_signature`` that you can + use to track the progress of the download. The query result is stored in an external link and can be + retrieved using the Get Download Full Query Result API. Both ``download_id`` and + ``download_id_signature`` must be provided when calling the Get endpoint. - ---- + ****Warning: Databricks strongly recommends that you protect the URLs that are returned by the ``EXTERNAL_LINKS`` disposition.**** - ### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the - `EXTERNAL_LINKS` disposition.** - - When you use the `EXTERNAL_LINKS` disposition, a short-lived, URL is generated, which can be used to + When you use the ``EXTERNAL_LINKS`` disposition, a short-lived, URL is generated, which can be used to download the results directly from . As a short-lived is embedded in this URL, you should protect the URL. - Because URLs are already generated with embedded temporary s, you must not set an `Authorization` + Because URLs are already generated with embedded temporary s, you must not set an ``Authorization`` header in the download requests. - See [Execute Statement](:method:statementexecution/executestatement) for more details. - - ---- + See Execute Statement for more details. :param space_id: str Genie space ID @@ -3017,27 +3023,22 @@ def get_download_full_query_result( download_id: str, download_id_signature: str, ) -> GenieGetDownloadFullQueryResultResponse: - """After [Generating a Full Query Result Download](:method:genie/generatedownloadfullqueryresult) and - successfully receiving a `download_id` and `download_id_signature`, use this API to poll the download - progress. Both `download_id` and `download_id_signature` are required to call this endpoint. When the - download is complete, the API returns the result in the `EXTERNAL_LINKS` disposition, containing one - or more external links to the query result files. + """After Generating a Full Query Result Download and successfully receiving a ``download_id`` and + ``download_id_signature``, use this API to poll the download progress. Both ``download_id`` and + ``download_id_signature`` are required to call this endpoint. When the download is complete, the API + returns the result in the ``EXTERNAL_LINKS`` disposition, containing one or more external links to the + query result files. - ---- + ****Warning: Databricks strongly recommends that you protect the URLs that are returned by the ``EXTERNAL_LINKS`` disposition.**** - ### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the - `EXTERNAL_LINKS` disposition.** - - When you use the `EXTERNAL_LINKS` disposition, a short-lived, URL is generated, which can be used to + When you use the ``EXTERNAL_LINKS`` disposition, a short-lived, URL is generated, which can be used to download the results directly from . As a short-lived is embedded in this URL, you should protect the URL. - Because URLs are already generated with embedded temporary s, you must not set an `Authorization` + Because URLs are already generated with embedded temporary s, you must not set an ``Authorization`` header in the download requests. - See [Execute Statement](:method:statementexecution/executestatement) for more details. - - ---- + See Execute Statement for more details. :param space_id: str Genie space ID @@ -3048,8 +3049,7 @@ def get_download_full_query_result( :param attachment_id: str Attachment ID :param download_id: str - Download ID. This ID is provided by the [Generate Download - endpoint](:method:genie/generateDownloadFullQueryResult) + Download ID. This ID is provided by the Generate Download endpoint :param download_id_signature: str JWT signature for the download_id to ensure secure access to query results @@ -3107,7 +3107,7 @@ def get_message_attachment_query_result( self, space_id: str, conversation_id: str, message_id: str, attachment_id: str ) -> 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` OR `COMPLETED`. + has a query attachment and the message status is ``EXECUTING_QUERY`` OR ``COMPLETED``. :param space_id: str Genie space ID @@ -3139,8 +3139,7 @@ def get_message_attachment_query_result( def get_message_query_result( self, space_id: str, conversation_id: str, message_id: str ) -> GenieGetMessageQueryResultResponse: - """DEPRECATED: Use [Get Message Attachment Query Result](:method:genie/getmessageattachmentqueryresult) - instead. + """DEPRECATED: Use Get Message Attachment Query Result instead. :param space_id: str Genie space ID @@ -3170,8 +3169,7 @@ def get_message_query_result( def get_message_query_result_by_attachment( self, space_id: str, conversation_id: str, message_id: str, attachment_id: str ) -> GenieGetMessageQueryResultResponse: - """DEPRECATED: Use [Get Message Attachment Query Result](:method:genie/getmessageattachmentqueryresult) - instead. + """DEPRECATED: Use Get Message Attachment Query Result instead. :param space_id: str Genie space ID @@ -3545,10 +3543,9 @@ def update_space( :param parent_path: str (optional) Parent workspace folder path to move this Genie space under. :param serialized_space: str (optional) - The contents of the Genie Space in serialized string form (full replacement). Use the [Get Genie - Space](:method:genie/getspace) API to retrieve an example response, which includes the - `serialized_space` field. This field provides the structure of the JSON string that represents the - space's layout and components. + The contents of the Genie Space in serialized string form (full replacement). Use the Get Genie + Space API to retrieve an example response, which includes the ``serialized_space`` field. This field + provides the structure of the JSON string that represents the space's layout and components. :param title: str (optional) Optional title override :param warehouse_id: str (optional) @@ -3856,13 +3853,13 @@ def list( :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. + 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. + ``DASHBOARD_VIEW_BASIC``only includes summary metadata from the dashboard. :returns: Iterator over :class:`Dashboard` """ @@ -3903,7 +3900,7 @@ def list_schedules( :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 + A page token, received from a previous ``ListSchedules`` call. Use this to retrieve the subsequent page. :returns: Iterator over :class:`Schedule` @@ -3945,8 +3942,8 @@ def list_subscriptions( :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. + A page token, received from a previous ``ListSubscriptions`` call. Use this to retrieve the + subsequent page. :returns: Iterator over :class:`Subscription` """ @@ -4062,7 +4059,8 @@ def revert(self, dashboard_id: str, *, etag: Optional[str] = None) -> RevertDash UUID identifying the dashboard. :param etag: str (optional) The etag for the dashboard. Optionally, it can be provided to verify that the dashboard has not been - modified from its last retrieval. + modified from its last retrieval. TODO(TSE-3937): update to new non-CMK-encrypted label when + available :returns: :class:`RevertDashboardResponse` """ diff --git a/databricks/sdk/service/dataclassification.py b/databricks/sdk/service/dataclassification.py index 32ba6e41e..f1bbba866 100755 --- a/databricks/sdk/service/dataclassification.py +++ b/databricks/sdk/service/dataclassification.py @@ -72,9 +72,10 @@ class AutoTaggingConfigAutoTaggingMode(Enum): @dataclass class CatalogConfig: """Data Classification configuration for a Unity Catalog catalog. This message follows the "At Most - One Resource" pattern: at most one CatalogConfig exists per catalog. - Full CRUD operations are - supported: Create enables Data Classification, Delete disables it - It has no unique identifier - of its own and uses its parent catalog's identifier (catalog_name)""" + One Resource" pattern: at most one CatalogConfig exists per catalog. + + - Full CRUD operations are supported: Create enables Data Classification, Delete disables it + - It has no unique identifier of its own and uses its parent catalog's identifier (catalog_name)""" auto_tag_configs: Optional[List[AutoTaggingConfig]] = None """List of auto-tagging configurations for this catalog. Empty list means no auto-tagging is @@ -82,7 +83,7 @@ class CatalogConfig: included_schemas: Optional[CatalogConfigSchemaNames] = None """Schemas to include in the scan. Empty list is not supported as it results in a no-op scan. If - `included_schemas` is not set, all schemas are scanned.""" + ``included_schemas`` is not set, all schemas are scanned.""" name: Optional[str] = None """Resource name in the format: catalogs/{catalog_name}/config.""" @@ -156,8 +157,9 @@ def __init__(self, api_client): def create_catalog_config(self, parent: str, catalog_config: CatalogConfig) -> CatalogConfig: """Create Data Classification configuration for a catalog. - Creates a new config resource, which enables Data Classification for the specified catalog. - The - config must not already exist for the catalog. + Creates a new config resource, which enables Data Classification for the specified catalog. + + - The config must not already exist for the catalog. :param parent: str Parent resource in the format: catalogs/{catalog_name} @@ -221,9 +223,11 @@ def get_catalog_config(self, name: str) -> CatalogConfig: return CatalogConfig.from_dict(res) def update_catalog_config(self, name: str, catalog_config: CatalogConfig, update_mask: FieldMask) -> CatalogConfig: - """Update the Data Classification configuration for a catalog. - The config must already exist for the - catalog. - Updates fields specified in the update_mask. Use update_mask field to perform partial - updates of the configuration. + """Update the Data Classification configuration for a catalog. + + - The config must already exist for the catalog. + - Updates fields specified in the update_mask. Use update_mask field to perform partial updates of the + configuration. :param name: str Resource name in the format: catalogs/{catalog_name}/config. diff --git a/databricks/sdk/service/dataquality.py b/databricks/sdk/service/dataquality.py index 4b1d26912..625b3e363 100644 --- a/databricks/sdk/service/dataquality.py +++ b/databricks/sdk/service/dataquality.py @@ -97,14 +97,14 @@ class CronSchedule: """The data quality monitoring workflow cron schedule.""" quartz_cron_expression: str - """The expression that determines when to run the monitor. See [examples]. - - [examples]: https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html""" + """The expression that determines when to run the monitor. See `examples + `__.""" timezone_id: str """A Java timezone id. The schedule for a job will be resolved with respect to this timezone. See - `Java TimeZone `_ for details. - The timezone id (e.g., ``America/Los_Angeles``) in which to evaluate the quartz expression.""" + ``Java TimeZone ``_ for + details. The timezone id (e.g., ``America/Los_Angeles``) in which to evaluate the quartz + expression.""" pause_status: Optional[CronSchedulePauseStatus] = None """Read only field that indicates whether the schedule is paused or not.""" @@ -161,7 +161,7 @@ class DataProfilingConfig: baseline_table_name: Optional[str] = None """Baseline table name. Baseline data is used to compute drift from the data in the monitored - `table_name`. The baseline table and the monitored table shall have the same schema.""" + ``table_name``. The baseline table and the monitored table shall have the same schema.""" custom_metrics: Optional[List[DataProfilingCustomMetric]] = None """Custom metrics.""" @@ -171,13 +171,13 @@ class DataProfilingConfig: PENDING state.""" drift_metrics_table_name: Optional[str] = None - """Table that stores drift metrics data. Format: `catalog.schema.table_name`.""" + """Table that stores drift metrics data. Format: ``catalog.schema.table_name``.""" effective_warehouse_id: Optional[str] = None """The warehouse for dashboard creation""" inference_log: Optional[InferenceLogConfig] = None - """`Analysis Configuration` for monitoring inference log tables.""" + """``Analysis Configuration`` for monitoring inference log tables.""" latest_monitor_failure_message: Optional[str] = None """The latest error message for a monitor failure.""" @@ -188,13 +188,13 @@ class DataProfilingConfig: indicate corrupted monitor_version numbers.""" monitored_table_name: Optional[str] = None - """Unity Catalog table to monitor. Format: `catalog.schema.table_name`""" + """Unity Catalog table to monitor. Format: ``catalog.schema.table_name``""" notification_settings: Optional[NotificationSettings] = None """Field for specifying notification settings.""" profile_metrics_table_name: Optional[str] = None - """Table that stores profile metrics data. Format: `catalog.schema.table_name`.""" + """Table that stores profile metrics data. Format: ``catalog.schema.table_name``.""" schedule: Optional[CronSchedule] = None """The cron schedule.""" @@ -205,18 +205,19 @@ class DataProfilingConfig: slicing_exprs: Optional[List[str]] = None """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 example `slicing_exprs=[“col_1”, “col_2 > 10”]` will generate the following slices: - two slices for `col_2 > 10` (True and False), and one slice per unique value in `col1`. For - high-cardinality columns, only the top 100 unique values by frequency will generate slices.""" + For example ``slicing_exprs=[“col_1”, “col_2 > 10”]`` will generate the following + slices: two slices for ``col_2 > 10`` (True and False), and one slice per unique value in + ``col1``. For high-cardinality columns, only the top 100 unique values by frequency will + generate slices.""" snapshot: Optional[SnapshotConfig] = None - """`Analysis Configuration` for monitoring snapshot tables.""" + """``Analysis Configuration`` for monitoring snapshot tables.""" status: Optional[DataProfilingStatus] = None """The data profiling monitor status.""" time_series: Optional[TimeSeriesConfig] = None - """`Analysis Configuration` for monitoring time series tables.""" + """``Analysis Configuration`` for monitoring time series tables.""" warehouse_id: Optional[str] = None """Optional argument to specify the warehouse for dashboard creation. If not specified, the first @@ -347,10 +348,9 @@ class DataProfilingCustomMetric: """Name of the metric in the output tables.""" definition: str - """Jinja template for a SQL expression that specifies how to compute the metric. See [create metric - definition]. - - [create metric definition]: https://docs.databricks.com/en/lakehouse-monitoring/custom-metrics.html#create-definition""" + """Jinja template for a SQL expression that specifies how to compute the metric. See `create metric + definition + `__.""" input_columns: List[str] """A list of column names in the input table the metric should be computed for. Can use @@ -567,27 +567,32 @@ class Monitor: """Monitor for the data quality of unity catalog entities such as schema or table.""" object_type: str - """The type of the monitored object. Can be one of the following: `schema` or `table`.""" + """The type of the monitored object. Can be one of the following: ``schema`` or ``table``.""" object_id: str - """The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + """The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for + ``table``. - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + Find the ``schema_id`` from either: - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id""" + Find the ``table_id`` from either: + + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field.""" anomaly_detection_config: Optional[AnomalyDetectionConfig] = None - """Anomaly Detection Configuration, applicable to `schema` object types.""" + """Anomaly Detection Configuration, applicable to ``schema`` object types.""" data_profiling_config: Optional[DataProfilingConfig] = None - """Data Profiling Configuration, applicable to `table` object types. Exactly one `Analysis - Configuration` must be present.""" + """Data Profiling Configuration, applicable to ``table`` object types. Exactly one ``Analysis + Configuration`` must be present.""" def as_dict(self) -> dict: """Serializes the Monitor into a dictionary suitable for use as a JSON request body.""" @@ -686,20 +691,25 @@ class Refresh: """The Refresh object gives information on a refresh of the data quality monitoring pipeline.""" object_type: str - """The type of the monitored object. Can be one of the following: `schema`or `table`.""" + """The type of the monitored object. Can be one of the following: ``schema``or ``table``.""" object_id: str - """The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + """The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for + ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id""" + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field.""" end_time_ms: Optional[int] = None """Time when the refresh ended (milliseconds since 1/1/1970 UTC).""" @@ -855,34 +865,41 @@ def from_dict(cls, d: Dict[str, Any]) -> TimeSeriesConfig: class DataQualityAPI: - """Manage the data quality of Unity Catalog objects (currently support `schema` and `table`)""" + """Manage the data quality of Unity Catalog objects (currently support ``schema`` and ``table``)""" def __init__(self, api_client): self._api = api_client def cancel_refresh(self, object_type: str, object_id: str, refresh_id: int) -> CancelRefreshResponse: - """Cancels a data quality monitor refresh. Currently only supported for the `table` `object_type`. The - call must be made in the same workspace as where the monitor was created. + """Cancels a data quality monitor refresh. Currently only supported for the ``table`` ``object_type``. + The call must be made in the same workspace as where the monitor was created. - The caller must have either of the following sets of permissions: 1. **MANAGE** and **USE_CATALOG** on - the table's parent catalog. 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and - **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the table's parent catalog, - **USE_SCHEMA** on the table's parent schema, and **MANAGE** on the table. + The caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **MANAGE** on the table. :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param refresh_id: int Unique id of the refresh operation. @@ -907,20 +924,23 @@ def cancel_refresh(self, object_type: str, object_id: str, refresh_id: int) -> C def create_monitor(self, monitor: Monitor) -> Monitor: """Create a data quality monitor on a Unity Catalog object. The caller must provide either - `anomaly_detection_config` for a schema monitor or `data_profiling_config` for a table monitor. + ``anomaly_detection_config`` for a schema monitor or ``data_profiling_config`` for a table monitor. + + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: - For the `table` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent - schema, and **SELECT** on the table 2. **USE_CATALOG** on the table's parent catalog, **MANAGE** and - **USE_SCHEMA** on the table's parent schema, and **SELECT** on the table. 3. **USE_CATALOG** on the - table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **MANAGE** and **SELECT** on - the table. + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent + schema, and **SELECT** on the table + 2. **USE_CATALOG** on the table's parent catalog, **MANAGE** and **USE_SCHEMA** on the table's parent + schema, and **SELECT** on the table. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **MANAGE** and **SELECT** on the table. Workspace assets, such as the dashboard, will be created in the workspace where this call was made. - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. :param monitor: :class:`Monitor` The monitor to create. @@ -943,28 +963,35 @@ def create_monitor(self, monitor: Monitor) -> Monitor: return Monitor.from_dict(res) def create_refresh(self, object_type: str, object_id: str, refresh: Refresh) -> Refresh: - """Creates a refresh. Currently only supported for the `table` `object_type`. The call must be made in - the same workspace as where the monitor was created. + """Creates a refresh. Currently only supported for the ``table`` ``object_type``. The call must be made + in the same workspace as where the monitor was created. + + The caller must have either of the following sets of permissions: - The caller must have either of the following sets of permissions: 1. **MANAGE** and **USE_CATALOG** on - the table's parent catalog. 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and - **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the table's parent catalog, - **USE_SCHEMA** on the table's parent schema, and **MANAGE** on the table. + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **MANAGE** on the table. :param object_type: str - The type of the monitored object. Can be one of the following: `schema`or `table`. + The type of the monitored object. Can be one of the following: ``schema``or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + Find the ``schema_id`` from either: - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + Find the ``table_id`` from either: + + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param refresh: :class:`Refresh` The refresh to create @@ -990,7 +1017,7 @@ def create_refresh(self, object_type: str, object_id: str, refresh: Refresh) -> def delete_monitor(self, object_type: str, object_id: str): """Delete a data quality monitor on Unity Catalog object. - For the `table` `object_type`, the caller must have either of the following sets of permissions: + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: **MANAGE** and **USE_CATALOG** on the table's parent catalog. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's parent schema. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **MANAGE** on the table. @@ -998,24 +1025,29 @@ def delete_monitor(self, object_type: str, object_id: str): 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). - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + Find the ``schema_id`` from either: - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + Find the ``table_id`` from either: + + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. """ @@ -1034,19 +1066,23 @@ def delete_refresh(self, object_type: str, object_id: str, refresh_id: int): """(Unimplemented) Delete a refresh :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param refresh_id: int Unique id of the refresh operation. @@ -1068,33 +1104,41 @@ def delete_refresh(self, object_type: str, object_id: str, refresh_id: int): def get_monitor(self, object_type: str, object_id: str) -> Monitor: """Read a data quality monitor on a Unity Catalog object. - For the `table` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the table's parent catalog. 2. **USE_CATALOG** on the table's parent - catalog, and **MANAGE** and **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the - table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **SELECT** on the table. + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **SELECT** on the table. - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **USE_SCHEMA** on the schema. + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **USE_SCHEMA** on the schema. The returned information includes configuration values on the entity and parent entity 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 object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :returns: :class:`Monitor` """ @@ -1114,29 +1158,37 @@ def get_refresh(self, object_type: str, object_id: str, refresh_id: int) -> Refr """Get data quality monitor refresh. The call must be made in the same workspace as where the monitor was created. - For the `table` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the table's parent catalog. 2. **USE_CATALOG** on the table's parent - catalog, and **MANAGE** and **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the - table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **SELECT** on the table. + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **SELECT** on the table. + + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **USE_SCHEMA** on the schema. + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **USE_SCHEMA** on the schema. :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + Find the ``schema_id`` from either: - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + Find the ``table_id`` from either: + + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param refresh_id: int Unique id of the refresh operation. @@ -1193,29 +1245,37 @@ def list_refresh( """List data quality monitor refreshes. The call must be made in the same workspace as where the monitor was created. - For the `table` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the table's parent catalog. 2. **USE_CATALOG** on the table's parent - catalog, and **MANAGE** and **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the - table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **SELECT** on the table. + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **SELECT** on the table. + + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **USE_SCHEMA** on the schema. + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **USE_SCHEMA** on the schema. :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + Find the ``schema_id`` from either: - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + Find the ``table_id`` from either: + + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param page_size: int (optional) :param page_token: str (optional) @@ -1252,34 +1312,42 @@ def list_refresh( def update_monitor(self, object_type: str, object_id: str, monitor: Monitor, update_mask: str) -> Monitor: """Update a data quality monitor on Unity Catalog object. - For the `table` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the table's parent catalog. 2. **USE_CATALOG** on the table's parent - catalog, and **MANAGE** and **USE_SCHEMA** on the table's parent schema. 3. **USE_CATALOG** on the - table's parent catalog, **USE_SCHEMA** on the table's parent schema, and **MANAGE** on the table. + For the ``table`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the table's parent catalog. + 2. **USE_CATALOG** on the table's parent catalog, and **MANAGE** and **USE_SCHEMA** on the table's + parent schema. + 3. **USE_CATALOG** on the table's parent catalog, **USE_SCHEMA** on the table's parent schema, and + **MANAGE** on the table. - For the `schema` `object_type`, the caller must have either of the following sets of permissions: 1. - **MANAGE** and **USE_CATALOG** on the schema's parent catalog. 2. **USE_CATALOG** on the schema's - parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. + For the ``schema`` ``object_type``, the caller must have either of the following sets of permissions: + + 1. **MANAGE** and **USE_CATALOG** on the schema's parent catalog. + 2. **USE_CATALOG** on the schema's parent catalog, and **MANAGE** and **USE_SCHEMA** on the schema. :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param monitor: :class:`Monitor` The monitor to update. :param update_mask: str The field mask to specify which fields to update as a comma-separated list. Example value: - `data_profiling_config.custom_metrics,data_profiling_config.schedule.quartz_cron_expression` + ``data_profiling_config.custom_metrics,data_profiling_config.schedule.quartz_cron_expression`` :returns: :class:`Monitor` """ @@ -1308,19 +1376,23 @@ def update_refresh( """(Unimplemented) Update a refresh :param object_type: str - The type of the monitored object. Can be one of the following: `schema` or `table`. + The type of the monitored object. Can be one of the following: ``schema`` or ``table``. :param object_id: str - The UUID of the request object. It is `schema_id` for `schema`, and `table_id` for `table`. + The UUID of the request object. It is ``schema_id`` for ``schema``, and ``table_id`` for ``table``. + + Find the ``schema_id`` from either: - Find the `schema_id` from either: 1. The [schema_id] of the `Schemas` resource. 2. In [Catalog - Explorer] > select the `schema` > go to the `Details` tab > the `Schema ID` field. + 1. The `schema_id `__ of the + ``Schemas`` resource. + 2. In `Catalog Explorer `__ > select the + ``schema`` > go to the ``Details`` tab > the ``Schema ID`` field. - Find the `table_id` from either: 1. The [table_id] of the `Tables` resource. 2. In [Catalog - Explorer] > select the `table` > go to the `Details` tab > the `Table ID` field. + Find the ``table_id`` from either: - [Catalog Explorer]: https://docs.databricks.com/aws/en/catalog-explorer/ - [schema_id]: https://docs.databricks.com/api/workspace/schemas/get#schema_id - [table_id]: https://docs.databricks.com/api/workspace/tables/get#table_id + 1. The `table_id `__ of the + ``Tables`` resource. + 2. In `Catalog Explorer `__ > select the + ``table`` > go to the ``Details`` tab > the ``Table ID`` field. :param refresh_id: int Unique id of the refresh operation. :param refresh: :class:`Refresh` diff --git a/databricks/sdk/service/disasterrecovery.py b/databricks/sdk/service/disasterrecovery.py index b688d018e..4d1a55c7a 100755 --- a/databricks/sdk/service/disasterrecovery.py +++ b/databricks/sdk/service/disasterrecovery.py @@ -315,7 +315,7 @@ class StableUrl: failover_group_name: Optional[str] = None """Fully qualified resource name of the FailoverGroup this stable URL is currently linked to, in - the format `accounts/{account_id}/failover-groups/{failover_group_id}`. Empty when the stable + the format ``accounts/{account_id}/failover-groups/{failover_group_id}``. Empty when the stable URL is not attached to any failover group.""" name: Optional[str] = None @@ -323,8 +323,8 @@ class StableUrl: url: Optional[str] = None """The stable URL endpoint. Generated on creation and immutable thereafter. For non-Private-Link - workspaces this is `https:///?c=`. For Private-Link workspaces this is - the per-connection hostname.""" + workspaces this is ``https:///?c=``. For Private-Link workspaces this + is the per-connection hostname.""" def as_dict(self) -> dict: """Serializes the StableUrl into a dictionary suitable for use as a JSON request body.""" @@ -686,16 +686,18 @@ def list_failover_groups( ) -> Iterator[FailoverGroup]: """List failover groups. - List entries are abbreviated: `state` and `replication_point` are not populated. Call GetFailoverGroup - to retrieve the full resource. + List entries are abbreviated: ``state`` and ``replication_point`` are not populated. Call + GetFailoverGroup to retrieve the full resource. :param parent: str The parent resource. Format: accounts/{account_id}. :param page_size: int (optional) - Maximum number of failover groups to return per page: - 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 or unset, 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. + Maximum number of failover groups to return per page: + + - 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 or unset, 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) Page token received from a previous ListFailoverGroups call. Provide this to retrieve the subsequent page. @@ -731,10 +733,12 @@ def list_stable_urls( :param parent: str The parent resource. Format: accounts/{account_id}. :param page_size: int (optional) - Maximum number of stable URLs to return per page: - 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 or unset, 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. + Maximum number of stable URLs to return per page: + + - 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 or unset, 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) Page token received from a previous ListStableUrls call. Provide this to retrieve the subsequent page. diff --git a/databricks/sdk/service/environments.py b/databricks/sdk/service/environments.py index 7854c0137..30e169e1e 100755 --- a/databricks/sdk/service/environments.py +++ b/databricks/sdk/service/environments.py @@ -262,8 +262,8 @@ class Operation: """This resource represents a long-running operation that is the result of a network API call.""" done: Optional[bool] = None - """If the value is `false`, it means the operation is still in progress. If `true`, the operation - is completed, and either `error` or `response` is available.""" + """If the value is ``false``, it means the operation is still in progress. If ``true``, the + operation is completed, and either ``error`` or ``response`` is available.""" error: Optional[DatabricksServiceExceptionWithDetailsProto] = None """The error result of the operation in case of failure or cancellation.""" @@ -275,8 +275,8 @@ class Operation: name: Optional[str] = None """The server-assigned name, which is only unique within the same service that originally returns - it. If you use the default HTTP mapping, the `name` should be a resource name ending with - `operations/{unique_id}`.""" + it. If you use the default HTTP mapping, the ``name`` should be a resource name ending with + ``operations/{unique_id}``.""" response: Optional[dict] = None """The normal, successful response of the operation.""" @@ -614,15 +614,14 @@ def list_workspace_base_environments( Databricks provides the following base environments: - - `workspace-base-environments/databricks_ai_...`: includes popular AI and deep learning packages for - serverless GPU compute. - - - `workspace-base-environments/databricks_ml_...`: includes popular ML packages for serverless - compute. + - ``workspace-base-environments/databricks_ai_...``: includes popular AI and deep learning packages + for serverless GPU compute. + - ``workspace-base-environments/databricks_ml_...``: includes popular ML packages for serverless + compute. Databricks-provided base environments are versioned. For example, - `workspace-base-environments/databricks_ml_v5` corresponds to the ML environment built on environment - version 5. + ``workspace-base-environments/databricks_ml_v5`` corresponds to the ML environment built on + environment version 5. :param page_size: int (optional) The maximum number of environments to return per page. Default is 1000. diff --git a/databricks/sdk/service/files.py b/databricks/sdk/service/files.py index fcc6ba07b..814ac94b6 100755 --- a/databricks/sdk/service/files.py +++ b/databricks/sdk/service/files.py @@ -307,7 +307,7 @@ class ListDirectoryResponse: """Array of DirectoryEntry.""" next_page_token: Optional[str] = None - """A token, which can be sent as `page_token` to retrieve the next page.""" + """A token, which can be sent as ``page_token`` to retrieve the next page.""" def as_dict(self) -> dict: """Serializes the ListDirectoryResponse into a dictionary suitable for use as a JSON request body.""" @@ -510,13 +510,14 @@ def close(self, handle: int): def create(self, path: str, *, overwrite: Optional[bool] = None) -> 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 + 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. + 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. @@ -545,19 +546,18 @@ def create(self, path: str, *, overwrite: Optional[bool] = None) -> CreateRespon def delete(self, path: str, *, recursive: Optional[bool] = None): """Delete the file or directory (optionally recursively delete all files in the directory). This call - throws an exception with `IO_ERROR` if the path is a non-empty directory and `recursive` is set to - `false` or on other similar errors. + throws an exception with ``IO_ERROR`` if the path is a non-empty directory and ``recursive`` is set to + ``false`` or on other similar errors. When you delete a large number of files, the delete operation is done in increments. The call returns a response after approximately 45 seconds with an error message (503 Service Unavailable) asking you to re-invoke the delete operation until the directory structure is fully deleted. For operations that delete more than 10K files, we discourage using the DBFS REST API, but advise you - to perform such operations in the context of a cluster, using the [File system utility - (dbutils.fs)](/dev-tools/databricks-utils.html#dbutils-fs). `dbutils.fs` covers the functional scope - of the DBFS REST API, but from notebooks. Running such operations using notebooks provides better - control and manageability, such as selective deletes, and the possibility to automate periodic delete - jobs. + to perform such operations in the context of a cluster, using the File system utility (dbutils.fs). + ``dbutils.fs`` covers the functional scope of the DBFS REST API, but from notebooks. Running such + operations using notebooks provides better control and manageability, such as selective deletes, and + the possibility to automate periodic delete jobs. :param path: str The path of the file or directory to delete. The path should be the absolute DBFS path. @@ -586,7 +586,7 @@ def delete(self, path: str, *, recursive: Optional[bool] = None): def get_status(self, path: str) -> 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`. + 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. @@ -610,14 +610,13 @@ def get_status(self, path: str) -> FileInfo: def list(self, path: str) -> Iterator[FileInfo]: """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`. + 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. We strongly recommend using list only on directories containing less than 10K files and discourage using the DBFS REST API for operations that list more than 10K files. Instead, we recommend - that you perform such operations in the context of a cluster, using the [File system utility - (dbutils.fs)](/dev-tools/databricks-utils.html#dbutils-fs), which provides the same functionality - without timing out. + that you perform such operations in the context of a cluster, using the File system utility + (dbutils.fs), which provides the same functionality without timing out. :param path: str The path of the file or directory. The path should be the absolute DBFS path. @@ -643,8 +642,8 @@ def list(self, path: str) -> Iterator[FileInfo]: def mkdirs(self, path: str): """Creates the given directory and necessary parent directories if they do not exist. If a file (not a directory) exists at any prefix of the input path, this call throws an exception with - `RESOURCE_ALREADY_EXISTS`. **Note**: If this operation fails, it might have succeeded in creating some - of the necessary parent directories. + ``RESOURCE_ALREADY_EXISTS``. **Note**: If this operation fails, it might have succeeded in creating + some of the necessary parent directories. :param path: str The path of the new directory. The path should be the absolute DBFS path. @@ -668,8 +667,8 @@ def mkdirs(self, path: str): def move(self, source_path: str, destination_path: str): """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 + 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 @@ -702,8 +701,8 @@ def put(self, path: str, *, contents: Optional[str] = None, overwrite: Optional[ 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. + 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. @@ -738,11 +737,11 @@ def put(self, path: str, *, contents: Optional[str] = None, overwrite: Optional[ def read(self, path: str, *, length: Optional[int] = None, offset: Optional[int] = None) -> 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`. + ``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 + If ``offset + length`` exceeds the number of bytes in a file, it reads the contents until the end of file. :param path: str @@ -780,24 +779,24 @@ class FilesAPI: 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 + 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. + 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. - Use of Files API may incur Databricks data transfer charges. - - [Unity Catalog volumes]: https://docs.databricks.com/en/connect/unity-catalog/volumes.html""" + Use of Files API may incur Databricks data transfer charges.""" def __init__(self, api_client): self._api = api_client def create_directory(self, directory_path: str): """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 + 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 @@ -893,8 +892,8 @@ def get_directory_metadata(self, directory_path: str): 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). + 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. @@ -950,7 +949,7 @@ def list_directory_contents( 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` + 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 @@ -959,12 +958,12 @@ def list_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. + 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` """ diff --git a/databricks/sdk/service/iam.py b/databricks/sdk/service/iam.py index 5e62590d8..e7f10153a 100755 --- a/databricks/sdk/service/iam.py +++ b/databricks/sdk/service/iam.py @@ -289,7 +289,7 @@ class AccountUser: """If this user is active""" display_name: Optional[str] = None - """String that represents a concatenation of given and family names. For example `John Smith`.""" + """String that represents a concatenation of given and family names. For example ``John Smith``.""" emails: Optional[List[ComplexValue]] = None """All the emails associated with the Databricks user.""" @@ -628,8 +628,11 @@ class GrantRule: principals: Optional[List[str]] = None """Principals this grant rule applies to. A principal can be a user (for end users), a service principal (for applications and compute workloads), or an account group. Each principal has its - own identifier format: * users/ * groups/ * - servicePrincipals/""" + own identifier format: + + - users/ + - groups/ + - servicePrincipals/""" def as_dict(self) -> dict: """Serializes the GrantRule into a dictionary suitable for use as a JSON request body.""" @@ -661,10 +664,9 @@ class Group: """String that represents a human-readable group name""" entitlements: Optional[List[ComplexValue]] = None - """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""" + """Entitlements assigned to the group. See `assigning entitlements + `__ + for a full list of supported values.""" external_id: Optional[str] = None """external_id should be unique for identifying groups""" @@ -1785,8 +1787,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ResourceInfo: @dataclass class ResourceMeta: resource_type: Optional[str] = None - """Identifier for group type. Can be local workspace group (`WorkspaceGroup`) or account group - (`Group`).""" + """Identifier for group type. Can be local workspace group (``WorkspaceGroup``) or account group + (``Group``).""" def as_dict(self) -> dict: """Serializes the ResourceMeta into a dictionary suitable for use as a JSON request body.""" @@ -1937,10 +1939,9 @@ class ServicePrincipal: """String that represents a concatenation of given and family names.""" entitlements: Optional[List[ComplexValue]] = None - """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""" + """Entitlements assigned to the service principal. See `assigning entitlements + `__ + for a full list of supported values.""" external_id: Optional[str] = None @@ -2027,20 +2028,19 @@ class User: """If this user is active""" display_name: Optional[str] = None - """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""" + """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``.""" emails: Optional[List[ComplexValue]] = None """All the emails associated with the Databricks user.""" entitlements: Optional[List[ComplexValue]] = None - """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""" + """Entitlements assigned to the user. See `assigning entitlements + `__ + for a full list of supported values.""" external_id: Optional[str] = None """External ID is not currently supported. It is reserved for future use.""" @@ -2241,10 +2241,10 @@ def get_assignable_roles_for_resource(self, resource: str) -> GetAssignableRoles :param resource: str The resource name for which assignable roles will be listed. - Examples | Summary :--- | :--- `resource=accounts/` | A resource name for the account. - `resource=accounts//groups/` | A resource name for the group. - `resource=accounts//servicePrincipals/` | A resource name for the service - principal. `resource=accounts//tagPolicies/` | A resource name for the + Examples | Summary :--- | :--- ``resource=accounts/`` | A resource name for the account. + ``resource=accounts//groups/`` | A resource name for the group. + ``resource=accounts//servicePrincipals/`` | A resource name for the service + principal. ``resource=accounts//tagPolicies/`` | A resource name for the tag policy. :returns: :class:`GetAssignableRolesForResourceResponse` @@ -2272,13 +2272,13 @@ def get_rule_set(self, name: str, etag: str) -> RuleSetResponse: :param name: str The ruleset name associated with the request. - Examples | Summary :--- | :--- `name=accounts//ruleSets/default` | A name for a rule set - on the account. `name=accounts//groups//ruleSets/default` | A name for a rule - set on the group. - `name=accounts//servicePrincipals//ruleSets/default` | - A name for a rule set on the service principal. - `name=accounts//tagPolicies//ruleSets/default` | A name for a rule set on - the tag policy. + Examples | Summary :--- | :--- ``name=accounts//ruleSets/default`` | A name for a rule + set on the account. ``name=accounts//groups//ruleSets/default`` | A name for a + rule set on the group. + ``name=accounts//servicePrincipals//ruleSets/default`` + | A name for a rule set on the service principal. + ``name=accounts//tagPolicies//ruleSets/default`` | A name for a rule set + on the tag policy. :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 @@ -2287,8 +2287,8 @@ def get_rule_set(self, name: str, etag: str) -> RuleSetResponse: etag from a GET rule set request, and pass it with the PUT update request to identify the rule set version you are updating. - Examples | Summary :--- | :--- `etag=` | An empty etag can only be used in GET to indicate no - freshness requirements. `etag=RENUAAABhSweA4NvVmmUYdiU717H3Tgy0UJdor3gE4a+mq/oj9NjAf8ZsQ==` | An + Examples | Summary :--- | :--- ``etag=`` | An empty etag can only be used in GET to indicate no + freshness requirements. ``etag=RENUAAABhSweA4NvVmmUYdiU717H3Tgy0UJdor3gE4a+mq/oj9NjAf8ZsQ==`` | An etag encoded a specific version of the rule set to get or to be updated. :returns: :class:`RuleSetResponse` @@ -2356,10 +2356,10 @@ def get_assignable_roles_for_resource(self, resource: str) -> GetAssignableRoles :param resource: str The resource name for which assignable roles will be listed. - Examples | Summary :--- | :--- `resource=accounts/` | A resource name for the account. - `resource=accounts//groups/` | A resource name for the group. - `resource=accounts//servicePrincipals/` | A resource name for the service - principal. `resource=accounts//tagPolicies/` | A resource name for the + Examples | Summary :--- | :--- ``resource=accounts/`` | A resource name for the account. + ``resource=accounts//groups/`` | A resource name for the group. + ``resource=accounts//servicePrincipals/`` | A resource name for the service + principal. ``resource=accounts//tagPolicies/`` | A resource name for the tag policy. :returns: :class:`GetAssignableRolesForResourceResponse` @@ -2388,13 +2388,13 @@ def get_rule_set(self, name: str, etag: str) -> RuleSetResponse: :param name: str The ruleset name associated with the request. - Examples | Summary :--- | :--- `name=accounts//ruleSets/default` | A name for a rule set - on the account. `name=accounts//groups//ruleSets/default` | A name for a rule - set on the group. - `name=accounts//servicePrincipals//ruleSets/default` | - A name for a rule set on the service principal. - `name=accounts//tagPolicies//ruleSets/default` | A name for a rule set on - the tag policy. + Examples | Summary :--- | :--- ``name=accounts//ruleSets/default`` | A name for a rule + set on the account. ``name=accounts//groups//ruleSets/default`` | A name for a + rule set on the group. + ``name=accounts//servicePrincipals//ruleSets/default`` + | A name for a rule set on the service principal. + ``name=accounts//tagPolicies//ruleSets/default`` | A name for a rule set + on the tag policy. :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 @@ -2403,8 +2403,8 @@ def get_rule_set(self, name: str, etag: str) -> RuleSetResponse: etag from a GET rule set request, and pass it with the PUT update request to identify the rule set version you are updating. - Examples | Summary :--- | :--- `etag=` | An empty etag can only be used in GET to indicate no - freshness requirements. `etag=RENUAAABhSweA4NvVmmUYdiU717H3Tgy0UJdor3gE4a+mq/oj9NjAf8ZsQ==` | An + Examples | Summary :--- | :--- ``etag=`` | An empty etag can only be used in GET to indicate no + freshness requirements. ``etag=RENUAAABhSweA4NvVmmUYdiU717H3Tgy0UJdor3gE4a+mq/oj9NjAf8ZsQ==`` | An etag encoded a specific version of the rule set to get or to be updated. :returns: :class:`RuleSetResponse` @@ -2556,8 +2556,8 @@ def list( start_index: Optional[int] = None, ) -> Iterator[AccountGroup]: """Gets all details of the groups associated with the Databricks account. As of 08/22/2025, this endpoint - will no longer return members. Instead, members should be retrieved by iterating through `Get group - details`. Existing accounts that rely on this attribute will not be impacted and will continue + will no longer return members. Instead, members should be retrieved by iterating through ``Get group + details``. Existing accounts that rely on this attribute will not be impacted and will continue receiving member data as before. :param attributes: str (optional) @@ -2567,12 +2567,11 @@ def list( :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 + 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. :param sort_by: str (optional) Attribute to sort the results. :param sort_order: :class:`ListSortOrder` (optional) @@ -2799,12 +2798,11 @@ def list( :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 + 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. :param sort_by: str (optional) Attribute to sort the results. :param sort_order: :class:`ListSortOrder` (optional) @@ -2965,7 +2963,7 @@ def create( :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`. + String that represents a concatenation of given and family names. For example ``John Smith``. :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param external_id: str (optional) @@ -3045,15 +3043,14 @@ def get( :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 + 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. :param sort_by: str (optional) - Attribute to sort the results. Multi-part paths are supported. For example, `userName`, - `name.givenName`, and `emails`. + 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) @@ -3106,15 +3103,14 @@ def list( :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 + 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. :param sort_by: str (optional) - Attribute to sort the results. Multi-part paths are supported. For example, `userName`, - `name.givenName`, and `emails`. + 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) @@ -3201,7 +3197,7 @@ def update( :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`. + String that represents a concatenation of given and family names. For example ``John Smith``. :param emails: List[:class:`ComplexValue`] (optional) All the emails associated with the Databricks user. :param external_id: str (optional) @@ -3301,10 +3297,9 @@ def create( :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 + Entitlements assigned to the group. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) :param id: str (optional) @@ -3408,12 +3403,11 @@ def list( :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 + 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. :param sort_by: str (optional) Attribute to sort the results. :param sort_order: :class:`ListSortOrder` (optional) @@ -3507,10 +3501,9 @@ def update( :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 + Entitlements assigned to the group. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) :param members: List[:class:`ComplexValue`] (optional) @@ -3605,27 +3598,27 @@ def migrate_permissions( 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. * **[Spark Declarative Pipelines permissions](:service:pipelines)** — Manage - which users can view, manage, run, cancel, or own a Spark Declarative 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. * **[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** — Manage which users can manage or use apps. + - **Cluster permissions** — Manage which users can manage, restart, or attach to clusters. + - **Cluster policy permissions** — Manage which users can use cluster policies. + - **Spark Declarative Pipelines permissions** — Manage which users can view, manage, run, cancel, or own + a Spark Declarative Pipeline. + - **Job permissions** — Manage which users can view, manage, trigger, cancel, or own a job. + - **MLflow experiment permissions** — Manage which users can read, edit, or manage MLflow experiments. + - **MLflow registered model permissions** — Manage which users can read, edit, or manage MLflow + registered models. + - **Instance Pool permissions** — Manage which users can manage or attach to pools. + - **Repo permissions** — Manage which users can read, run, edit, or manage a repo. + - **Serving endpoint permissions** — Manage which users can view, query, or manage a serving endpoint. + - **SQL warehouse permissions** — Manage which users can use or manage SQL warehouses. + - **Token permissions** — Manage which users can create or use tokens. + - **Workspace object permissions** — 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**.""" def __init__(self, api_client): self._api = api_client @@ -3798,10 +3791,9 @@ def create( :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 + Entitlements assigned to the service principal. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) :param id: str (optional) @@ -3902,12 +3894,11 @@ def list( :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 + 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. :param sort_by: str (optional) Attribute to sort the results. :param sort_order: :class:`ListSortOrder` (optional) @@ -4007,10 +3998,9 @@ def update( :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 + Entitlements assigned to the service principal. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) :param groups: List[:class:`ComplexValue`] (optional) :param roles: List[:class:`ComplexValue`] (optional) @@ -4085,17 +4075,16 @@ def create( :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 + 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``. :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 + Entitlements assigned to the user. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. :param groups: List[:class:`ComplexValue`] (optional) @@ -4188,15 +4177,14 @@ def get( :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 + 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. :param sort_by: str (optional) - Attribute to sort the results. Multi-part paths are supported. For example, `userName`, - `name.givenName`, and `emails`. + 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) @@ -4287,15 +4275,14 @@ def list( :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 + 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. :param sort_by: str (optional) - Attribute to sort the results. Multi-part paths are supported. For example, `userName`, - `name.givenName`, and `emails`. + 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) @@ -4415,17 +4402,16 @@ def update( :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 + 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``. :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 + Entitlements assigned to the user. See `assigning entitlements + `__ + for a full list of supported values. :param external_id: str (optional) External ID is not currently supported. It is reserved for future use. :param groups: List[:class:`ComplexValue`] (optional) diff --git a/databricks/sdk/service/iamv2.py b/databricks/sdk/service/iamv2.py index 560d5db6f..d13f89639 100755 --- a/databricks/sdk/service/iamv2.py +++ b/databricks/sdk/service/iamv2.py @@ -600,10 +600,11 @@ def get_workspace_access_detail( self, workspace_id: int, principal_id: int, *, view: Optional[WorkspaceAccessDetailView] = None ) -> WorkspaceAccessDetail: """Returns the access details for a principal in a workspace. Allows for checking access details for any - provisioned principal (user, service principal, or group) in a workspace. * Provisioned principal here - refers to one that has been synced into Databricks from the customer's IdP or added explicitly to - Databricks via SCIM/UI. Allows for passing in a "view" parameter to control what fields are returned - (BASIC by default or FULL). + provisioned principal (user, service principal, or group) in a workspace. + + - Provisioned principal here refers to one that has been synced into Databricks from the customer's + IdP or added explicitly to Databricks via SCIM/UI. Allows for passing in a "view" parameter to + control what fields are returned (BASIC by default or FULL). :param workspace_id: int Required. The workspace ID for which the access details are being requested. @@ -871,10 +872,11 @@ def get_workspace_access_detail_local( self, principal_id: int, *, view: Optional[WorkspaceAccessDetailView] = None ) -> WorkspaceAccessDetail: """Returns the access details for a principal in the current workspace. Allows for checking access - details for any provisioned principal (user, service principal, or group) in the current workspace. * - Provisioned principal here refers to one that has been synced into Databricks from the customer's IdP - or added explicitly to Databricks via SCIM/UI. Allows for passing in a "view" parameter to control - what fields are returned (BASIC by default or FULL). + details for any provisioned principal (user, service principal, or group) in the current workspace. + + - Provisioned principal here refers to one that has been synced into Databricks from the customer's + IdP or added explicitly to Databricks via SCIM/UI. Allows for passing in a "view" parameter to + control what fields are returned (BASIC by default or FULL). :param principal_id: int Required. The internal ID of the principal (user/sp/group) for which the access details are being diff --git a/databricks/sdk/service/jobs.py b/databricks/sdk/service/jobs.py index 75e4e5782..d00ba845e 100755 --- a/databricks/sdk/service/jobs.py +++ b/databricks/sdk/service/jobs.py @@ -51,9 +51,11 @@ class AlertTask: """The warehouse_id identifies the warehouse settings used by the alert task.""" workspace_path: Optional[str] = None - """The workspace_path is the path to the alert file in the workspace. The path: * must start with - "/Workspace" * must be a normalized path. User has to select only one of alert_id or - workspace_path to identify the alert.""" + """The workspace_path is the path to the alert file in the workspace. The path: + + - must start with "/Workspace" + - must be a normalized path. User has to select only one of alert_id or workspace_path to + identify the alert.""" def as_dict(self) -> dict: """Serializes the AlertTask into a dictionary suitable for use as a JSON request body.""" @@ -166,23 +168,26 @@ class BaseJob: effective_budget_policy_id: Optional[str] = None """The id of the budget policy used by this job for cost attribution purposes. This may be set - through (in order of precedence): 1. Budget admins through the account or workspace console 2. - Jobs UI in the job details page and Jobs API using `budget_policy_id` 3. Inferred default based - on accessible budget policies of the run_as identity on job creation or modification.""" + through (in order of precedence): + + 1. Budget admins through the account or workspace console + 2. Jobs UI in the job details page and Jobs API using ``budget_policy_id`` + 3. Inferred default based on accessible budget policies of the run_as identity on job creation + or modification.""" effective_usage_policy_id: Optional[str] = None """The id of the usage policy used by this job for cost attribution purposes.""" has_more: Optional[bool] = None - """Indicates if the job has more array properties (`tasks`, `job_clusters`) that are not shown. + """Indicates if the job has more array properties (``tasks``, ``job_clusters``) that are not shown. They can be accessed via :method:jobs/get endpoint. It is only relevant for API 2.2 - :method:jobs/list requests with `expand_tasks=true`.""" + :method:jobs/list requests with ``expand_tasks=true``.""" job_id: Optional[int] = None """The canonical identifier for this job.""" settings: Optional[JobSettings] = None - """Settings for this job and all of its runs. These settings can be updated using the `resetJob` + """Settings for this job and all of its runs. These settings can be updated using the ``resetJob`` method.""" trigger_state: Optional[TriggerStateProto] = None @@ -250,15 +255,16 @@ class BaseRun: attempt_number: Optional[int] = None """The sequence number of this run attempt for a triggered job run. The initial attempt of a run has an attempt_number of 0. If the initial run attempt fails, and the job has a retry policy - (`max_retries` > 0), subsequent runs are created with an `original_attempt_run_id` of the - 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.""" + (``max_retries`` > 0), subsequent runs are created with an ``original_attempt_run_id`` of the + 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.""" 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 - `cleanup_duration`. The `cleanup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``cleanup_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" cluster_instance: Optional[ClusterInstance] = None """The cluster used for this run. If the run is specified to use a new cluster, this field is set @@ -279,9 +285,9 @@ class BaseRun: the client-set performance target on the request depending on whether the performance mode is supported by the job type. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * - `PERFORMANCE_OPTIMIZED`: Prioritizes fast startup and execution times through rapid scaling and - optimized cluster performance.""" + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling + and optimized cluster performance.""" effective_usage_policy_id: Optional[str] = None """The id of the usage policy used by this run for cost attribution purposes.""" @@ -293,24 +299,24 @@ class BaseRun: execution_duration: Optional[int] = None """The time in milliseconds it took to execute the commands in the JAR or notebook until they completed, failed, timed out, were cancelled, or encountered an unexpected error. The duration - of a task run is the sum of the `setup_duration`, `execution_duration`, and the - `cleanup_duration`. The `execution_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``execution_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" git_source: Optional[GitSource] = None """An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - 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. + 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.""" + are used, ``git_source`` must be defined on the job.""" has_more: Optional[bool] = None - """Indicates if the run has more array properties (`tasks`, `job_clusters`) that are not shown. + """Indicates if the run has more array properties (``tasks``, ``job_clusters``) that are not shown. They can be accessed via :method:jobs/getrun endpoint. It is only relevant for API 2.2 - :method:jobs/listruns requests with `expand_tasks=true`.""" + :method:jobs/listruns requests with ``expand_tasks=true``.""" job_clusters: Optional[List[JobCluster]] = None """A list of job cluster specifications that can be shared and reused by tasks of this job. @@ -330,7 +336,7 @@ class BaseRun: that the task run belongs to.""" number_in_job: Optional[int] = None - """A unique identifier for this job run. This is set to the same value as `run_id`.""" + """A unique identifier for this job run. This is set to the same value as ``run_id``.""" original_attempt_run_id: Optional[int] = None """If this run is a retry of a prior run attempt, this field contains the run_id of the original @@ -365,9 +371,9 @@ class BaseRun: setup_duration: Optional[int] = None """The time in milliseconds it took to set up the cluster. For runs that run on new clusters this is the cluster creation time, for runs that run on existing clusters this time should be very - short. The duration of a task run is the sum of the `setup_duration`, `execution_duration`, and - the `cleanup_duration`. The `setup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + short. The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, + and the ``cleanup_duration``. The ``setup_duration`` field is set to 0 for multitask job runs. + The total duration of a multitask job run is the value of the ``run_duration`` field.""" start_time: Optional[int] = None """The time at which this run was started in epoch milliseconds (milliseconds since 1/1/1970 UTC). @@ -375,15 +381,15 @@ class BaseRun: scheduled to run on a new cluster, this is the time the cluster creation call is issued.""" state: Optional[RunState] = None - """Deprecated. Please use the `status` field instead.""" + """Deprecated. Please use the ``status`` field instead.""" status: Optional[RunStatus] = None tasks: Optional[List[RunTask]] = None - """The list of tasks performed by the run. Each task has its own `run_id` which you can use to call - `JobsGetOutput` to retrieve the run resutls. If more than 100 tasks are available, you can - paginate through them using :method:jobs/getrun. Use the `next_page_token` field at the object - root to determine if more results are available.""" + """The list of tasks performed by the run. Each task has its own ``run_id`` which you can use to + call ``JobsGetOutput`` to retrieve the run resutls. If more than 100 tasks are available, you + can paginate through them using :method:jobs/getrun. Use the ``next_page_token`` field at the + object root to determine if more results are available.""" trigger: Optional[TriggerType] = None @@ -754,7 +760,7 @@ class ClusterInstance: """The canonical identifier for the cluster used by a run. This field is always available for runs on existing clusters. For runs on new clusters, it becomes available once the cluster is created. This value can be used to view logs by browsing to - `/#setting/sparkui/$cluster_id/driver-logs`. The logs continue to be available after the run + ``/#setting/sparkui/$cluster_id/driver-logs``. The logs continue to be available after the run completes. The response won’t include this field if the identifier is not available yet.""" @@ -762,8 +768,8 @@ class ClusterInstance: spark_context_id: Optional[str] = None """The canonical identifier for the Spark context used by a run. This field is filled in once the run begins execution. This value can be used to view the Spark UI by browsing to - `/#setting/sparkui/$cluster_id/$spark_context_id`. The Spark UI continues to be available after - the run has completed. + ``/#setting/sparkui/$cluster_id/$spark_context_id``. The Spark UI continues to be available + after the run has completed. The response won’t include this field if the identifier is not available yet.""" @@ -800,7 +806,7 @@ class ClusterSpec: job_cluster_key: Optional[str] = None """If job_cluster_key, this task is executed reusing the cluster specified in - `job.settings.job_clusters`.""" + ``job.settings.job_clusters``.""" libraries: Optional[List[compute.Library]] = None """An optional list of libraries to be installed on the cluster. The default value is an empty @@ -922,15 +928,15 @@ class Condition(Enum): @dataclass class ConditionTask: op: ConditionTaskOp - """* `EQUAL_TO`, `NOT_EQUAL` operators perform string comparison of their operands. This means that - `“12.0” == “12”` will evaluate to `false`. * `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, - `LESS_THAN`, `LESS_THAN_OR_EQUAL` operators perform numeric comparison of their operands. - `“12.0” >= “12”` will evaluate to `true`, `“10.0” >= “12”` will evaluate to - `false`. + """- ``EQUAL_TO``, ``NOT_EQUAL`` operators perform string comparison of their operands. This means + that ``“12.0” == “12”`` will evaluate to ``false``. + - ``GREATER_THAN``, ``GREATER_THAN_OR_EQUAL``, ``LESS_THAN``, ``LESS_THAN_OR_EQUAL`` operators + perform numeric comparison of their operands. ``“12.0” >= “12”`` will evaluate to + ``true``, ``“10.0” >= “12”`` will evaluate to ``false``. - The boolean comparison to task values can be implemented with operators `EQUAL_TO`, `NOT_EQUAL`. - If a task value was set to a boolean value, it will be serialized to `“true”` or - `“false”` for the comparison.""" + The boolean comparison to task values can be implemented with operators ``EQUAL_TO``, + ``NOT_EQUAL``. If a task value was set to a boolean value, it will be serialized to + ``“true”`` or ``“false”`` for the comparison.""" left: str """The left operand of the condition task. Can be either a string value or a job state or parameter @@ -969,15 +975,15 @@ def from_dict(cls, d: Dict[str, Any]) -> ConditionTask: class ConditionTaskOp(Enum): - """* `EQUAL_TO`, `NOT_EQUAL` operators perform string comparison of their operands. This means that - `“12.0” == “12”` will evaluate to `false`. * `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, - `LESS_THAN`, `LESS_THAN_OR_EQUAL` operators perform numeric comparison of their operands. - `“12.0” >= “12”` will evaluate to `true`, `“10.0” >= “12”` will evaluate to - `false`. + """- ``EQUAL_TO``, ``NOT_EQUAL`` operators perform string comparison of their operands. This means + that ``“12.0” == “12”`` will evaluate to ``false``. + - ``GREATER_THAN``, ``GREATER_THAN_OR_EQUAL``, ``LESS_THAN``, ``LESS_THAN_OR_EQUAL`` operators + perform numeric comparison of their operands. ``“12.0” >= “12”`` will evaluate to + ``true``, ``“10.0” >= “12”`` will evaluate to ``false``. - The boolean comparison to task values can be implemented with operators `EQUAL_TO`, `NOT_EQUAL`. - If a task value was set to a boolean value, it will be serialized to `“true”` or - `“false”` for the comparison.""" + The boolean comparison to task values can be implemented with operators ``EQUAL_TO``, + ``NOT_EQUAL``. If a task value was set to a boolean value, it will be serialized to + ``“true”`` or ``“false”`` for the comparison.""" EQUAL_TO = "EQUAL_TO" GREATER_THAN = "GREATER_THAN" @@ -1052,16 +1058,14 @@ def from_dict(cls, d: Dict[str, Any]) -> CreateResponse: @dataclass class CronSchedule: quartz_cron_expression: str - """A Cron expression using Quartz syntax that describes the schedule for a job. See [Cron Trigger] - for details. This field is required. - - [Cron Trigger]: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html""" + """A Cron expression using Quartz syntax that describes the schedule for a job. See `Cron Trigger + `__ for + details. This field is required.""" timezone_id: str - """A Java timezone ID. The schedule for a job is resolved with respect to this timezone. See [Java - TimeZone] for details. This field is required. - - [Java TimeZone]: https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html""" + """A Java timezone ID. The schedule for a job is resolved with respect to this timezone. See `Java + TimeZone `__ for details. + This field is required.""" pause_status: Optional[PauseStatus] = None """Indicate whether this schedule is paused or not.""" @@ -1141,12 +1145,14 @@ class DashboardTask: filters: Optional[Dict[str, str]] = None """Dashboard task parameters. Used to apply dashboard filter values during dashboard task execution. Parameter values get applied to any dashboard filters that have a matching URL - identifier as the parameter key. The parameter value format is dependent on the filter type: - - For text and single-select filters, provide a single value (e.g. `"value"`) - For date and - datetime filters, provide the value in ISO 8601 format (e.g. `"2000-01-01T00:00:00"`) - For - multi-select filters, provide a JSON array of values (e.g. `"[\"value1\",\"value2\"]"`) - For - range and date range filters, provide a JSON object with `start` and `end` (e.g. - `"{\"start\":\"1\",\"end\":\"10\"}"`)""" + identifier as the parameter key. The parameter value format is dependent on the filter type: + + - For text and single-select filters, provide a single value (e.g. ``"value"``) + - For date and datetime filters, provide the value in ISO 8601 format (e.g. + ``"2000-01-01T00:00:00"``) + - For multi-select filters, provide a JSON array of values (e.g. ``"[\"value1\",\"value2\"]"``) + - For range and date range filters, provide a JSON object with ``start`` and ``end`` (e.g. + ``"{\"start\":\"1\",\"end\":\"10\"}"``)""" subscription: Optional[Subscription] = None """Optional: subscription configuration for sending the dashboard snapshot.""" @@ -1356,7 +1362,7 @@ def from_dict(cls, d: Dict[str, Any]) -> DbtCloudTaskOutput: @dataclass class DbtOutput: artifacts_headers: Optional[Dict[str, str]] = None - """An optional map of headers to send when retrieving the artifact from the `artifacts_link`.""" + """An optional map of headers to send when retrieving the artifact from the ``artifacts_link``.""" artifacts_link: Optional[str] = None """A pre-signed URL to download the (compressed) dbt artifacts. This link is valid for a limited @@ -1559,7 +1565,7 @@ def from_dict(cls, d: Dict[str, Any]) -> DbtPlatformTaskOutput: @dataclass class DbtTask: commands: List[str] - """A list of dbt commands to execute. All commands must start with `dbt`. This parameter must not + """A list of dbt commands to execute. All commands must start with ``dbt``. This parameter must not be empty. A maximum of up to 10 commands can be provided.""" catalog: Optional[str] = None @@ -1577,21 +1583,21 @@ class DbtTask: schema: Optional[str] = None """Optional schema to write to. This parameter is only used when a warehouse_id is also provided. - If not provided, the `default` schema is used.""" + If not provided, the ``default`` schema is used.""" source: Optional[Source] = None - """Optional location type of the project directory. When set to `WORKSPACE`, the project will be - retrieved from the local Databricks workspace. When set to `GIT`, the project will be retrieved - from a Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if - `git_source` is defined and `WORKSPACE` otherwise. + """Optional location type of the project directory. When set to ``WORKSPACE``, the project will be + retrieved from the local Databricks workspace. When set to ``GIT``, the project will be + retrieved from a Git repository defined in ``git_source``. If the value is empty, the task will + use ``GIT`` if ``git_source`` is defined and ``WORKSPACE`` otherwise. - * `WORKSPACE`: Project is located in Databricks workspace. * `GIT`: Project is located in cloud - Git provider.""" + - ``WORKSPACE``: Project is located in Databricks workspace. + - ``GIT``: Project is located in cloud Git provider.""" warehouse_id: Optional[str] = None """ID of the SQL warehouse to connect to. If provided, we automatically generate and provide the profile and connection details to dbt. It can be overridden on a per-command basis by using the - `--profiles-dir` command line argument.""" + ``--profiles-dir`` command line argument.""" def as_dict(self) -> dict: """Serializes the DbtTask into a dictionary suitable for use as a JSON request body.""" @@ -1749,7 +1755,7 @@ class ExportRunOutput: views: Optional[List[ViewItem]] = None """The exported content in HTML format (one for every view item). To extract the HTML notebook from - the JSON response, download and run this [Python script](/_static/examples/extract.py).""" + the JSON response, download and run this Python script.""" def as_dict(self) -> dict: """Serializes the ExportRunOutput into a dictionary suitable for use as a JSON request body.""" @@ -2037,10 +2043,10 @@ class Format(Enum): @dataclass class GenAiComputeTask: - """DEPRECATED — use `AiRuntimeTask` for all new BYOT multi-node GPU workloads (see - ai_runtime_task.proto). `AiRuntimeTask` is the only supported BYOT task type for new workloads; - this proto is retained only for AIR CLI (fka SGCLI) pywheel backwards compatibility and will be - removed once the pywheel → databricks-cli migration completes (post- PuPr).""" + """DEPRECATED — use ``AiRuntimeTask`` for all new BYOT multi-node GPU workloads (see + ai_runtime_task.proto). ``AiRuntimeTask`` is the only supported BYOT task type for new + workloads; this proto is retained only for AIR CLI (fka SGCLI) pywheel backwards compatibility + and will be removed once the pywheel → databricks-cli migration completes (post- PuPr).""" dl_runtime_image: str """Runtime image""" @@ -2055,17 +2061,19 @@ class GenAiComputeTask: found, backend will create the mlflow experiment using the name.""" source: Optional[Source] = None - """Optional location type of the training script. When set to `WORKSPACE`, the script will be - retrieved from the local Databricks workspace. When set to `GIT`, the script will be retrieved - from a Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if - `git_source` is defined and `WORKSPACE` otherwise. * `WORKSPACE`: Script is located in - Databricks workspace. * `GIT`: Script is located in cloud Git provider.""" + """Optional location type of the training script. When set to ``WORKSPACE``, the script will be + retrieved from the local Databricks workspace. When set to ``GIT``, the script will be retrieved + from a Git repository defined in ``git_source``. If the value is empty, the task will use + ``GIT`` if ``git_source`` is defined and ``WORKSPACE`` otherwise. + + - ``WORKSPACE``: Script is located in Databricks workspace. + - ``GIT``: Script is located in cloud Git provider.""" training_script_path: Optional[str] = None """The training script file path to be executed. Cloud file URIs (such as dbfs:/, s3:/, adls:/, gcs:/) and workspace paths are supported. For python files stored in the Databricks workspace, - the path must be absolute and begin with `/`. For files stored in a remote repository, the path - must be relative. This field is required.""" + the path must be absolute and begin with ``/``. For files stored in a remote repository, the + path must be relative. This field is required.""" yaml_parameters: Optional[str] = None """Optional string containing model parameters passed to the training script in yaml format. If @@ -2239,11 +2247,11 @@ class GitSource: """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. + 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.""" + are used, ``git_source`` must be defined on the job.""" git_url: str """URL of the repository to be cloned by this job.""" @@ -2340,17 +2348,20 @@ class Job: effective_budget_policy_id: Optional[str] = None """The id of the budget policy used by this job for cost attribution purposes. This may be set - through (in order of precedence): 1. Budget admins through the account or workspace console 2. - Jobs UI in the job details page and Jobs API using `budget_policy_id` 3. Inferred default based - on accessible budget policies of the run_as identity on job creation or modification.""" + through (in order of precedence): + + 1. Budget admins through the account or workspace console + 2. Jobs UI in the job details page and Jobs API using ``budget_policy_id`` + 3. Inferred default based on accessible budget policies of the run_as identity on job creation + or modification.""" effective_usage_policy_id: Optional[str] = None """The id of the usage policy used by this job for cost attribution purposes.""" has_more: Optional[bool] = None - """Indicates if the job has more array properties (`tasks`, `job_clusters`) that are not shown. + """Indicates if the job has more array properties (``tasks``, ``job_clusters``) that are not shown. They can be accessed via :method:jobs/get endpoint. It is only relevant for API 2.2 - :method:jobs/list requests with `expand_tasks=true`.""" + :method:jobs/list requests with ``expand_tasks=true``.""" job_id: Optional[int] = None """The canonical identifier for this job.""" @@ -2360,15 +2371,15 @@ class Job: run_as_user_name: Optional[str] = None """The email of an active workspace user or the application ID of a service principal that the job - runs as. This value can be changed by setting the `run_as` field when creating or updating a + runs as. This value can be changed by setting the ``run_as`` field when creating or updating a job. - By default, `run_as_user_name` is based on the current job settings and is set to the creator of - the job if job access control is disabled or to the user with the `is_owner` permission if job - access control is enabled.""" + By default, ``run_as_user_name`` is based on the current job settings and is set to the creator + of the job if job access control is disabled or to the user with the ``is_owner`` permission if + job access control is enabled.""" settings: Optional[JobSettings] = None - """Settings for this job and all of its runs. These settings can be updated using the `resetJob` + """Settings for this job and all of its runs. These settings can be updated using the ``resetJob`` method.""" trigger_state: Optional[TriggerStateProto] = None @@ -2554,7 +2565,7 @@ def from_dict(cls, d: Dict[str, Any]) -> JobAccessControlResponse: class JobCluster: job_cluster_key: str """A unique name for the job cluster. This field is required and must be unique within the job. - `JobTaskSettings` may refer to this field to determine which cluster to launch for the task + ``JobTaskSettings`` may refer to this field to determine which cluster to launch for the task execution.""" new_cluster: compute.ClusterSpec @@ -2636,19 +2647,19 @@ class JobDeployment: kind: JobDeploymentKind """The kind of deployment that manages the job. - * `BUNDLE`: The job is managed by Databricks Asset Bundle. * `SYSTEM_MANAGED`: The job is - managed by Databricks and is read-only.""" + - ``BUNDLE``: The job is managed by Databricks Asset Bundle. + - ``SYSTEM_MANAGED``: The job is managed by Databricks and is read-only.""" deployment_id: Optional[str] = None - """ID of the deployment that manages this job. Only set when `kind` is `BUNDLE`. Used to look up - deployment metadata from the Deployment Metadata service.""" + """ID of the deployment that manages this job. Only set when ``kind`` is ``BUNDLE``. Used to look + up deployment metadata from the Deployment Metadata service.""" metadata_file_path: Optional[str] = None """Path of the file that contains deployment metadata.""" version_id: Optional[str] = None - """ID of the version of the deployment that produced this job. Only set when `kind` is `BUNDLE`. - Identifies a specific snapshot of the deployment in the Deployment Metadata service.""" + """ID of the version of the deployment that produced this job. Only set when ``kind`` is + ``BUNDLE``. Identifies a specific snapshot of the deployment in the Deployment Metadata service.""" def as_dict(self) -> dict: """Serializes the JobDeployment into a dictionary suitable for use as a JSON request body.""" @@ -2688,8 +2699,8 @@ def from_dict(cls, d: Dict[str, Any]) -> JobDeployment: class JobDeploymentKind(Enum): - """* `BUNDLE`: The job is managed by Databricks Asset Bundle. * `SYSTEM_MANAGED`: The job is - managed by Databricks and is read-only.""" + """- ``BUNDLE``: The job is managed by Databricks Asset Bundle. + - ``SYSTEM_MANAGED``: The job is managed by Databricks and is read-only.""" BUNDLE = "BUNDLE" SYSTEM_MANAGED = "SYSTEM_MANAGED" @@ -2698,8 +2709,8 @@ class JobDeploymentKind(Enum): class JobEditMode(Enum): """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.""" + - ``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.""" EDITABLE = "EDITABLE" UI_LOCKED = "UI_LOCKED" @@ -2708,20 +2719,21 @@ class JobEditMode(Enum): @dataclass class JobEmailNotifications: no_alert_for_skipped_runs: Optional[bool] = None - """If true, do not send email to recipients specified in `on_failure` if the run is skipped. This - field is `deprecated`. Please use the `notification_settings.no_alert_for_skipped_runs` field.""" + """If true, do not send email to recipients specified in ``on_failure`` if the run is skipped. This + field is ``deprecated``. Please use the ``notification_settings.no_alert_for_skipped_runs`` + field.""" on_duration_warning_threshold_exceeded: Optional[List[str]] = None """A list of email addresses to be notified when the duration of a run exceeds the threshold - specified for the `RUN_DURATION_SECONDS` metric in the `health` field. If no rule for the - `RUN_DURATION_SECONDS` metric is specified in the `health` field for the job, notifications are - not sent.""" + specified for the ``RUN_DURATION_SECONDS`` metric in the ``health`` field. If no rule for the + ``RUN_DURATION_SECONDS`` metric is specified in the ``health`` field for the job, notifications + are not sent.""" on_failure: Optional[List[str]] = None """A list of email addresses to be notified when a run unsuccessfully completes. A run is - considered to have completed unsuccessfully if it ends with an `INTERNAL_ERROR` - `life_cycle_state` or a `FAILED`, or `TIMED_OUT` result_state. If this is not specified on job - creation, reset, or update the list is empty, and notifications are not sent.""" + considered to have completed unsuccessfully if it ends with an ``INTERNAL_ERROR`` + ``life_cycle_state`` or a ``FAILED``, or ``TIMED_OUT`` result_state. If this is not specified on + job creation, reset, or update the list is empty, and notifications are not sent.""" on_start: Optional[List[str]] = None """A list of email addresses to be notified when a run begins. If not specified on job creation, @@ -2729,16 +2741,17 @@ class JobEmailNotifications: on_streaming_backlog_exceeded: Optional[List[str]] = None """A list of email addresses to notify when any streaming backlog thresholds are exceeded for any - stream. Streaming backlog thresholds can be set in the `health` field using the following - metrics: `STREAMING_BACKLOG_BYTES`, `STREAMING_BACKLOG_RECORDS`, `STREAMING_BACKLOG_SECONDS`, or - `STREAMING_BACKLOG_FILES`. Alerting is based on the 10-minute average of these metrics. If the - issue persists, notifications are resent every 30 minutes.""" + stream. Streaming backlog thresholds can be set in the ``health`` field using the following + metrics: ``STREAMING_BACKLOG_BYTES``, ``STREAMING_BACKLOG_RECORDS``, + ``STREAMING_BACKLOG_SECONDS``, or ``STREAMING_BACKLOG_FILES``. Alerting is based on the + 10-minute average of these metrics. If the issue persists, notifications are resent every 30 + minutes.""" on_success: Optional[List[str]] = None """A list of email addresses to be notified when a run successfully completes. A run is considered - to have completed successfully if it ends with a `TERMINATED` `life_cycle_state` and a `SUCCESS` - result_state. If not specified on job creation, reset, or update, the list is empty, and - notifications are not sent.""" + to have completed successfully if it ends with a ``TERMINATED`` ``life_cycle_state`` and a + ``SUCCESS`` result_state. If not specified on job creation, reset, or update, the list is empty, + and notifications are not sent.""" def as_dict(self) -> dict: """Serializes the JobEmailNotifications into a dictionary suitable for use as a JSON request body.""" @@ -2821,11 +2834,11 @@ def from_dict(cls, d: Dict[str, Any]) -> JobEnvironment: @dataclass class JobNotificationSettings: no_alert_for_canceled_runs: Optional[bool] = None - """If true, do not send notifications to recipients specified in `on_failure` if the run is + """If true, do not send notifications to recipients specified in ``on_failure`` if the run is canceled.""" no_alert_for_skipped_runs: Optional[bool] = None - """If true, do not send notifications to recipients specified in `on_failure` if the run is + """If true, do not send notifications to recipients specified in ``on_failure`` if the run is skipped.""" def as_dict(self) -> dict: @@ -2897,7 +2910,8 @@ def from_dict(cls, d: Dict[str, Any]) -> JobParameter: @dataclass class JobParameterDefinition: name: str - """The name of the defined parameter. May only contain alphanumeric characters, `_`, `-`, and `.`""" + """The name of the defined parameter. May only contain alphanumeric characters, ``_``, ``-``, and + ``.``""" default: str """Default value of the parameter.""" @@ -3052,7 +3066,8 @@ class JobRunAs: """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.""" + Either ``user_name`` or ``service_principal_name`` should be specified. If not, an error is + thrown.""" group_name: Optional[str] = None """Group name of an account group assigned to the workspace. Setting this field requires being a @@ -3060,7 +3075,7 @@ class JobRunAs: service_principal_name: Optional[str] = None """Application ID of an active service principal. Setting this field requires the - `servicePrincipal/user` role.""" + ``servicePrincipal/user`` role.""" user_name: Optional[str] = None """The email of an active workspace user. Non-admin users can only set this field to their own @@ -3103,11 +3118,11 @@ class JobSettings: budget_policy_id: Optional[str] = None """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.""" + ``effective_budget_policy_id`` for the budget policy used by this workload.""" continuous: Optional[Continuous] = None """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.""" + always one run executing. Only one of ``schedule`` and ``continuous`` can be used.""" deployment: Optional[JobDeployment] = None """Deployment information for jobs managed by external sources.""" @@ -3118,8 +3133,8 @@ class JobSettings: edit_mode: Optional[JobEditMode] = None """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.""" + - ``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.""" email_notifications: Optional[JobEmailNotifications] = None """An optional set of email addresses that is notified when runs of this job begin or complete as @@ -3134,17 +3149,17 @@ class JobSettings: format: Optional[Format] = None """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"`.""" + When using the Jobs API 2.1 this value is always set to ``"MULTI_TASK"``.""" git_source: Optional[GitSource] = None """An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - 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. + 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.""" + are used, ``git_source`` must be defined on the job.""" health: Optional[JobsHealthRules] = None @@ -3161,14 +3176,14 @@ class JobSettings: 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.""" + value cannot exceed 1000. Setting this value to ``0`` causes all new runs to be skipped.""" name: Optional[str] = None """An optional name for the job. The maximum length is 4096 bytes in UTF-8 encoding.""" notification_settings: Optional[JobNotificationSettings] = None """Optional notification settings that are used when sending notifications to each of the - `email_notifications` and `webhook_notifications` for this job.""" + ``email_notifications`` and ``webhook_notifications`` for this job.""" parameters: Optional[List[JobParameterDefinition]] = None """Job-level parameter definitions""" @@ -3178,21 +3193,21 @@ class JobSettings: or cost-efficiency for the run. The performance target does not apply to tasks that run on Serverless GPU compute. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * - `PERFORMANCE_OPTIMIZED`: Prioritizes fast startup and execution times through rapid scaling and - optimized cluster performance.""" + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling + and optimized cluster performance.""" queue: Optional[QueueSettings] = None """The queue settings of the job.""" run_as: Optional[JobRunAs] = None """The user or service principal that the job runs as, if specified in the request. This field - indicates the explicit configuration of `run_as` for the job. To find the value in all cases, - explicit or implicit, use `run_as_user_name`.""" + indicates the explicit configuration of ``run_as`` for the job. To find the value in all cases, + explicit or implicit, use ``run_as_user_name``.""" schedule: Optional[CronSchedule] = None """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`.""" + triggered by clicking “Run Now” in the Jobs UI or sending an API request to ``runNow``.""" tags: Optional[Dict[str, str]] = None """A map of tags associated with the job. These are forwarded to the cluster as cluster tags for @@ -3203,20 +3218,20 @@ class JobSettings: """A list of task specifications to be executed by this job. It supports up to 1000 elements in write endpoints (:method:jobs/create, :method:jobs/reset, :method:jobs/update, :method:jobs/submit). Read endpoints return only 100 tasks. If more than 100 tasks are - available, you can paginate through them using :method:jobs/get. Use the `next_page_token` field - at the object root to determine if more results are available.""" + available, you can paginate through them using :method:jobs/get. Use the ``next_page_token`` + field at the object root to determine if more results are available.""" timeout_seconds: Optional[int] = None - """An optional timeout applied to each run of this job. A value of `0` means no timeout.""" + """An optional timeout applied to each run of this job. A value of ``0`` means no timeout.""" trigger: Optional[TriggerSettings] = None """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`.""" + request to ``runNow``.""" usage_policy_id: Optional[str] = None """The id of the user specified usage policy to use for this job. If not specified, a default usage - policy may be applied when creating or modifying the job. See `effective_usage_policy_id` for + policy may be applied when creating or modifying the job. See ``effective_usage_policy_id`` for the usage policy used by this workload.""" webhook_notifications: Optional[WebhookNotifications] = None @@ -3378,11 +3393,13 @@ class JobSource: """Dirty state indicates the job is not fully synced with the job specification in the remote repository. - Possible values are: * `NOT_SYNCED`: The job is not yet synced with the remote job - specification. Import the remote job specification from UI to make the job fully synced. * - `DISCONNECTED`: The job is temporary disconnected from the remote job specification and is - allowed for live edit. Import the remote job specification again from UI to make the job fully - synced.""" + Possible values are: + + - ``NOT_SYNCED``: The job is not yet synced with the remote job specification. Import the remote + job specification from UI to make the job fully synced. + - ``DISCONNECTED``: The job is temporary disconnected from the remote job specification and is + allowed for live edit. Import the remote job specification again from UI to make the job fully + synced.""" def as_dict(self) -> dict: """Serializes the JobSource into a dictionary suitable for use as a JSON request body.""" @@ -3420,11 +3437,13 @@ class JobSourceDirtyState(Enum): """Dirty state indicates the job is not fully synced with the job specification in the remote repository. - Possible values are: * `NOT_SYNCED`: The job is not yet synced with the remote job - specification. Import the remote job specification from UI to make the job fully synced. * - `DISCONNECTED`: The job is temporary disconnected from the remote job specification and is - allowed for live edit. Import the remote job specification again from UI to make the job fully - synced.""" + Possible values are: + + - ``NOT_SYNCED``: The job is not yet synced with the remote job specification. Import the remote + job specification from UI to make the job fully synced. + - ``DISCONNECTED``: The job is temporary disconnected from the remote job specification and is + allowed for live edit. Import the remote job specification again from UI to make the job fully + synced.""" DISCONNECTED = "DISCONNECTED" NOT_SYNCED = "NOT_SYNCED" @@ -3433,13 +3452,15 @@ class JobSourceDirtyState(Enum): class JobsHealthMetric(Enum): """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 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.""" + - ``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.""" RUN_DURATION_SECONDS = "RUN_DURATION_SECONDS" STREAMING_BACKLOG_BYTES = "STREAMING_BACKLOG_BYTES" @@ -3747,11 +3768,9 @@ class ModelTriggerConfigurationCondition(Enum): @dataclass class NotebookOutput: result: Optional[str] = None - """The value passed to - [dbutils.notebook.exit()](/notebooks/notebook-workflows.html#notebook-workflows-exit). - Databricks restricts this API to return the first 5 MB of the value. For a larger result, your - job can store the results in a cloud storage service. This field is absent if - `dbutils.notebook.exit()` was never called.""" + """The value passed to dbutils.notebook.exit(). Databricks restricts this API to return the first 5 + MB of the value. For a larger result, your job can store the results in a cloud storage service. + This field is absent if ``dbutils.notebook.exit()`` was never called.""" truncated: Optional[bool] = None """Whether or not the result was truncated.""" @@ -3790,28 +3809,29 @@ class NotebookTask: base_parameters: Optional[Dict[str, str]] = None """Base parameters to be used for each run of this job. If the run is initiated by a call to :method:jobs/run Now with parameters specified, the two parameters maps are merged. If the same - key is specified in `base_parameters` and in `run-now`, the value from `run-now` is used. Use - [Task parameter variables] to set parameters containing information about job runs. + key is specified in ``base_parameters`` and in ``run-now``, the value from ``run-now`` is used. + Use `Task parameter variables `__ to + set parameters containing information about job runs. - If the notebook takes a parameter that is not specified in the job’s `base_parameters` or the - `run-now` override parameters, the default value from the notebook is used. + If the notebook takes a parameter that is not specified in the job’s ``base_parameters`` or + the ``run-now`` override parameters, the default value from the notebook is used. - Retrieve these parameters in a notebook using [dbutils.widgets.get]. + Retrieve these parameters in a notebook using `dbutils.widgets.get + `__. - The JSON representation of this field cannot exceed 1MB. - - [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables - [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-widgets""" + The JSON representation of this field cannot exceed 1MB.""" source: Optional[Source] = None - """Optional location type of the notebook. When set to `WORKSPACE`, the notebook will be retrieved - from the local Databricks workspace. When set to `GIT`, the notebook will be retrieved from a - Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if - `git_source` is defined and `WORKSPACE` otherwise. * `WORKSPACE`: Notebook is located in - Databricks workspace. * `GIT`: Notebook is located in cloud Git provider.""" + """Optional location type of the notebook. When set to ``WORKSPACE``, the notebook will be + retrieved from the local Databricks workspace. When set to ``GIT``, the notebook will be + retrieved from a Git repository defined in ``git_source``. If the value is empty, the task will + use ``GIT`` if ``git_source`` is defined and ``WORKSPACE`` otherwise. + + - ``WORKSPACE``: Notebook is located in Databricks workspace. + - ``GIT``: Notebook is located in cloud Git provider.""" warehouse_id: Optional[str] = None - """Optional `warehouse_id` to run the notebook on a SQL warehouse. Classic SQL warehouses are NOT + """Optional ``warehouse_id`` to run the notebook on a SQL warehouse. Classic SQL warehouses are NOT supported, please use serverless or pro SQL warehouses. Note that SQL warehouses only support SQL cells; if the notebook contains non-SQL cells, the run @@ -4259,8 +4279,8 @@ def from_dict(cls, d: Dict[str, Any]) -> PowerBiTask: @dataclass class PythonOperatorTask: main: Optional[str] = None - """Fully qualified name of the main class or function. For example, `my_project.my_function` or - `my_project.MyOperator`.""" + """Fully qualified name of the main class or function. For example, ``my_project.my_function`` or + ``my_project.MyOperator``.""" parameters: Optional[List[PythonOperatorTaskParameter]] = None """An ordered list of task parameters. TODO(JOBS-30885): Add limits for parameters.""" @@ -4326,15 +4346,15 @@ class PythonWheelTask: entry_point: str """Named entry point to use, if it does not exist in the metadata of the package it executes the - function from the package directly using `$packageName.$entryPoint()`""" + function from the package directly using ``$packageName.$entryPoint()``""" named_parameters: Optional[Dict[str, str]] = None - """Command-line parameters passed to Python wheel task in the form of `["--name=task", - "--data=dbfs:/path/to/data.json"]`. Leave it empty if `parameters` is not null.""" + """Command-line parameters passed to Python wheel task in the form of ``["--name=task", + "--data=dbfs:/path/to/data.json"]``. Leave it empty if ``parameters`` is not null.""" parameters: Optional[List[str]] = None - """Command-line parameters passed to Python wheel task. Leave it empty if `named_parameters` is not - null.""" + """Command-line parameters passed to Python wheel task. Leave it empty if ``named_parameters`` is + not null.""" def as_dict(self) -> dict: """Serializes the PythonWheelTask into a dictionary suitable for use as a JSON request body.""" @@ -4406,11 +4426,14 @@ def from_dict(cls, d: Dict[str, Any]) -> QueueDetails: class QueueDetailsCodeCode(Enum): - """The reason for queuing the run. * `ACTIVE_RUNS_LIMIT_REACHED`: The run was queued due to - reaching the workspace limit of active task runs. * `MAX_CONCURRENT_RUNS_REACHED`: The run was - queued due to reaching the per-job limit of concurrent job runs. * - `ACTIVE_RUN_JOB_TASKS_LIMIT_REACHED`: The run was queued due to reaching the workspace limit of - active run job tasks.""" + """The reason for queuing the run. + + - ``ACTIVE_RUNS_LIMIT_REACHED``: The run was queued due to reaching the workspace limit of + active task runs. + - ``MAX_CONCURRENT_RUNS_REACHED``: The run was queued due to reaching the per-job limit of + concurrent job runs. + - ``ACTIVE_RUN_JOB_TASKS_LIMIT_REACHED``: The run was queued due to reaching the workspace limit + of active run job tasks.""" ACTIVE_RUNS_LIMIT_REACHED = "ACTIVE_RUNS_LIMIT_REACHED" ACTIVE_RUN_JOB_TASKS_LIMIT_REACHED = "ACTIVE_RUN_JOB_TASKS_LIMIT_REACHED" @@ -4449,21 +4472,21 @@ class RepairHistoryItem: the client-set performance target on the request depending on whether the performance mode is supported by the job type. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * - `PERFORMANCE_OPTIMIZED`: Prioritizes fast startup and execution times through rapid scaling and - optimized cluster performance.""" + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling + and optimized cluster performance.""" end_time: Optional[int] = None """The end time of the (repaired) run.""" id: Optional[int] = None - """The ID of the repair. Only returned for the items that represent a repair in `repair_history`.""" + """The ID of the repair. Only returned for the items that represent a repair in ``repair_history``.""" start_time: Optional[int] = None """The start time of the (repaired) run.""" state: Optional[RunState] = None - """Deprecated. Please use the `status` field instead.""" + """Deprecated. Please use the ``status`` field instead.""" status: Optional[RunStatus] = None @@ -4542,8 +4565,8 @@ class RepairRunResponse: """Run repair was initiated.""" repair_id: Optional[int] = None - """The ID of the repair. Must be provided in subsequent repairs using the `latest_repair_id` field - to ensure sequential repairs.""" + """The ID of the repair. Must be provided in subsequent repairs using the ``latest_repair_id`` + field to ensure sequential repairs.""" def as_dict(self) -> dict: """Serializes the RepairRunResponse into a dictionary suitable for use as a JSON request body.""" @@ -4880,15 +4903,16 @@ class Run: attempt_number: Optional[int] = None """The sequence number of this run attempt for a triggered job run. The initial attempt of a run has an attempt_number of 0. If the initial run attempt fails, and the job has a retry policy - (`max_retries` > 0), subsequent runs are created with an `original_attempt_run_id` of the - 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.""" + (``max_retries`` > 0), subsequent runs are created with an ``original_attempt_run_id`` of the + 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.""" 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 - `cleanup_duration`. The `cleanup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``cleanup_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" cluster_instance: Optional[ClusterInstance] = None """The cluster used for this run. If the run is specified to use a new cluster, this field is set @@ -4909,9 +4933,9 @@ class Run: the client-set performance target on the request depending on whether the performance mode is supported by the job type. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * - `PERFORMANCE_OPTIMIZED`: Prioritizes fast startup and execution times through rapid scaling and - optimized cluster performance.""" + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling + and optimized cluster performance.""" effective_usage_policy_id: Optional[str] = None """The id of the usage policy used by this run for cost attribution purposes.""" @@ -4923,24 +4947,24 @@ class Run: execution_duration: Optional[int] = None """The time in milliseconds it took to execute the commands in the JAR or notebook until they completed, failed, timed out, were cancelled, or encountered an unexpected error. The duration - of a task run is the sum of the `setup_duration`, `execution_duration`, and the - `cleanup_duration`. The `execution_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``execution_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" git_source: Optional[GitSource] = None """An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - 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. + 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.""" + are used, ``git_source`` must be defined on the job.""" has_more: Optional[bool] = None - """Indicates if the run has more array properties (`tasks`, `job_clusters`) that are not shown. + """Indicates if the run has more array properties (``tasks``, ``job_clusters``) that are not shown. They can be accessed via :method:jobs/getrun endpoint. It is only relevant for API 2.2 - :method:jobs/listruns requests with `expand_tasks=true`.""" + :method:jobs/listruns requests with ``expand_tasks=true``.""" iterations: Optional[List[RunTask]] = None """Only populated by for-each iterations. The parent for-each task is located in tasks array.""" @@ -4966,7 +4990,7 @@ class Run: """A token that can be used to list the next page of array properties.""" number_in_job: Optional[int] = None - """A unique identifier for this job run. This is set to the same value as `run_id`.""" + """A unique identifier for this job run. This is set to the same value as ``run_id``.""" original_attempt_run_id: Optional[int] = None """If this run is a retry of a prior run attempt, this field contains the run_id of the original @@ -5001,9 +5025,9 @@ class Run: setup_duration: Optional[int] = None """The time in milliseconds it took to set up the cluster. For runs that run on new clusters this is the cluster creation time, for runs that run on existing clusters this time should be very - short. The duration of a task run is the sum of the `setup_duration`, `execution_duration`, and - the `cleanup_duration`. The `setup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + short. The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, + and the ``cleanup_duration``. The ``setup_duration`` field is set to 0 for multitask job runs. + The total duration of a multitask job run is the value of the ``run_duration`` field.""" start_time: Optional[int] = None """The time at which this run was started in epoch milliseconds (milliseconds since 1/1/1970 UTC). @@ -5011,15 +5035,15 @@ class Run: scheduled to run on a new cluster, this is the time the cluster creation call is issued.""" state: Optional[RunState] = None - """Deprecated. Please use the `status` field instead.""" + """Deprecated. Please use the ``status`` field instead.""" status: Optional[RunStatus] = None tasks: Optional[List[RunTask]] = None - """The list of tasks performed by the run. Each task has its own `run_id` which you can use to call - `JobsGetOutput` to retrieve the run resutls. If more than 100 tasks are available, you can - paginate through them using :method:jobs/getrun. Use the `next_page_token` field at the object - root to determine if more results are available.""" + """The list of tasks performed by the run. Each task has its own ``run_id`` which you can use to + call ``JobsGetOutput`` to retrieve the run resutls. If more than 100 tasks are available, you + can paginate through them using :method:jobs/getrun. Use the ``next_page_token`` field at the + object root to determine if more results are available.""" trigger: Optional[TriggerType] = None @@ -5225,15 +5249,15 @@ def from_dict(cls, d: Dict[str, Any]) -> Run: @dataclass class RunConditionTask: op: ConditionTaskOp - """* `EQUAL_TO`, `NOT_EQUAL` operators perform string comparison of their operands. This means that - `“12.0” == “12”` will evaluate to `false`. * `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, - `LESS_THAN`, `LESS_THAN_OR_EQUAL` operators perform numeric comparison of their operands. - `“12.0” >= “12”` will evaluate to `true`, `“10.0” >= “12”` will evaluate to - `false`. + """- ``EQUAL_TO``, ``NOT_EQUAL`` operators perform string comparison of their operands. This means + that ``“12.0” == “12”`` will evaluate to ``false``. + - ``GREATER_THAN``, ``GREATER_THAN_OR_EQUAL``, ``LESS_THAN``, ``LESS_THAN_OR_EQUAL`` operators + perform numeric comparison of their operands. ``“12.0” >= “12”`` will evaluate to + ``true``, ``“10.0” >= “12”`` will evaluate to ``false``. - The boolean comparison to task values can be implemented with operators `EQUAL_TO`, `NOT_EQUAL`. - If a task value was set to a boolean value, it will be serialized to `“true”` or - `“false”` for the comparison.""" + The boolean comparison to task values can be implemented with operators ``EQUAL_TO``, + ``NOT_EQUAL``. If a task value was set to a boolean value, it will be serialized to + ``“true”`` or ``“false”`` for the comparison.""" left: str """The left operand of the condition task. Can be either a string value or a job state or parameter @@ -5245,7 +5269,7 @@ class RunConditionTask: outcome: Optional[str] = None """The condition expression evaluation result. Filled in if the task was successfully completed. - Can be `"true"` or `"false"`""" + Can be ``"true"`` or ``"false"``""" def as_dict(self) -> dict: """Serializes the RunConditionTask into a dictionary suitable for use as a JSON request body.""" @@ -5339,13 +5363,16 @@ def from_dict(cls, d: Dict[str, Any]) -> RunForEachTask: class RunIf(Enum): """An optional value indicating the condition that determines whether the task should be run once - its dependencies have been completed. When omitted, defaults to `ALL_SUCCESS`. + its dependencies have been completed. When omitted, defaults to ``ALL_SUCCESS``. + + Possible values are: - Possible values are: * `ALL_SUCCESS`: All dependencies have executed and succeeded * - `AT_LEAST_ONE_SUCCESS`: At least one dependency has succeeded * `NONE_FAILED`: None of the - dependencies have failed and at least one was executed * `ALL_DONE`: All dependencies have been - completed * `AT_LEAST_ONE_FAILED`: At least one dependency failed * `ALL_FAILED`: ALl - dependencies have failed""" + - ``ALL_SUCCESS``: All dependencies have executed and succeeded + - ``AT_LEAST_ONE_SUCCESS``: At least one dependency has succeeded + - ``NONE_FAILED``: None of the dependencies have failed and at least one was executed + - ``ALL_DONE``: All dependencies have been completed + - ``AT_LEAST_ONE_FAILED``: At least one dependency failed + - ``ALL_FAILED``: ALl dependencies have failed""" ALL_DONE = "ALL_DONE" ALL_FAILED = "ALL_FAILED" @@ -5386,43 +5413,42 @@ class RunJobTask: """ID of the job to trigger.""" dbt_commands: Optional[List[str]] = None - """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"]` - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + """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"]`` - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" jar_params: Optional[List[str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" job_parameters: Optional[Dict[str, str]] = None """Job-level parameters used to trigger the job.""" notebook_params: Optional[Dict[str, str]] = None - """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. + """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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - The JSON representation of this field (for example `{"notebook_params":{"name":"john - doe","age":"35"}}`) cannot exceed 10,000 bytes. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. - [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + The JSON representation of this field (for example ``{"notebook_params":{"name":"john + doe","age":"35"}}``) cannot exceed 10,000 bytes.""" pipeline_params: Optional[PipelineParams] = None """Controls whether the pipeline should perform a full refresh""" @@ -5430,45 +5456,45 @@ class RunJobTask: python_named_params: Optional[Dict[str, str]] = None python_params: Optional[List[str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + emojis.""" spark_submit_params: Optional[List[str]] = None - """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 + """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. + ``{"python_params":["john doe","35"]}``) cannot exceed 10,000 bytes. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + emojis.""" sql_params: Optional[Dict[str, str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" def as_dict(self) -> dict: """Serializes the RunJobTask into a dictionary suitable for use as a JSON request body.""" @@ -5538,17 +5564,23 @@ def from_dict(cls, d: Dict[str, Any]) -> RunJobTask: class RunLifeCycleState(Enum): - """A value indicating the run's lifecycle state. The possible values are: * `QUEUED`: The run is - queued. * `PENDING`: The run is waiting to be executed while the cluster and execution context - are being prepared. * `RUNNING`: The task of this run is being executed. * `TERMINATING`: The - task of this run has completed, and the cluster and execution context are being cleaned up. * - `TERMINATED`: The task of this run has completed, and the cluster and execution context have - been cleaned up. This state is terminal. * `SKIPPED`: This run was aborted because a previous - run of the same job was already active. This state is terminal. * `INTERNAL_ERROR`: An - exceptional state that indicates a failure in the Jobs service, such as network failure over a - long period. If a run on a new cluster ends in the `INTERNAL_ERROR` state, the Jobs service - terminates the cluster as soon as possible. This state is terminal. * `BLOCKED`: The run is - blocked on an upstream dependency. * `WAITING_FOR_RETRY`: The run is waiting for a retry.""" + """A value indicating the run's lifecycle state. The possible values are: + + - ``QUEUED``: The run is queued. + - ``PENDING``: The run is waiting to be executed while the cluster and execution context are + being prepared. + - ``RUNNING``: The task of this run is being executed. + - ``TERMINATING``: The task of this run has completed, and the cluster and execution context are + being cleaned up. + - ``TERMINATED``: The task of this run has completed, and the cluster and execution context have + been cleaned up. This state is terminal. + - ``SKIPPED``: This run was aborted because a previous run of the same job was already active. + This state is terminal. + - ``INTERNAL_ERROR``: An exceptional state that indicates a failure in the Jobs service, such as + network failure over a long period. If a run on a new cluster ends in the ``INTERNAL_ERROR`` + state, the Jobs service terminates the cluster as soon as possible. This state is terminal. + - ``BLOCKED``: The run is blocked on an upstream dependency. + - ``WAITING_FOR_RETRY``: The run is waiting for a retry.""" BLOCKED = "BLOCKED" INTERNAL_ERROR = "INTERNAL_ERROR" @@ -5578,7 +5610,7 @@ class RunNowResponse: """Run was started successfully.""" number_in_job: Optional[int] = None - """A unique identifier for this job run. This is set to the same value as `run_id`.""" + """A unique identifier for this job run. This is set to the same value as ``run_id``.""" run_id: Optional[int] = None """The globally unique ID of the newly triggered run.""" @@ -5653,12 +5685,11 @@ class RunOutput: notebook_output: Optional[NotebookOutput] = None """The output of a notebook task, if available. A notebook task that terminates (either - successfully or with a failure) without calling `dbutils.notebook.exit()` is considered to have - an empty output. This field is set but its result value is empty. Databricks restricts this API - to return the first 5 MB of the output. To return a larger result, use the [ClusterLogConf] - field to configure log storage for the job cluster. - - [ClusterLogConf]: https://docs.databricks.com/dev-tools/api/latest/clusters.html#clusterlogconf""" + successfully or with a failure) without calling ``dbutils.notebook.exit()`` is considered to + have an empty output. This field is set but its result value is empty. Databricks restricts this + API to return the first 5 MB of the output. To return a larger result, use the `ClusterLogConf + `__ field to + configure log storage for the job cluster.""" run_job_output: Optional[RunJobOutput] = None """The output of a run job task, if available""" @@ -5763,40 +5794,39 @@ def from_dict(cls, d: Dict[str, Any]) -> RunOutput: @dataclass class RunParameters: dbt_commands: Optional[List[str]] = None - """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"]` - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + """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"]`` - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" jar_params: Optional[List[str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" notebook_params: Optional[Dict[str, str]] = None - """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. + """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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - The JSON representation of this field (for example `{"notebook_params":{"name":"john - doe","age":"35"}}`) cannot exceed 10,000 bytes. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. - [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + The JSON representation of this field (for example ``{"notebook_params":{"name":"john + doe","age":"35"}}``) cannot exceed 10,000 bytes.""" pipeline_params: Optional[PipelineParams] = None """Controls whether the pipeline should perform a full refresh""" @@ -5804,45 +5834,45 @@ class RunParameters: python_named_params: Optional[Dict[str, str]] = None python_params: Optional[List[str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + emojis.""" spark_submit_params: Optional[List[str]] = None - """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 + """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. + ``{"python_params":["john doe","35"]}``) cannot exceed 10,000 bytes. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + emojis.""" sql_params: Optional[Dict[str, str]] = None - """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. + """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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown""" + ⚠ **Deprecation note** Use `job parameters + `__ to pass + information down to tasks.""" def as_dict(self) -> dict: """Serializes the RunParameters into a dictionary suitable for use as a JSON request body.""" @@ -5902,15 +5932,20 @@ def from_dict(cls, d: Dict[str, Any]) -> RunParameters: class RunResultState(Enum): - """A value indicating the run's result. The possible values are: * `SUCCESS`: The task completed - successfully. * `FAILED`: The task completed with an error. * `TIMEDOUT`: The run was stopped - after reaching the timeout. * `CANCELED`: The run was canceled at user request. * - `MAXIMUM_CONCURRENT_RUNS_REACHED`: The run was skipped because the maximum concurrent runs were - reached. * `EXCLUDED`: The run was skipped because the necessary conditions were not met. * - `SUCCESS_WITH_FAILURES`: The job run completed successfully with some failures; leaf tasks were - successful. * `UPSTREAM_FAILED`: The run was skipped because of an upstream failure. * - `UPSTREAM_CANCELED`: The run was skipped because an upstream task was canceled. * `DISABLED`: - The run was skipped because it was disabled explicitly by the user.""" + """A value indicating the run's result. The possible values are: + + - ``SUCCESS``: The task completed successfully. + - ``FAILED``: The task completed with an error. + - ``TIMEDOUT``: The run was stopped after reaching the timeout. + - ``CANCELED``: The run was canceled at user request. + - ``MAXIMUM_CONCURRENT_RUNS_REACHED``: The run was skipped because the maximum concurrent runs + were reached. + - ``EXCLUDED``: The run was skipped because the necessary conditions were not met. + - ``SUCCESS_WITH_FAILURES``: The job run completed successfully with some failures; leaf tasks + were successful. + - ``UPSTREAM_FAILED``: The run was skipped because of an upstream failure. + - ``UPSTREAM_CANCELED``: The run was skipped because an upstream task was canceled. + - ``DISABLED``: The run was skipped because it was disabled explicitly by the user.""" CANCELED = "CANCELED" DISABLED = "DISABLED" @@ -6045,25 +6080,25 @@ class RunTask: alert_task: Optional[AlertTask] = None """The task evaluates a Databricks alert and sends notifications to subscribers when the - `alert_task` field is present.""" + ``alert_task`` field is present.""" attempt_number: Optional[int] = None """The sequence number of this run attempt for a triggered job run. The initial attempt of a run has an attempt_number of 0. If the initial run attempt fails, and the job has a retry policy - (`max_retries` > 0), subsequent runs are created with an `original_attempt_run_id` of the - 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.""" + (``max_retries`` > 0), subsequent runs are created with an ``original_attempt_run_id`` of the + 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/clean-rooms/index.html""" + """The task runs a `clean rooms `__ notebook + when the ``clean_rooms_notebook_task`` field is present.""" 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 - `cleanup_duration`. The `cleanup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``cleanup_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" cluster_instance: Optional[ClusterInstance] = None """The cluster used for this run. If the run is specified to use a new cluster, this field is set @@ -6074,8 +6109,8 @@ class RunTask: condition_task: Optional[RunConditionTask] = 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 - does not support retries or notifications.""" + ``condition_task`` field is present. The condition task does not require a cluster to execute + and does not support retries or notifications.""" dashboard_task: Optional[DashboardTask] = None """The task refreshes a dashboard and sends a snapshot to subscribers.""" @@ -6086,13 +6121,13 @@ class RunTask: dbt_platform_task: Optional[DbtPlatformTask] = None dbt_task: Optional[DbtTask] = None - """The task runs one or more dbt commands when the `dbt_task` field is present. The dbt task + """The task runs one or more dbt commands when the ``dbt_task`` field is present. The dbt task requires both Databricks SQL and the ability to use a serverless or a pro SQL warehouse.""" depends_on: Optional[List[TaskDependency]] = None """An optional array of objects specifying the dependency graph of the task. All tasks specified in - this field must complete successfully before executing this task. The key is `task_key`, and the - value is the name assigned to the dependent task.""" + this field must complete successfully before executing this task. The key is ``task_key``, and + the value is the name assigned to the dependent task.""" description: Optional[str] = None """An optional description for this task.""" @@ -6109,9 +6144,9 @@ class RunTask: the client-set performance target on the request depending on whether the performance mode is supported by the job type. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * - `PERFORMANCE_OPTIMIZED`: Prioritizes fast startup and execution times through rapid scaling and - optimized cluster performance.""" + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling + and optimized cluster performance.""" email_notifications: Optional[JobEmailNotifications] = None """An optional set of email addresses notified when the task run begins or completes. The default @@ -6128,9 +6163,9 @@ class RunTask: execution_duration: Optional[int] = None """The time in milliseconds it took to execute the commands in the JAR or notebook until they completed, failed, timed out, were cancelled, or encountered an unexpected error. The duration - of a task run is the sum of the `setup_duration`, `execution_duration`, and the - `cleanup_duration`. The `execution_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + of a task run is the sum of the ``setup_duration``, ``execution_duration``, and the + ``cleanup_duration``. The ``execution_duration`` field is set to 0 for multitask job runs. The + total duration of a multitask job run is the value of the ``run_duration`` field.""" existing_cluster_id: Optional[str] = None """If existing_cluster_id, the ID of an existing cluster that is used for all runs. When running @@ -6138,7 +6173,7 @@ class RunTask: responding. We suggest running jobs and tasks on new clusters for greater reliability""" for_each_task: Optional[RunForEachTask] = None - """The task executes a nested task for every input provided when the `for_each_task` field is + """The task executes a nested task for every input provided when the ``for_each_task`` field is present.""" gen_ai_compute_task: Optional[GenAiComputeTask] = None @@ -6146,14 +6181,14 @@ class RunTask: git_source: Optional[GitSource] = None """An optional specification for a remote Git repository containing the source code used by tasks. Version-controlled source code is supported by notebook, dbt, Python script, and SQL File tasks. - 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.""" + 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.""" job_cluster_key: Optional[str] = None """If job_cluster_key, this task is executed reusing the cluster specified in - `job.settings.job_clusters`.""" + ``job.settings.job_clusters``.""" libraries: Optional[List[compute.Library]] = None """An optional list of libraries to be installed on the cluster. The default value is an empty @@ -6161,9 +6196,9 @@ class RunTask: max_retries: Optional[int] = None """An optional maximum number of times to retry an unsuccessful run. A run is considered to be - unsuccessful if it completes with the `FAILED` result_state or `INTERNAL_ERROR` - `life_cycle_state`. The value `-1` means to retry indefinitely and the value `0` means to never - retry.""" + unsuccessful if it completes with the ``FAILED`` result_state or ``INTERNAL_ERROR`` + ``life_cycle_state``. The value ``-1`` means to retry indefinitely and the value ``0`` means to + never retry.""" min_retry_interval_millis: Optional[int] = None """An optional minimal interval in milliseconds between the start of the failed run and the @@ -6173,24 +6208,24 @@ class RunTask: """If new_cluster, a description of a new cluster that is created for each run.""" notebook_task: Optional[NotebookTask] = None - """The task runs a notebook when the `notebook_task` field is present.""" + """The task runs a notebook when the ``notebook_task`` field is present.""" notification_settings: Optional[TaskNotificationSettings] = None """Optional notification settings that are used when sending notifications to each of the - `email_notifications` and `webhook_notifications` for this task run.""" + ``email_notifications`` and ``webhook_notifications`` for this task run.""" pipeline_task: Optional[PipelineTask] = None - """The task triggers a pipeline update when the `pipeline_task` field is present. Only pipelines + """The task triggers a pipeline update when the ``pipeline_task`` field is present. Only pipelines configured to use triggered more are supported.""" power_bi_task: Optional[PowerBiTask] = None - """The task triggers a Power BI semantic model update when the `power_bi_task` field is present.""" + """The task triggers a Power BI semantic model update when the ``power_bi_task`` field is present.""" python_operator_task: Optional[PythonOperatorTask] = None """The task runs a Python operator task.""" python_wheel_task: Optional[PythonWheelTask] = None - """The task runs a Python wheel when the `python_wheel_task` field is present.""" + """The task runs a Python wheel when the ``python_wheel_task`` field is present.""" queue_duration: Optional[int] = None """The time in milliseconds that the run has spent in the queue.""" @@ -6210,35 +6245,34 @@ class RunTask: run_if: Optional[RunIf] = None """An optional value indicating the condition that determines whether the task should be run once - its dependencies have been completed. When omitted, defaults to `ALL_SUCCESS`. See + its dependencies have been completed. When omitted, defaults to ``ALL_SUCCESS``. See :method:jobs/create for a list of possible values.""" run_job_task: Optional[RunJobTask] = None - """The task triggers another job when the `run_job_task` field is present.""" + """The task triggers another job when the ``run_job_task`` field is present.""" run_page_url: Optional[str] = None setup_duration: Optional[int] = None """The time in milliseconds it took to set up the cluster. For runs that run on new clusters this is the cluster creation time, for runs that run on existing clusters this time should be very - short. The duration of a task run is the sum of the `setup_duration`, `execution_duration`, and - the `cleanup_duration`. The `setup_duration` field is set to 0 for multitask job runs. The total - duration of a multitask job run is the value of the `run_duration` field.""" + short. The duration of a task run is the sum of the ``setup_duration``, ``execution_duration``, + and the ``cleanup_duration``. The ``setup_duration`` field is set to 0 for multitask job runs. + The total duration of a multitask job run is the value of the ``run_duration`` field.""" spark_jar_task: Optional[SparkJarTask] = None - """The task runs a JAR when the `spark_jar_task` field is present.""" + """The task runs a JAR when the ``spark_jar_task`` field is present.""" spark_python_task: Optional[SparkPythonTask] = None - """The task runs a Python file when the `spark_python_task` field is present.""" + """The task runs a Python file when the ``spark_python_task`` field is present.""" spark_submit_task: Optional[SparkSubmitTask] = None """(Legacy) The task runs the spark-submit script when the spark_submit_task field is present. - Databricks recommends using the spark_jar_task instead; see [Spark Submit task for - jobs](/jobs/spark-submit).""" + Databricks recommends using the spark_jar_task instead; see Spark Submit task for jobs.""" sql_task: Optional[SqlTask] = None """The task runs a SQL query or file, or it refreshes a SQL alert or a legacy SQL dashboard when - the `sql_task` field is present.""" + the ``sql_task`` field is present.""" start_time: Optional[int] = None """The time at which this run was started in epoch milliseconds (milliseconds since 1/1/1970 UTC). @@ -6246,12 +6280,12 @@ class RunTask: scheduled to run on a new cluster, this is the time the cluster creation call is issued.""" state: Optional[RunState] = None - """Deprecated. Please use the `status` field instead.""" + """Deprecated. Please use the ``status`` field instead.""" status: Optional[RunStatus] = None timeout_seconds: Optional[int] = None - """An optional timeout applied to each run of this job task. A value of `0` means no timeout.""" + """An optional timeout applied to each run of this job task. A value of ``0`` means no timeout.""" webhook_notifications: Optional[WebhookNotifications] = None """A collection of system notification IDs to notify when the run begins or completes. The default @@ -6546,11 +6580,12 @@ def from_dict(cls, d: Dict[str, Any]) -> RunTask: class RunType(Enum): - """The type of a run. * `JOB_RUN`: Normal job run. A run created with :method:jobs/runNow. * - `WORKFLOW_RUN`: Workflow run. A run created with [dbutils.notebook.run]. * `SUBMIT_RUN`: Submit - run. A run created with :method:jobs/submit. + """The type of a run. - [dbutils.notebook.run]: https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-workflow""" + - ``JOB_RUN``: Normal job run. A run created with :method:jobs/runNow. + - ``WORKFLOW_RUN``: Workflow run. A run created with `dbutils.notebook.run + `__. + - ``SUBMIT_RUN``: Submit run. A run created with :method:jobs/submit.""" JOB_RUN = "JOB_RUN" SUBMIT_RUN = "SUBMIT_RUN" @@ -6558,13 +6593,13 @@ class RunType(Enum): class Source(Enum): - """Optional location type of the SQL file. When set to `WORKSPACE`, the SQL file will be retrieved\ - from the local Databricks workspace. When set to `GIT`, the SQL file will be retrieved from a - Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if - `git_source` is defined and `WORKSPACE` otherwise. - - * `WORKSPACE`: SQL file is located in Databricks workspace. * `GIT`: SQL file is located in - cloud Git provider.""" + """Optional location type of the SQL file. When set to ``WORKSPACE``, the SQL file will be + retrieved from the local Databricks workspace. When set to ``GIT``, the SQL file will be + retrieved from a Git repository defined in ``git_source``. If the value is empty, the task will + use ``GIT`` if ``git_source`` is defined and ``WORKSPACE`` otherwise. + + - ``WORKSPACE``: SQL file is located in Databricks workspace. + - ``GIT``: SQL file is located in cloud Git provider.""" GIT = "GIT" WORKSPACE = "WORKSPACE" @@ -6573,9 +6608,9 @@ class Source(Enum): @dataclass class SparkJarTask: jar_uri: Optional[str] = None - """Deprecated since 04/2016. For classic compute, provide a `jar` through the `libraries` field - instead. For serverless compute, provide a `jar` though the `java_dependencies` field inside the - `environments` list. + """Deprecated since 04/2016. For classic compute, provide a ``jar`` through the ``libraries`` field + instead. For serverless compute, provide a ``jar`` though the ``java_dependencies`` field inside + the ``environments`` list. See the examples of classic and serverless compute usage at the top of the page.""" @@ -6583,18 +6618,17 @@ class SparkJarTask: """The full name of the class containing the main method to be executed. This class must be contained in a JAR provided as a library. - The code must use `SparkContext.getOrCreate` to obtain a Spark context; otherwise, runs of the + The code must use ``SparkContext.getOrCreate`` to obtain a Spark context; otherwise, runs of the job fail.""" parameters: Optional[List[str]] = None """Parameters passed to the main method. - Use [Task parameter variables] to set parameters containing information about job runs. - - [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables""" + Use `Task parameter variables `__ to + set parameters containing information about job runs.""" run_as_repl: Optional[bool] = None - """Deprecated. A value of `false` is no longer supported.""" + """Deprecated. A value of ``false`` is no longer supported.""" def as_dict(self) -> dict: """Serializes the SparkJarTask into a dictionary suitable for use as a JSON request body.""" @@ -6638,24 +6672,24 @@ class SparkPythonTask: python_file: str """The Python file to be executed. Cloud file URIs (such as dbfs:/, s3:/, adls:/, gcs:/) and workspace paths are supported. For python files stored in the Databricks workspace, the path - must be absolute and begin with `/`. For files stored in a remote repository, the path must be + must be absolute and begin with ``/``. For files stored in a remote repository, the path must be relative. This field is required.""" parameters: Optional[List[str]] = None """Command line parameters passed to the Python file. - Use [Task parameter variables] to set parameters containing information about job runs. - - [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables""" + Use `Task parameter variables `__ to + set parameters containing information about job runs.""" source: Optional[Source] = None - """Optional location type of the Python file. When set to `WORKSPACE` or not specified, the file - will be retrieved from the local Databricks workspace or cloud location (if the `python_file` - has a URI format). When set to `GIT`, the Python file will be retrieved from a Git repository - defined in `git_source`. + """Optional location type of the Python file. When set to ``WORKSPACE`` or not specified, the file + will be retrieved from the local Databricks workspace or cloud location (if the ``python_file`` + has a URI format). When set to ``GIT``, the Python file will be retrieved from a Git repository + defined in ``git_source``. - * `WORKSPACE`: The Python file is located in a Databricks workspace or at a cloud filesystem - URI. * `GIT`: The Python file is located in a remote Git repository.""" + - ``WORKSPACE``: The Python file is located in a Databricks workspace or at a cloud filesystem + URI. + - ``GIT``: The Python file is located in a remote Git repository.""" def as_dict(self) -> dict: """Serializes the SparkPythonTask into a dictionary suitable for use as a JSON request body.""" @@ -6694,9 +6728,8 @@ class SparkSubmitTask: parameters: Optional[List[str]] = None """Command-line parameters passed to spark submit. - Use [Task parameter variables] to set parameters containing information about job runs. - - [Task parameter variables]: https://docs.databricks.com/jobs.html#parameter-variables""" + Use `Task parameter variables `__ to + set parameters containing information about job runs.""" def as_dict(self) -> dict: """Serializes the SparkSubmitTask into a dictionary suitable for use as a JSON request body.""" @@ -6805,8 +6838,9 @@ def from_dict(cls, d: Dict[str, Any]) -> SqlAlertOutput: class SqlAlertState(Enum): """The state of the SQL alert. - * UNKNOWN: alert yet to be evaluated * OK: alert evaluated and did not fulfill trigger - conditions * TRIGGERED: alert evaluated and fulfilled trigger conditions""" + - UNKNOWN: alert yet to be evaluated + - OK: alert evaluated and did not fulfill trigger conditions + - TRIGGERED: alert evaluated and fulfilled trigger conditions""" OK = "OK" TRIGGERED = "TRIGGERED" @@ -7252,13 +7286,13 @@ class SqlTaskFile: workspace paths.""" source: Optional[Source] = None - """Optional location type of the SQL file. When set to `WORKSPACE`, the SQL file will be retrieved - from the local Databricks workspace. When set to `GIT`, the SQL file will be retrieved from a - Git repository defined in `git_source`. If the value is empty, the task will use `GIT` if - `git_source` is defined and `WORKSPACE` otherwise. + """Optional location type of the SQL file. When set to ``WORKSPACE``, the SQL file will be + retrieved from the local Databricks workspace. When set to ``GIT``, the SQL file will be + retrieved from a Git repository defined in ``git_source``. If the value is empty, the task will + use ``GIT`` if ``git_source`` is defined and ``WORKSPACE`` otherwise. - * `WORKSPACE`: SQL file is located in Databricks workspace. * `GIT`: SQL file is located in - cloud Git provider.""" + - ``WORKSPACE``: SQL file is located in Databricks workspace. + - ``GIT``: SQL file is located in cloud Git provider.""" def as_dict(self) -> dict: """Serializes the SqlTaskFile into a dictionary suitable for use as a JSON request body.""" @@ -7386,20 +7420,19 @@ class SubmitTask: alert_task: Optional[AlertTask] = None """The task evaluates a Databricks alert and sends notifications to subscribers when the - `alert_task` field is present.""" + ``alert_task`` field is present.""" 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/clean-rooms/index.html""" + """The task runs a `clean rooms `__ notebook + when the ``clean_rooms_notebook_task`` field is present.""" compute: Optional[Compute] = None """Task level compute configuration.""" 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 - does not support retries or notifications.""" + ``condition_task`` field is present. The condition task does not require a cluster to execute + and does not support retries or notifications.""" dashboard_task: Optional[DashboardTask] = None """The task refreshes a dashboard and sends a snapshot to subscribers.""" @@ -7410,13 +7443,13 @@ class SubmitTask: dbt_platform_task: Optional[DbtPlatformTask] = None dbt_task: Optional[DbtTask] = None - """The task runs one or more dbt commands when the `dbt_task` field is present. The dbt task + """The task runs one or more dbt commands when the ``dbt_task`` field is present. The dbt task requires both Databricks SQL and the ability to use a serverless or a pro SQL warehouse.""" depends_on: Optional[List[TaskDependency]] = None """An optional array of objects specifying the dependency graph of the task. All tasks specified in - this field must complete successfully before executing this task. The key is `task_key`, and the - value is the name assigned to the dependent task.""" + this field must complete successfully before executing this task. The key is ``task_key``, and + the value is the name assigned to the dependent task.""" description: Optional[str] = None """An optional description for this task.""" @@ -7442,7 +7475,7 @@ class SubmitTask: responding. We suggest running jobs and tasks on new clusters for greater reliability""" for_each_task: Optional[ForEachTask] = None - """The task executes a nested task for every input provided when the `for_each_task` field is + """The task executes a nested task for every input provided when the ``for_each_task`` field is present.""" gen_ai_compute_task: Optional[GenAiComputeTask] = None @@ -7455,9 +7488,9 @@ class SubmitTask: max_retries: Optional[int] = None """An optional maximum number of times to retry an unsuccessful run. A run is considered to be - unsuccessful if it completes with the `FAILED` result_state or `INTERNAL_ERROR` - `life_cycle_state`. The value `-1` means to retry indefinitely and the value `0` means to never - retry.""" + unsuccessful if it completes with the ``FAILED`` result_state or ``INTERNAL_ERROR`` + ``life_cycle_state``. The value ``-1`` means to retry indefinitely and the value ``0`` means to + never retry.""" min_retry_interval_millis: Optional[int] = None """An optional minimal interval in milliseconds between the start of the failed run and the @@ -7467,24 +7500,24 @@ class SubmitTask: """If new_cluster, a description of a new cluster that is created for each run.""" notebook_task: Optional[NotebookTask] = None - """The task runs a notebook when the `notebook_task` field is present.""" + """The task runs a notebook when the ``notebook_task`` field is present.""" notification_settings: Optional[TaskNotificationSettings] = None """Optional notification settings that are used when sending notifications to each of the - `email_notifications` and `webhook_notifications` for this task run.""" + ``email_notifications`` and ``webhook_notifications`` for this task run.""" pipeline_task: Optional[PipelineTask] = None - """The task triggers a pipeline update when the `pipeline_task` field is present. Only pipelines + """The task triggers a pipeline update when the ``pipeline_task`` field is present. Only pipelines configured to use triggered more are supported.""" power_bi_task: Optional[PowerBiTask] = None - """The task triggers a Power BI semantic model update when the `power_bi_task` field is present.""" + """The task triggers a Power BI semantic model update when the ``power_bi_task`` field is present.""" python_operator_task: Optional[PythonOperatorTask] = None """The task runs a Python operator task.""" python_wheel_task: Optional[PythonWheelTask] = None - """The task runs a Python wheel when the `python_wheel_task` field is present.""" + """The task runs a Python wheel when the ``python_wheel_task`` field is present.""" retry_on_timeout: Optional[bool] = None """An optional policy to specify whether to retry a job when it times out. The default behavior is @@ -7492,29 +7525,28 @@ class SubmitTask: run_if: Optional[RunIf] = None """An optional value indicating the condition that determines whether the task should be run once - its dependencies have been completed. When omitted, defaults to `ALL_SUCCESS`. See + its dependencies have been completed. When omitted, defaults to ``ALL_SUCCESS``. See :method:jobs/create for a list of possible values.""" run_job_task: Optional[RunJobTask] = None - """The task triggers another job when the `run_job_task` field is present.""" + """The task triggers another job when the ``run_job_task`` field is present.""" spark_jar_task: Optional[SparkJarTask] = None - """The task runs a JAR when the `spark_jar_task` field is present.""" + """The task runs a JAR when the ``spark_jar_task`` field is present.""" spark_python_task: Optional[SparkPythonTask] = None - """The task runs a Python file when the `spark_python_task` field is present.""" + """The task runs a Python file when the ``spark_python_task`` field is present.""" spark_submit_task: Optional[SparkSubmitTask] = None """(Legacy) The task runs the spark-submit script when the spark_submit_task field is present. - Databricks recommends using the spark_jar_task instead; see [Spark Submit task for - jobs](/jobs/spark-submit).""" + Databricks recommends using the spark_jar_task instead; see Spark Submit task for jobs.""" sql_task: Optional[SqlTask] = None """The task runs a SQL query or file, or it refreshes a SQL alert or a legacy SQL dashboard when - the `sql_task` field is present.""" + the ``sql_task`` field is present.""" timeout_seconds: Optional[int] = None - """An optional timeout applied to each run of this job task. A value of `0` means no timeout.""" + """An optional timeout applied to each run of this job task. A value of ``0`` means no timeout.""" webhook_notifications: Optional[WebhookNotifications] = None """A collection of system notification IDs to notify when the run begins or completes. The default @@ -7774,11 +7806,11 @@ def from_dict(cls, d: Dict[str, Any]) -> Subscription: @dataclass class SubscriptionSubscriber: destination_id: Optional[str] = None - """A snapshot of the dashboard will be sent to the destination when the `destination_id` field is + """A snapshot of the dashboard will be sent to the destination when the ``destination_id`` field is present.""" user_name: Optional[str] = None - """A snapshot of the dashboard will be sent to the user's email when the `user_name` field is + """A snapshot of the dashboard will be sent to the user's email when the ``user_name`` field is present.""" def as_dict(self) -> dict: @@ -7812,7 +7844,7 @@ class TableState: successful evaluation of the trigger""" table_name: Optional[str] = None - """Full table name of the table to monitor, e.g. `mycatalog.myschema.mytable`""" + """Full table name of the table to monitor, e.g. ``mycatalog.myschema.mytable``""" def as_dict(self) -> dict: """Serializes the TableState into a dictionary suitable for use as a JSON request body.""" @@ -7876,7 +7908,7 @@ def from_dict(cls, d: Dict[str, Any]) -> TableTriggerState: class TableUpdateTriggerConfiguration: table_names: List[str] """A list of tables to monitor for changes. The table name must be in the format - `catalog_name.schema_name.table_name`.""" + ``catalog_name.schema_name.table_name``.""" condition: Optional[Condition] = None """The table(s) condition based on which to trigger a job run.""" @@ -7936,20 +7968,19 @@ class Task: alert_task: Optional[AlertTask] = None """The task evaluates a Databricks alert and sends notifications to subscribers when the - `alert_task` field is present.""" + ``alert_task`` field is present.""" 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/clean-rooms/index.html""" + """The task runs a `clean rooms `__ notebook + when the ``clean_rooms_notebook_task`` field is present.""" compute: Optional[Compute] = None """Task level compute configuration.""" 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 - does not support retries or notifications.""" + ``condition_task`` field is present. The condition task does not require a cluster to execute + and does not support retries or notifications.""" dashboard_task: Optional[DashboardTask] = None """The task refreshes a dashboard and sends a snapshot to subscribers.""" @@ -7960,13 +7991,13 @@ class Task: dbt_platform_task: Optional[DbtPlatformTask] = None dbt_task: Optional[DbtTask] = None - """The task runs one or more dbt commands when the `dbt_task` field is present. The dbt task + """The task runs one or more dbt commands when the ``dbt_task`` field is present. The dbt task requires both Databricks SQL and the ability to use a serverless or a pro SQL warehouse.""" depends_on: Optional[List[TaskDependency]] = None """An optional array of objects specifying the dependency graph of the task. All tasks specified in - this field must complete before executing this task. The task will run only if the `run_if` - condition is true. The key is `task_key`, and the value is the name assigned to the dependent + this field must complete before executing this task. The task will run only if the ``run_if`` + condition is true. The key is ``task_key``, and the value is the name assigned to the dependent task.""" description: Optional[str] = None @@ -7993,7 +8024,7 @@ class Task: responding. We suggest running jobs and tasks on new clusters for greater reliability""" for_each_task: Optional[ForEachTask] = None - """The task executes a nested task for every input provided when the `for_each_task` field is + """The task executes a nested task for every input provided when the ``for_each_task`` field is present.""" gen_ai_compute_task: Optional[GenAiComputeTask] = None @@ -8002,7 +8033,7 @@ class Task: job_cluster_key: Optional[str] = None """If job_cluster_key, this task is executed reusing the cluster specified in - `job.settings.job_clusters`.""" + ``job.settings.job_clusters``.""" libraries: Optional[List[compute.Library]] = None """An optional list of libraries to be installed on the cluster. The default value is an empty @@ -8010,9 +8041,9 @@ class Task: max_retries: Optional[int] = None """An optional maximum number of times to retry an unsuccessful run. A run is considered to be - unsuccessful if it completes with the `FAILED` result_state or `INTERNAL_ERROR` - `life_cycle_state`. The value `-1` means to retry indefinitely and the value `0` means to never - retry.""" + unsuccessful if it completes with the ``FAILED`` result_state or ``INTERNAL_ERROR`` + ``life_cycle_state``. The value ``-1`` means to retry indefinitely and the value ``0`` means to + never retry.""" min_retry_interval_millis: Optional[int] = None """An optional minimal interval in milliseconds between the start of the failed run and the @@ -8022,24 +8053,24 @@ class Task: """If new_cluster, a description of a new cluster that is created for each run.""" notebook_task: Optional[NotebookTask] = None - """The task runs a notebook when the `notebook_task` field is present.""" + """The task runs a notebook when the ``notebook_task`` field is present.""" notification_settings: Optional[TaskNotificationSettings] = None """Optional notification settings that are used when sending notifications to each of the - `email_notifications` and `webhook_notifications` for this task.""" + ``email_notifications`` and ``webhook_notifications`` for this task.""" pipeline_task: Optional[PipelineTask] = None - """The task triggers a pipeline update when the `pipeline_task` field is present. Only pipelines + """The task triggers a pipeline update when the ``pipeline_task`` field is present. Only pipelines configured to use triggered more are supported.""" power_bi_task: Optional[PowerBiTask] = None - """The task triggers a Power BI semantic model update when the `power_bi_task` field is present.""" + """The task triggers a Power BI semantic model update when the ``power_bi_task`` field is present.""" python_operator_task: Optional[PythonOperatorTask] = None """The task runs a Python operator task.""" python_wheel_task: Optional[PythonWheelTask] = None - """The task runs a Python wheel when the `python_wheel_task` field is present.""" + """The task runs a Python wheel when the ``python_wheel_task`` field is present.""" retry_on_timeout: Optional[bool] = None """An optional policy to specify whether to retry a job when it times out. The default behavior is @@ -8049,31 +8080,32 @@ class Task: """An optional value specifying the condition determining whether the task is run once its dependencies have been completed. - * `ALL_SUCCESS`: All dependencies have executed and succeeded * `AT_LEAST_ONE_SUCCESS`: At least - one dependency has succeeded * `NONE_FAILED`: None of the dependencies have failed and at least - one was executed * `ALL_DONE`: All dependencies have been completed * `AT_LEAST_ONE_FAILED`: At - least one dependency failed * `ALL_FAILED`: ALl dependencies have failed""" + - ``ALL_SUCCESS``: All dependencies have executed and succeeded + - ``AT_LEAST_ONE_SUCCESS``: At least one dependency has succeeded + - ``NONE_FAILED``: None of the dependencies have failed and at least one was executed + - ``ALL_DONE``: All dependencies have been completed + - ``AT_LEAST_ONE_FAILED``: At least one dependency failed + - ``ALL_FAILED``: ALl dependencies have failed""" run_job_task: Optional[RunJobTask] = None - """The task triggers another job when the `run_job_task` field is present.""" + """The task triggers another job when the ``run_job_task`` field is present.""" spark_jar_task: Optional[SparkJarTask] = None - """The task runs a JAR when the `spark_jar_task` field is present.""" + """The task runs a JAR when the ``spark_jar_task`` field is present.""" spark_python_task: Optional[SparkPythonTask] = None - """The task runs a Python file when the `spark_python_task` field is present.""" + """The task runs a Python file when the ``spark_python_task`` field is present.""" spark_submit_task: Optional[SparkSubmitTask] = None """(Legacy) The task runs the spark-submit script when the spark_submit_task field is present. - Databricks recommends using the spark_jar_task instead; see [Spark Submit task for - jobs](/jobs/spark-submit).""" + Databricks recommends using the spark_jar_task instead; see Spark Submit task for jobs.""" sql_task: Optional[SqlTask] = None """The task runs a SQL query or file, or it refreshes a SQL alert or a legacy SQL dashboard when - the `sql_task` field is present.""" + the ``sql_task`` field is present.""" timeout_seconds: Optional[int] = None - """An optional timeout applied to each run of this job task. A value of `0` means no timeout.""" + """An optional timeout applied to each run of this job task. A value of ``0`` means no timeout.""" webhook_notifications: Optional[WebhookNotifications] = None """A collection of system notification IDs to notify when runs of this task begin or complete. The @@ -8327,20 +8359,21 @@ def from_dict(cls, d: Dict[str, Any]) -> TaskDependency: @dataclass class TaskEmailNotifications: no_alert_for_skipped_runs: Optional[bool] = None - """If true, do not send email to recipients specified in `on_failure` if the run is skipped. This - field is `deprecated`. Please use the `notification_settings.no_alert_for_skipped_runs` field.""" + """If true, do not send email to recipients specified in ``on_failure`` if the run is skipped. This + field is ``deprecated``. Please use the ``notification_settings.no_alert_for_skipped_runs`` + field.""" on_duration_warning_threshold_exceeded: Optional[List[str]] = None """A list of email addresses to be notified when the duration of a run exceeds the threshold - specified for the `RUN_DURATION_SECONDS` metric in the `health` field. If no rule for the - `RUN_DURATION_SECONDS` metric is specified in the `health` field for the job, notifications are - not sent.""" + specified for the ``RUN_DURATION_SECONDS`` metric in the ``health`` field. If no rule for the + ``RUN_DURATION_SECONDS`` metric is specified in the ``health`` field for the job, notifications + are not sent.""" on_failure: Optional[List[str]] = None """A list of email addresses to be notified when a run unsuccessfully completes. A run is - considered to have completed unsuccessfully if it ends with an `INTERNAL_ERROR` - `life_cycle_state` or a `FAILED`, or `TIMED_OUT` result_state. If this is not specified on job - creation, reset, or update the list is empty, and notifications are not sent.""" + considered to have completed unsuccessfully if it ends with an ``INTERNAL_ERROR`` + ``life_cycle_state`` or a ``FAILED``, or ``TIMED_OUT`` result_state. If this is not specified on + job creation, reset, or update the list is empty, and notifications are not sent.""" on_start: Optional[List[str]] = None """A list of email addresses to be notified when a run begins. If not specified on job creation, @@ -8348,16 +8381,17 @@ class TaskEmailNotifications: on_streaming_backlog_exceeded: Optional[List[str]] = None """A list of email addresses to notify when any streaming backlog thresholds are exceeded for any - stream. Streaming backlog thresholds can be set in the `health` field using the following - metrics: `STREAMING_BACKLOG_BYTES`, `STREAMING_BACKLOG_RECORDS`, `STREAMING_BACKLOG_SECONDS`, or - `STREAMING_BACKLOG_FILES`. Alerting is based on the 10-minute average of these metrics. If the - issue persists, notifications are resent every 30 minutes.""" + stream. Streaming backlog thresholds can be set in the ``health`` field using the following + metrics: ``STREAMING_BACKLOG_BYTES``, ``STREAMING_BACKLOG_RECORDS``, + ``STREAMING_BACKLOG_SECONDS``, or ``STREAMING_BACKLOG_FILES``. Alerting is based on the + 10-minute average of these metrics. If the issue persists, notifications are resent every 30 + minutes.""" on_success: Optional[List[str]] = None """A list of email addresses to be notified when a run successfully completes. A run is considered - to have completed successfully if it ends with a `TERMINATED` `life_cycle_state` and a `SUCCESS` - result_state. If not specified on job creation, reset, or update, the list is empty, and - notifications are not sent.""" + to have completed successfully if it ends with a ``TERMINATED`` ``life_cycle_state`` and a + ``SUCCESS`` result_state. If not specified on job creation, reset, or update, the list is empty, + and notifications are not sent.""" def as_dict(self) -> dict: """Serializes the TaskEmailNotifications into a dictionary suitable for use as a JSON request body.""" @@ -8409,16 +8443,16 @@ def from_dict(cls, d: Dict[str, Any]) -> TaskEmailNotifications: @dataclass class TaskNotificationSettings: alert_on_last_attempt: Optional[bool] = None - """If true, do not send notifications to recipients specified in `on_start` for the retried runs - and do not send notifications to recipients specified in `on_failure` until the last retry of + """If true, do not send notifications to recipients specified in ``on_start`` for the retried runs + and do not send notifications to recipients specified in ``on_failure`` until the last retry of the run.""" no_alert_for_canceled_runs: Optional[bool] = None - """If true, do not send notifications to recipients specified in `on_failure` if the run is + """If true, do not send notifications to recipients specified in ``on_failure`` if the run is canceled.""" no_alert_for_skipped_runs: Optional[bool] = None - """If true, do not send notifications to recipients specified in `on_failure` if the run is + """If true, do not send notifications to recipients specified in ``on_failure`` if the run is skipped.""" def as_dict(self) -> dict: @@ -8454,10 +8488,12 @@ def from_dict(cls, d: Dict[str, Any]) -> TaskNotificationSettings: class TaskRetryMode(Enum): - """task retry mode of the continuous job * NEVER: The failed task will not be retried. * - ON_FAILURE: Retry a failed task if at least one other task in the job is still running its first - attempt. When this condition is no longer met or the retry limit is reached, the job run is - cancelled and a new run is started.""" + """task retry mode of the continuous job + + - NEVER: The failed task will not be retried. + - ON_FAILURE: Retry a failed task if at least one other task in the job is still running its + first attempt. When this condition is no longer met or the retry limit is reached, the job run + is cancelled and a new run is started.""" NEVER = "NEVER" ON_FAILURE = "ON_FAILURE" @@ -8465,45 +8501,60 @@ class TaskRetryMode(Enum): class TerminationCodeCode(Enum): """The code indicates why the run was terminated. Additional codes might be introduced in future - releases. * `SUCCESS`: The run was completed successfully. * `SUCCESS_WITH_FAILURES`: The run - was completed successfully but some child runs failed. * `USER_CANCELED`: The run was - successfully canceled during execution by a user. * `CANCELED`: The run was canceled during - execution by the Databricks platform; for example, if the maximum run duration was exceeded. * - `SKIPPED`: Run was never executed, for example, if the upstream task run failed, the dependency - type condition was not met, or there were no material tasks to execute. * `INTERNAL_ERROR`: The - run encountered an unexpected error. Refer to the state message for further details. * - `DRIVER_ERROR`: The run encountered an error while communicating with the Spark Driver. * - `CLUSTER_ERROR`: The run failed due to a cluster error. Refer to the state message for further - details. * `REPOSITORY_CHECKOUT_FAILED`: Failed to complete the checkout due to an error when - communicating with the third party service. * `INVALID_CLUSTER_REQUEST`: The run failed because - it issued an invalid request to start the cluster. * `WORKSPACE_RUN_LIMIT_EXCEEDED`: The - workspace has reached the quota for the maximum number of concurrent active runs. Consider - scheduling the runs over a larger time frame. * `FEATURE_DISABLED`: The run failed because it - tried to access a feature unavailable for the workspace. * `CLUSTER_REQUEST_LIMIT_EXCEEDED`: The - number of cluster creation, start, and upsize requests have exceeded the allotted rate limit. - Consider spreading the run execution over a larger time frame. * `STORAGE_ACCESS_ERROR`: The run - failed due to an error when accessing the customer blob storage. Refer to the state message for - further details. * `RUN_EXECUTION_ERROR`: The run was completed with task failures. For more - details, refer to the state message or run output. * `UNAUTHORIZED_ERROR`: The run failed due to - a permission issue while accessing a resource. Refer to the state message for further details. * - `LIBRARY_INSTALLATION_ERROR`: The run failed while installing the user-requested library. Refer - to the state message for further details. The causes might include, but are not limited to: The - provided library is invalid, there are insufficient permissions to install the library, and so - forth. * `MAX_CONCURRENT_RUNS_EXCEEDED`: The scheduled run exceeds the limit of maximum - concurrent runs set for the job. * `MAX_SPARK_CONTEXTS_EXCEEDED`: The run is scheduled on a - cluster that has already reached the maximum number of contexts it is configured to create. See: - [Link]. * `RESOURCE_NOT_FOUND`: A resource necessary for run execution does not exist. Refer to - the state message for further details. * `INVALID_RUN_CONFIGURATION`: The run failed due to an - invalid configuration. Refer to the state message for further details. * `CLOUD_FAILURE`: The - run failed due to a cloud provider issue. Refer to the state message for further details. * - `MAX_JOB_QUEUE_SIZE_EXCEEDED`: The run was skipped due to reaching the job level queue size - limit. * `DISABLED`: The run was never executed because it was disabled explicitly by the user. - * `BREAKING_CHANGE`: Run failed because of an intentional breaking change in Spark, but it will - be retried with a mitigation config. * `CLUSTER_TERMINATED_BY_USER`: The run failed because the - externally managed cluster entered an unusable state, likely due to the user terminating or - restarting it outside the jobs service. - - [Link]: https://kb.databricks.com/en_US/notebooks/too-many-execution-contexts-are-open-right-now""" + releases. + + - ``SUCCESS``: The run was completed successfully. + - ``SUCCESS_WITH_FAILURES``: The run was completed successfully but some child runs failed. + - ``USER_CANCELED``: The run was successfully canceled during execution by a user. + - ``CANCELED``: The run was canceled during execution by the Databricks platform; for example, + if the maximum run duration was exceeded. + - ``SKIPPED``: Run was never executed, for example, if the upstream task run failed, the + dependency type condition was not met, or there were no material tasks to execute. + - ``INTERNAL_ERROR``: The run encountered an unexpected error. Refer to the state message for + further details. + - ``DRIVER_ERROR``: The run encountered an error while communicating with the Spark Driver. + - ``CLUSTER_ERROR``: The run failed due to a cluster error. Refer to the state message for + further details. + - ``REPOSITORY_CHECKOUT_FAILED``: Failed to complete the checkout due to an error when + communicating with the third party service. + - ``INVALID_CLUSTER_REQUEST``: The run failed because it issued an invalid request to start the + cluster. + - ``WORKSPACE_RUN_LIMIT_EXCEEDED``: The workspace has reached the quota for the maximum number + of concurrent active runs. Consider scheduling the runs over a larger time frame. + - ``FEATURE_DISABLED``: The run failed because it tried to access a feature unavailable for the + workspace. + - ``CLUSTER_REQUEST_LIMIT_EXCEEDED``: The number of cluster creation, start, and upsize requests + have exceeded the allotted rate limit. Consider spreading the run execution over a larger time + frame. + - ``STORAGE_ACCESS_ERROR``: The run failed due to an error when accessing the customer blob + storage. Refer to the state message for further details. + - ``RUN_EXECUTION_ERROR``: The run was completed with task failures. For more details, refer to + the state message or run output. + - ``UNAUTHORIZED_ERROR``: The run failed due to a permission issue while accessing a resource. + Refer to the state message for further details. + - ``LIBRARY_INSTALLATION_ERROR``: The run failed while installing the user-requested library. + Refer to the state message for further details. The causes might include, but are not limited + to: The provided library is invalid, there are insufficient permissions to install the + library, and so forth. + - ``MAX_CONCURRENT_RUNS_EXCEEDED``: The scheduled run exceeds the limit of maximum concurrent + runs set for the job. + - ``MAX_SPARK_CONTEXTS_EXCEEDED``: The run is scheduled on a cluster that has already reached + the maximum number of contexts it is configured to create. See: `Link + `__. + - ``RESOURCE_NOT_FOUND``: A resource necessary for run execution does not exist. Refer to the + state message for further details. + - ``INVALID_RUN_CONFIGURATION``: The run failed due to an invalid configuration. Refer to the + state message for further details. + - ``CLOUD_FAILURE``: The run failed due to a cloud provider issue. Refer to the state message + for further details. + - ``MAX_JOB_QUEUE_SIZE_EXCEEDED``: The run was skipped due to reaching the job level queue size + limit. + - ``DISABLED``: The run was never executed because it was disabled explicitly by the user. + - ``BREAKING_CHANGE``: Run failed because of an intentional breaking change in Spark, but it + will be retried with a mitigation config. + - ``CLUSTER_TERMINATED_BY_USER``: The run failed because the externally managed cluster entered + an unusable state, likely due to the user terminating or restarting it outside the jobs + service.""" BREAKING_CHANGE = "BREAKING_CHANGE" BUDGET_POLICY_LIMIT_EXCEEDED = "BUDGET_POLICY_LIMIT_EXCEEDED" @@ -8576,13 +8627,12 @@ def from_dict(cls, d: Dict[str, Any]) -> TerminationDetails: class TerminationTypeType(Enum): - """* `SUCCESS`: The run terminated without any issues * `INTERNAL_ERROR`: An error occurred in the - Databricks platform. Please look at the [status page] or contact support if the issue persists. - * `CLIENT_ERROR`: The run was terminated because of an error caused by user input or the job - configuration. * `CLOUD_FAILURE`: The run was terminated because of an issue with your cloud - provider. - - [status page]: https://status.databricks.com/""" + """- ``SUCCESS``: The run terminated without any issues + - ``INTERNAL_ERROR``: An error occurred in the Databricks platform. Please look at the `status + page `__ or contact support if the issue persists. + - ``CLIENT_ERROR``: The run was terminated because of an error caused by user input or the job + configuration. + - ``CLOUD_FAILURE``: The run was terminated because of an issue with your cloud provider.""" CLIENT_ERROR = "CLIENT_ERROR" CLOUD_FAILURE = "CLOUD_FAILURE" @@ -8710,15 +8760,18 @@ def from_dict(cls, d: Dict[str, Any]) -> TriggerStateProto: class TriggerType(Enum): """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. * `CONTINUOUS`: Indicates a run that is - triggered by a continuous job. * `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. - * `MODEL`: Indicates a run that is triggered by a model 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. + - ``CONTINUOUS``: Indicates a run that is triggered by a continuous job. + - ``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. + - ``MODEL``: Indicates a run that is triggered by a model update.""" CONTINUOUS = "CONTINUOUS" CONTINUOUS_RESTART = "CONTINUOUS_RESTART" @@ -8771,15 +8824,17 @@ def from_dict(cls, d: Dict[str, Any]) -> ViewItem: class ViewType(Enum): - """* `NOTEBOOK`: Notebook view item. * `DASHBOARD`: Dashboard view item.""" + """- ``NOTEBOOK``: Notebook view item. + - ``DASHBOARD``: Dashboard view item.""" DASHBOARD = "DASHBOARD" NOTEBOOK = "NOTEBOOK" class ViewsToExport(Enum): - """* `CODE`: Code view of the notebook. * `DASHBOARDS`: All dashboard views of the notebook. * - `ALL`: All views of the notebook.""" + """- ``CODE``: Code view of the notebook. + - ``DASHBOARDS``: All dashboard views of the notebook. + - ``ALL``: All views of the notebook.""" ALL = "ALL" CODE = "CODE" @@ -8814,28 +8869,29 @@ def from_dict(cls, d: Dict[str, Any]) -> Webhook: class WebhookNotifications: on_duration_warning_threshold_exceeded: Optional[List[Webhook]] = None """An optional list of system notification IDs to call when the duration of a run exceeds the - threshold specified for the `RUN_DURATION_SECONDS` metric in the `health` field. A maximum of 3 - destinations can be specified for the `on_duration_warning_threshold_exceeded` property.""" + threshold specified for the ``RUN_DURATION_SECONDS`` metric in the ``health`` field. A maximum + of 3 destinations can be specified for the ``on_duration_warning_threshold_exceeded`` property.""" on_failure: Optional[List[Webhook]] = None """An optional list of system notification IDs to call when the run fails. A maximum of 3 - destinations can be specified for the `on_failure` property.""" + destinations can be specified for the ``on_failure`` property.""" on_start: Optional[List[Webhook]] = None """An optional list of system notification IDs to call when the run starts. A maximum of 3 - destinations can be specified for the `on_start` property.""" + destinations can be specified for the ``on_start`` property.""" on_streaming_backlog_exceeded: Optional[List[Webhook]] = None """An optional list of system notification IDs to call when any streaming backlog thresholds are - exceeded for any stream. Streaming backlog thresholds can be set in the `health` field using the - following metrics: `STREAMING_BACKLOG_BYTES`, `STREAMING_BACKLOG_RECORDS`, - `STREAMING_BACKLOG_SECONDS`, or `STREAMING_BACKLOG_FILES`. Alerting is based on the 10-minute - average of these metrics. If the issue persists, notifications are resent every 30 minutes. A - maximum of 3 destinations can be specified for the `on_streaming_backlog_exceeded` property.""" + exceeded for any stream. Streaming backlog thresholds can be set in the ``health`` field using + the following metrics: ``STREAMING_BACKLOG_BYTES``, ``STREAMING_BACKLOG_RECORDS``, + ``STREAMING_BACKLOG_SECONDS``, or ``STREAMING_BACKLOG_FILES``. Alerting is based on the + 10-minute average of these metrics. If the issue persists, notifications are resent every 30 + minutes. A maximum of 3 destinations can be specified for the ``on_streaming_backlog_exceeded`` + property.""" on_success: Optional[List[Webhook]] = None """An optional list of system notification IDs to call when the run completes successfully. A - maximum of 3 destinations can be specified for the `on_success` property.""" + maximum of 3 destinations can be specified for the ``on_success`` property.""" def as_dict(self) -> dict: """Serializes the WebhookNotifications into a dictionary suitable for use as a JSON request body.""" @@ -8915,12 +8971,11 @@ class JobsAPI: scheduling system. You can implement job tasks using notebooks, JARS, Spark Declarative 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 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.""" def __init__(self, api_client): self._api = api_client @@ -9052,11 +9107,11 @@ def create( 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 + 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. + 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) @@ -9064,8 +9119,8 @@ def create( :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. + - ``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. @@ -9077,16 +9132,16 @@ def create( 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"`. + 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. + 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. + used, ``git_source`` must be defined on the job. :param health: :class:`JobsHealthRules` (optional) :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 @@ -9099,12 +9154,12 @@ def create( 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. + 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. + ``email_notifications`` and ``webhook_notifications`` for this job. :param parameters: List[:class:`JobParameterDefinition`] (optional) Job-level parameter definitions :param performance_target: :class:`PerformanceTarget` (optional) @@ -9112,18 +9167,18 @@ def create( cost-efficiency for the run. The performance target does not apply to tasks that run on Serverless GPU compute. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * `PERFORMANCE_OPTIMIZED`: - Prioritizes fast startup and execution times through rapid scaling and optimized cluster - performance. + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling and + optimized cluster performance. :param queue: :class:`QueueSettings` (optional) The queue settings of the job. :param run_as: :class:`JobRunAs` (optional) The user or service principal that the job runs as, if specified in the request. This field - indicates the explicit configuration of `run_as` for the job. To find the value in all cases, - explicit or implicit, use `run_as_user_name`. + indicates the explicit configuration of ``run_as`` for the job. To find the value in all cases, + explicit or implicit, use ``run_as_user_name``. :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`. + 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 @@ -9132,17 +9187,17 @@ def create( A list of task specifications to be executed by this job. It supports up to 1000 elements in write endpoints (:method:jobs/create, :method:jobs/reset, :method:jobs/update, :method:jobs/submit). Read endpoints return only 100 tasks. If more than 100 tasks are available, you can paginate through them - using :method:jobs/get. Use the `next_page_token` field at the object root to determine if more + using :method:jobs/get. Use the ``next_page_token`` field at the object root to determine if more results are available. :param timeout_seconds: int (optional) - An optional timeout applied to each run of this job. A value of `0` means no timeout. + 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`. + ``runNow``. :param usage_policy_id: str (optional) The id of the user specified usage policy to use for this job. If not specified, a default usage - policy may be applied when creating or modifying the job. See `effective_usage_policy_id` for the + policy may be applied when creating or modifying the job. See ``effective_usage_policy_id`` for the usage policy used by this workload. :param webhook_notifications: :class:`WebhookNotifications` (optional) A collection of system notification IDs to notify when runs of this job begin or complete. @@ -9292,18 +9347,18 @@ def get( """Retrieves the details for a single job. Large arrays in the results will be paginated when they exceed 100 elements. A request for a single - job will return all properties for that job, and the first 100 elements of array properties (`tasks`, - `job_clusters`, `environments` and `parameters`). Use the `next_page_token` field to check for more - results and pass its value as the `page_token` in subsequent requests. If any array properties have - more than 100 elements, additional results will be returned on subsequent requests. Arrays without - additional results will be empty on later pages. + job will return all properties for that job, and the first 100 elements of array properties + (``tasks``, ``job_clusters``, ``environments`` and ``parameters``). Use the ``next_page_token`` field + to check for more results and pass its value as the ``page_token`` in subsequent requests. If any + array properties have more than 100 elements, additional results will be returned on subsequent + requests. Arrays without additional results will be empty on later pages. :param job_id: int The canonical identifier of the job to retrieve information about. This field is required. :param include_trigger_state: bool (optional) Flag that indicates that trigger state should be included in the response. :param page_token: str (optional) - Use `next_page_token` returned from the previous GetJob response to request the next page of the + Use ``next_page_token`` returned from the previous GetJob response to request the next page of the job's array properties. :returns: :class:`Job` @@ -9378,11 +9433,11 @@ def get_run( """Retrieves the metadata of a run. Large arrays in the results will be paginated when they exceed 100 elements. A request for a single - run will return all properties for that run, and the first 100 elements of array properties (`tasks`, - `job_clusters`, `job_parameters` and `repair_history`). Use the next_page_token field to check for - more results and pass its value as the page_token in subsequent requests. If any array properties have - more than 100 elements, additional results will be returned on subsequent requests. Arrays without - additional results will be empty on later pages. + run will return all properties for that run, and the first 100 elements of array properties + (``tasks``, ``job_clusters``, ``job_parameters`` and ``repair_history``). Use the next_page_token + field to check for more results and pass its value as the page_token in subsequent requests. If any + array properties have more than 100 elements, additional results will be returned on subsequent + requests. Arrays without additional results will be empty on later pages. :param run_id: int The canonical identifier of the run for which to retrieve the metadata. This field is required. @@ -9391,7 +9446,7 @@ def get_run( :param include_resolved_values: bool (optional) Whether to include resolved parameter values in the response. :param page_token: str (optional) - Use `next_page_token` returned from the previous GetRun response to request the next page of the + Use ``next_page_token`` returned from the previous GetRun response to request the next page of the run's array properties. :returns: :class:`Run` @@ -9419,12 +9474,12 @@ def get_run( def get_run_output(self, run_id: int) -> 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 + 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 + 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 @@ -9468,10 +9523,10 @@ def list( 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. + 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. + 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` """ @@ -9521,12 +9576,12 @@ def list_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`. + 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`. + 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. Note that only the first 100 elements will be shown. Use :method:jobs/getrun to paginate through all tasks and clusters. @@ -9537,18 +9592,18 @@ def list_runs( 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. + 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. + 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. + 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. + 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` """ @@ -9616,99 +9671,99 @@ def repair_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"]` - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + 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"]`` - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :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. - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + 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. + + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :param job_parameters: Dict[str,str] (optional) - Job-level parameters used in the run. for example `"param": "overriding_val"` + 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. + 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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - The JSON representation of this field (for example `{"notebook_params":{"name":"john - doe","age":"35"}}`) cannot exceed 10,000 bytes. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. - [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + The JSON representation of this field (for example ``{"notebook_params":{"name":"john + doe","age":"35"}}``) cannot exceed 10,000 bytes. :param performance_target: :class:`PerformanceTarget` (optional) The performance mode on a serverless job. The performance target determines the level of compute performance or cost-efficiency for the run. This field overrides the performance target defined on the job level. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * `PERFORMANCE_OPTIMIZED`: - Prioritizes fast startup and execution times through rapid scaling and optimized cluster - performance. + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling and + optimized cluster performance. :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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown :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. + 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`. + 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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown :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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :returns: Long-running operation waiter for :class:`Run`. @@ -9801,16 +9856,15 @@ def repair_run_and_wait( ).result(timeout=timeout) def reset(self, job_id: int, new_settings: JobSettings): - """Overwrite all settings for the given job. Use the [_Update_ endpoint](:method:jobs/update) to update - job settings partially. + """Overwrite all settings for the given job. Use the *Update* endpoint 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. + Changes to the field ``JobBaseSettings.timeout_seconds`` are applied to active runs. Changes to + other fields are applied to future runs only. """ @@ -9848,17 +9902,17 @@ def run_now( spark_submit_params: Optional[List[str]] = None, sql_params: Optional[Dict[str, str]] = None, ) -> Wait[Run]: - """Run a job and return the `run_id` of the triggered 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"]` + 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"]`` - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :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 @@ -9869,37 +9923,35 @@ def run_now( 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 + For more information, see `How to ensure idempotency for jobs + `__. :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. - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + 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. + + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :param job_parameters: Dict[str,str] (optional) - Job-level parameters used in the run. for example `"param": "overriding_val"` + 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. + 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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. - - The JSON representation of this field (for example `{"notebook_params":{"name":"john - doe","age":"35"}}`) cannot exceed 10,000 bytes. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. - [dbutils.widgets.get]: https://docs.databricks.com/dev-tools/databricks-utils.html - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + The JSON representation of this field (for example ``{"notebook_params":{"name":"john + doe","age":"35"}}``) cannot exceed 10,000 bytes. :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. @@ -9908,52 +9960,52 @@ def run_now( performance or cost-efficiency for the run. This field overrides the performance target defined on the job level. - * `STANDARD`: Enables cost-efficient execution of serverless workloads. * `PERFORMANCE_OPTIMIZED`: - Prioritizes fast startup and execution times through rapid scaling and optimized cluster - performance. + - ``STANDARD``: Enables cost-efficient execution of serverless workloads. + - ``PERFORMANCE_OPTIMIZED``: Prioritizes fast startup and execution times through rapid scaling and + optimized cluster performance. :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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown :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. + 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. - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. 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. - - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown :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. - - ⚠ **Deprecation note** Use [job parameters] to pass information down to tasks. + 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. - [job parameters]: https://docs.databricks.com/jobs/job-parameters.html#job-parameter-pushdown + ⚠ **Deprecation note** Use `job parameters + `__ to pass information + down to tasks. :returns: Long-running operation waiter for :class:`Run`. @@ -10089,14 +10141,14 @@ def submit( webhook_notifications: Optional[WebhookNotifications] = None, ) -> Wait[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. + 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. **Important:** Jobs submitted using this endpoint are not saved as a job. They do not show up in the Jobs UI, and do not retry when they fail. Because they are not saved, Databricks cannot auto-optimize serverless compute in case of failure. If your job fails, you may want to use classic compute to - specify the compute needs for the job. Alternatively, use the `POST /jobs/create` and `POST - /jobs/run-now` endpoints to create and run a saved job. + specify the compute needs for the job. Alternatively, use the ``POST /jobs/create`` and ``POST + /jobs/run-now`` endpoints to create and run a saved job. :param access_control_list: List[:class:`JobAccessControlRequest`] (optional) List of permissions to set on the job. @@ -10111,11 +10163,11 @@ def submit( 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. + 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. + used, ``git_source`` must be defined on the job. :param health: :class:`JobsHealthRules` (optional) :param idempotency_token: str (optional) An optional token that can be used to guarantee the idempotency of job run requests. If a run with @@ -10127,22 +10179,21 @@ def submit( 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 + For more information, see `How to ensure idempotency for jobs + `__. :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. + ``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`. + 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. + An optional timeout applied to each run of this job. A value of ``0`` means no timeout. :param usage_policy_id: str (optional) The user specified id of the usage policy to use for this one-time run. If not specified, a default usage policy may be applied when creating or modifying the job. @@ -10242,24 +10293,24 @@ def submit_and_wait( def update( self, job_id: int, *, fields_to_remove: Optional[List[str]] = None, new_settings: Optional[JobSettings] = None ): - """Add, update, or remove specific settings of an existing job. Use the [_Reset_ - endpoint](:method:jobs/reset) to overwrite all job settings. + """Add, update, or remove specific settings of an existing job. Use the *Reset* endpoint 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. + 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 + 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. + 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 + Changes to the field ``JobSettings.timeout_seconds`` are applied to active runs. Changes to other fields are applied to future runs only. @@ -10328,7 +10379,7 @@ def __init__(self, api_client): def enforce_compliance( self, job_id: int, *, validate_only: Optional[bool] = None ) -> EnforcePolicyComplianceResponse: - """Updates a job so the job clusters that are created when running the job (specified in `new_cluster`) + """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. @@ -10396,7 +10447,7 @@ def list_compliance( 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`. + ``next_page_token`` or ``prev_page_token``. :returns: Iterator over :class:`JobCompliance` """ diff --git a/databricks/sdk/service/knowledgeassistants.py b/databricks/sdk/service/knowledgeassistants.py index dd83d0d33..51c3ee8c4 100755 --- a/databricks/sdk/service/knowledgeassistants.py +++ b/databricks/sdk/service/knowledgeassistants.py @@ -735,7 +735,7 @@ class ListKnowledgeAssistantsResponse: knowledge_assistants: Optional[List[KnowledgeAssistant]] = None next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" def as_dict(self) -> dict: @@ -1058,8 +1058,8 @@ def list_examples( The maximum number of examples to return. If unspecified, at most 100 examples will be returned. The maximum value is 100; values above 100 will be coerced to 100. :param page_token: str (optional) - A page token, received from a previous `ListExamples` call. Provide this to retrieve the subsequent - page. If unspecified, the first page will be returned. + A page token, received from a previous ``ListExamples`` call. Provide this to retrieve the + subsequent page. If unspecified, the first page will be returned. :returns: Iterator over :class:`Example` """ @@ -1095,8 +1095,8 @@ def list_knowledge_assistants( The maximum number of knowledge assistants to return. If unspecified, at most 100 knowledge assistants will be returned. The maximum value is 100; values above 100 will be coerced to 100. :param page_token: str (optional) - A page token, received from a previous `ListKnowledgeAssistants` call. Provide this to retrieve the - subsequent page. If unspecified, the first page will be returned. + A page token, received from a previous ``ListKnowledgeAssistants`` call. Provide this to retrieve + the subsequent page. If unspecified, the first page will be returned. :returns: Iterator over :class:`KnowledgeAssistant` """ @@ -1219,8 +1219,11 @@ def update_example(self, name: str, example: Example, update_mask: FieldMask) -> knowledge-assistants/{knowledge_assistant_id}/examples/{example_id} :param example: :class:`Example` :param update_mask: FieldMask - Comma-delimited list of fields to update on the example. Allowed values: `question`, `guidelines`. - Examples: - `question` - `question,guidelines` + Comma-delimited list of fields to update on the example. Allowed values: ``question``, + ``guidelines``. Examples: + + - ``question`` + - ``question,guidelines`` :returns: :class:`Example` """ @@ -1253,8 +1256,11 @@ def update_knowledge_assistant( annotations on Knowledge Assistant fields describe create-time requirements and do not mean all those fields are required for update. :param update_mask: FieldMask - Comma-delimited list of fields to update on the Knowledge Assistant. Allowed values: `display_name`, - `description`, `instructions`. Examples: - `display_name` - `description,instructions` + Comma-delimited list of fields to update on the Knowledge Assistant. Allowed values: + ``display_name``, ``description``, ``instructions``. Examples: + + - ``display_name`` + - ``description,instructions`` :returns: :class:`KnowledgeAssistant` """ @@ -1288,8 +1294,11 @@ def update_knowledge_source( annotations on Knowledge Source fields describe create-time requirements and do not mean all those fields are required for update. :param update_mask: FieldMask - Comma-delimited list of fields to update on the Knowledge Source. Allowed values: `display_name`, - `description`. Examples: - `display_name` - `display_name,description` + Comma-delimited list of fields to update on the Knowledge Source. Allowed values: ``display_name``, + ``description``. Examples: + + - ``display_name`` + - ``display_name,description`` :returns: :class:`KnowledgeSource` """ diff --git a/databricks/sdk/service/marketplace.py b/databricks/sdk/service/marketplace.py index 701055032..73b7b75f9 100755 --- a/databricks/sdk/service/marketplace.py +++ b/databricks/sdk/service/marketplace.py @@ -847,6 +847,7 @@ class FileParent: file_parent_type: Optional[FileParentType] = None parent_id: Optional[str] = None + """TODO make the following fields required""" def as_dict(self) -> dict: """Serializes the FileParent into a dictionary suitable for use as a JSON request body.""" @@ -1701,7 +1702,7 @@ class ListingDetail: pricing_model: Optional[str] = None """What the pricing model is (e.g. paid, subscription, paid upfront); should only be present if - cost is paid""" + cost is paid TODO: Not used yet, should deprecate if we will never use it""" privacy_policy_link: Optional[str] = None @@ -1714,9 +1715,10 @@ class ListingDetail: """Listing tags - Simple key value pair to annotate listings. When should I use tags vs dedicated fields? Using tags avoids the need to add new columns in the database for new annotations. However, this should be used sparingly since tags are stored as key value pair. Use tags only: - 1. If the field is optional and won't need to have NOT NULL integrity check 2. The value is - fairly fixed, static and low cardinality (eg. enums). 3. The value won't be used in filters or - joins with other tables.""" + + 1. If the field is optional and won't need to have NOT NULL integrity check + 2. The value is fairly fixed, static and low cardinality (eg. enums). + 3. The value won't be used in filters or joins with other tables.""" terms_of_service: Optional[str] = None @@ -2967,7 +2969,7 @@ def get( def list( self, listing_id: str, *, page_size: Optional[int] = None, page_token: Optional[str] = None ) -> Iterator[ListingFulfillment]: - """Get all listings fulfillments associated with a listing. A _fulfillment_ is a potential installation. + """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. @@ -3162,9 +3164,10 @@ def update( rotate_token: Optional[bool] = None, ) -> UpdateInstallationResponse: """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 + 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 @@ -4279,7 +4282,7 @@ def __init__(self, api_client): self._api = api_client def create(self) -> ProviderAnalyticsDashboard: - """Create provider analytics dashboard. Returns Marketplace specific `id`. Not to be confused with the + """Create provider analytics dashboard. Returns Marketplace specific ``id``. Not to be confused with the Lakeview dashboard id. diff --git a/databricks/sdk/service/ml.py b/databricks/sdk/service/ml.py index 1264fb15e..4d74bb643 100755 --- a/databricks/sdk/service/ml.py +++ b/databricks/sdk/service/ml.py @@ -51,13 +51,10 @@ class Activity: from_stage: Optional[str] = None """Source stage of the transition (if the activity is stage transition related). Valid values are: - * `None`: The initial stage of a model version. - - * `Staging`: Staging or pre-production stage. - - * `Production`: Production stage. - - * `Archived`: Archived stage.""" + - ``None``: The initial stage of a model version. + - ``Staging``: Staging or pre-production stage. + - ``Production``: Production stage. + - ``Archived``: Archived stage.""" id: Optional[str] = None """Unique identifier for the object.""" @@ -66,20 +63,17 @@ class Activity: """Time of the object at last update, as a Unix timestamp in milliseconds.""" system_comment: Optional[str] = None - """Comment made by system, for example explaining an activity of type `SYSTEM_TRANSITION`. It + """Comment made by system, for example explaining an activity of type ``SYSTEM_TRANSITION``. It usually describes a side effect, such as a version being archived as part of another version's stage transition, and may not be returned for some activity types.""" to_stage: Optional[str] = None """Target stage of the transition (if the activity is stage transition related). Valid values are: - * `None`: The initial stage of a model version. - - * `Staging`: Staging or pre-production stage. - - * `Production`: Production stage. - - * `Archived`: Archived stage.""" + - ``None``: The initial stage of a model version. + - ``Staging``: Staging or pre-production stage. + - ``Production``: Production stage. + - ``Archived``: Archived stage.""" user_id: Optional[str] = None """The username of the user that created the object.""" @@ -149,15 +143,16 @@ def from_dict(cls, d: Dict[str, Any]) -> Activity: class ActivityAction(Enum): """An action that a user (with sufficient permissions) could take on an activity or comment. - For activities, valid values are: * `APPROVE_TRANSITION_REQUEST`: Approve a transition request + For activities, valid values are: - * `REJECT_TRANSITION_REQUEST`: Reject a transition request + - ``APPROVE_TRANSITION_REQUEST``: Approve a transition request + - ``REJECT_TRANSITION_REQUEST``: Reject a transition request + - ``CANCEL_TRANSITION_REQUEST``: Cancel (delete) a transition request - * `CANCEL_TRANSITION_REQUEST`: Cancel (delete) a transition request + For comments, valid values are: - For comments, valid values are: * `EDIT_COMMENT`: Edit the comment - - * `DELETE_COMMENT`: Delete the comment""" + - ``EDIT_COMMENT``: Edit the comment + - ``DELETE_COMMENT``: Delete the comment""" APPROVE_TRANSITION_REQUEST = "APPROVE_TRANSITION_REQUEST" CANCEL_TRANSITION_REQUEST = "CANCEL_TRANSITION_REQUEST" @@ -167,19 +162,15 @@ class ActivityAction(Enum): class ActivityType(Enum): - """Type of activity. Valid values are: * `APPLIED_TRANSITION`: User applied the corresponding stage - transition. - - * `REQUESTED_TRANSITION`: User requested the corresponding stage transition. - - * `CANCELLED_REQUEST`: User cancelled an existing transition request. + """Type of activity. Valid values are: - * `APPROVED_REQUEST`: User approved the corresponding stage transition. - - * `REJECTED_REQUEST`: User rejected the coressponding stage transition. - - * `SYSTEM_TRANSITION`: For events performed as a side effect, such as archiving existing model - versions in a stage.""" + - ``APPLIED_TRANSITION``: User applied the corresponding stage transition. + - ``REQUESTED_TRANSITION``: User requested the corresponding stage transition. + - ``CANCELLED_REQUEST``: User cancelled an existing transition request. + - ``APPROVED_REQUEST``: User approved the corresponding stage transition. + - ``REJECTED_REQUEST``: User rejected the coressponding stage transition. + - ``SYSTEM_TRANSITION``: For events performed as a side effect, such as archiving existing model + versions in a stage.""" APPLIED_TRANSITION = "APPLIED_TRANSITION" APPROVED_REQUEST = "APPROVED_REQUEST" @@ -452,9 +443,9 @@ class AvgFunction: input: str """The input column from which the average is computed. For Kafka sources, use dot-prefixed path - notation (e.g., "value.amount"). For nested fields, the leaf node name is used. Colon-prefixed - notation (e.g., "value:amount") is supported for backwards compatibility but is deprecated; - migrate to dot notation.""" + notation (e.g., "value.amount"). For nested fields, the leaf node name is used. TODO(FS-939): + Colon-prefixed notation (e.g., "value:amount") is supported for backwards compatibility but is + deprecated; migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the AvgFunction into a dictionary suitable for use as a JSON request body.""" @@ -598,15 +589,16 @@ def from_dict(cls, d: Dict[str, Any]) -> ColumnSelection: class CommentActivityAction(Enum): """An action that a user (with sufficient permissions) could take on an activity or comment. - For activities, valid values are: * `APPROVE_TRANSITION_REQUEST`: Approve a transition request + For activities, valid values are: - * `REJECT_TRANSITION_REQUEST`: Reject a transition request + - ``APPROVE_TRANSITION_REQUEST``: Approve a transition request + - ``REJECT_TRANSITION_REQUEST``: Reject a transition request + - ``CANCEL_TRANSITION_REQUEST``: Cancel (delete) a transition request - * `CANCEL_TRANSITION_REQUEST`: Cancel (delete) a transition request + For comments, valid values are: - For comments, valid values are: * `EDIT_COMMENT`: Edit the comment - - * `DELETE_COMMENT`: Delete the comment""" + - ``EDIT_COMMENT``: Edit the comment + - ``DELETE_COMMENT``: Delete the comment""" APPROVE_TRANSITION_REQUEST = "APPROVE_TRANSITION_REQUEST" CANCEL_TRANSITION_REQUEST = "CANCEL_TRANSITION_REQUEST" @@ -687,7 +679,7 @@ def from_dict(cls, d: Dict[str, Any]) -> CommentObject: @dataclass class ContinuousWindow: - """Deprecated: use RollingWindow with `delay` instead.""" + """Deprecated: use RollingWindow with ``delay`` instead.""" window_duration: str """The duration of the continuous window (must be positive).""" @@ -725,9 +717,9 @@ class CountFunction: input: str """The input column from which the count is computed. For Kafka sources, use dot-prefixed path - notation (e.g., "value.amount"). For nested fields, the leaf node name is used. Colon-prefixed - notation (e.g., "value:amount") is supported for backwards compatibility but is deprecated; - migrate to dot notation.""" + notation (e.g., "value.amount"). For nested fields, the leaf node name is used. TODO(FS-939): + Colon-prefixed notation (e.g., "value:amount") is supported for backwards compatibility but is + deprecated; migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the CountFunction into a dictionary suitable for use as a JSON request body.""" @@ -1458,7 +1450,7 @@ class DeltaTableSource: transformation_sql: Optional[str] = None """A single SQL SELECT expression applied after filter_condition. Should contains all the columns needed (eg. "SELECT *, col_a + col_b AS col_c FROM x.y.z WHERE col_a > 0" would have - `transformation_sql` "*, col_a + col_b AS col_c") If transformation_sql is not provided, all + ``transformation_sql`` "*, col_a + col_b AS col_c") If transformation_sql is not provided, all columns of the delta table are present in the DataSource dataframe.""" def as_dict(self) -> dict: @@ -1510,8 +1502,8 @@ def from_dict(cls, d: Dict[str, Any]) -> DeltaTableSource: @dataclass class DirectMtlsConfig: - """Direct connection configs for mTLS, as Kafka Connections do not support mTLS yet . Temporarily - used until UC Kafka Connections gain mTLS support.""" + """Direct connection configs for mTLS, as Kafka Connections do not support mTLS yet (XTA-18030). + Temporarily used until UC Kafka Connections gain mTLS support.""" bootstrap_servers: str """A comma-separated list of host:port pairs for the Kafka bootstrap servers.""" @@ -1591,9 +1583,9 @@ class EntityColumn: """The name of the entity column. For Kafka sources, use dot-prefixed path notation to reference fields within the key or value schema (e.g., "value.user_id", "key.partition_key"). For nested fields, the leaf node name (e.g., "user_id" from "value.trip_details.user_id") is what will be - present in materialized tables and expected to match at query time. Colon-prefixed notation - (e.g., "value:user_id") is supported for backwards compatibility but is deprecated; migrate to - dot notation.""" + present in materialized tables and expected to match at query time. TODO(FS-939): Colon-prefixed + notation (e.g., "value:user_id") is supported for backwards compatibility but is deprecated; + migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the EntityColumn into a dictionary suitable for use as a JSON request body.""" @@ -2690,8 +2682,8 @@ def from_dict(cls, d: Dict[str, Any]) -> GetExperimentResponse: @dataclass class GetLatestVersionsResponse: model_versions: Optional[List[ModelVersion]] = None - """Latest version models for each requests stage. Only return models with current `READY` status. - If no `stages` provided, returns the latest version for each stage, including `"None"`.""" + """Latest version models for each requests stage. Only return models with current ``READY`` status. + If no ``stages`` provided, returns the latest version for each stage, including ``"None"``.""" def as_dict(self) -> dict: """Serializes the GetLatestVersionsResponse into a dictionary suitable for use as a JSON request body.""" @@ -2741,7 +2733,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GetLoggedModelResponse: @dataclass class GetMetricHistoryResponse: metrics: Optional[List[Metric]] = None - """All logged values for this metric if `max_results` is not specified in the request or if the + """All logged values for this metric if ``max_results`` is not specified in the request or if the total count of metrics returned is less than the service level pagination threshold. Otherwise, this is one page of results.""" @@ -2903,8 +2895,8 @@ class HttpUrlSpec: authorization: Optional[str] = None """Value of the authorization header that should be sent in the request sent by the wehbook. It - should be of the form `" "`. If set to an empty string, no authorization - header will be included in the request.""" + should be of the form ``" "``. If set to an empty string, no + authorization header will be included in the request.""" enable_ssl_verification: Optional[bool] = None """Enable/disable SSL certificate validation. Default is true. For self-signed certificates, this @@ -3012,8 +3004,8 @@ class IngestionConfig: deduplication_columns: Optional[List[str]] = None """Column paths used to identify duplicate rows during ingestion; only one row per distinct - combination of these values is kept. Use dot notation for nested fields (e.g. `value.user_id`). - Empty list means every column is compared.""" + combination of these values is kept. Use dot notation for nested fields (e.g. + ``value.user_id``). Empty list means every column is compared.""" ingestion_job_id: Optional[int] = None """The ID of the Databricks Job that performs the forward-fill ingestion.""" @@ -3545,7 +3537,7 @@ def from_dict(cls, d: Dict[str, Any]) -> LineageContext: @dataclass class LinkedFeature: - """Feature for model version.""" + """Feature for model version. ([ML-57150] Renamed from Feature to LinkedFeature)""" feature_name: Optional[str] = None """Feature name""" @@ -3911,9 +3903,12 @@ class ListStreamsResponse: """Response to a ListStreamsRequest. NOTE: Results are post-filtered by access permission on each stream's ingestion table. This - means: - Returned results may be fewer than page_size (including zero) - Page token points to - next unfiltered batch, not next filtered batch, and may point to an item that will be filtered - out Callers should paginate until next_page_token is empty to retrieve all accessible streams.""" + means: + + - Returned results may be fewer than page_size (including zero) + - Page token points to next unfiltered batch, not next filtered batch, and may point to an item + that will be filtered out Callers should paginate until next_page_token is empty to retrieve + all accessible streams.""" next_page_token: Optional[str] = None """Pagination token to request the next page of results for this query.""" @@ -4369,7 +4364,7 @@ class MaterializedFeature: cron_schedule: Optional[str] = None """The quartz cron expression that defines the schedule of the materialization pipeline. The - schedule is evaluated in the UTC timezone. Hidden from GraphQL: superseded by the `trigger` + schedule is evaluated in the UTC timezone. Hidden from GraphQL: superseded by the ``trigger`` oneof (cron_schedule_trigger), so not exposed to Catalog Explorer.""" cron_schedule_trigger: Optional[CronSchedule] = None @@ -4635,26 +4630,26 @@ def from_dict(cls, d: Dict[str, Any]) -> MinFunction: @dataclass class Model: creation_timestamp: Optional[int] = None - """Timestamp recorded when this `registered_model` was created.""" + """Timestamp recorded when this ``registered_model`` was created.""" description: Optional[str] = None - """Description of this `registered_model`.""" + """Description of this ``registered_model``.""" last_updated_timestamp: Optional[int] = None - """Timestamp recorded when metadata for this `registered_model` was last updated.""" + """Timestamp recorded when metadata for this ``registered_model`` was last updated.""" latest_versions: Optional[List[ModelVersion]] = None - """Collection of latest model versions for each stage. Only contains models with current `READY` + """Collection of latest model versions for each stage. Only contains models with current ``READY`` status.""" name: Optional[str] = None """Unique name for the model.""" tags: Optional[List[ModelTag]] = None - """Tags: Additional metadata key-value pairs for this `registered_model`.""" + """Tags: Additional metadata key-value pairs for this ``registered_model``.""" user_id: Optional[str] = None - """User that created this `registered_model`""" + """User that created this ``registered_model``""" def as_dict(self) -> dict: """Serializes the Model into a dictionary suitable for use as a JSON request body.""" @@ -4897,41 +4892,41 @@ def from_dict(cls, d: Dict[str, Any]) -> ModelTag: @dataclass class ModelVersion: creation_timestamp: Optional[int] = None - """Timestamp recorded when this `model_version` was created.""" + """Timestamp recorded when this ``model_version`` was created.""" current_stage: Optional[str] = None - """Current stage for this `model_version`.""" + """Current stage for this ``model_version``.""" description: Optional[str] = None - """Description of this `model_version`.""" + """Description of this ``model_version``.""" last_updated_timestamp: Optional[int] = None - """Timestamp recorded when metadata for this `model_version` was last updated.""" + """Timestamp recorded when metadata for this ``model_version`` was last updated.""" name: Optional[str] = None """Unique name of the model""" run_id: Optional[str] = None - """MLflow run ID used when creating `model_version`, if `source` was generated by an experiment run - stored in MLflow tracking server.""" + """MLflow run ID used when creating ``model_version``, if ``source`` was generated by an experiment + run stored in MLflow tracking server.""" run_link: Optional[str] = None """Run Link: Direct link to the run that generated this version""" source: Optional[str] = None - """URI indicating the location of the source model artifacts, used when creating `model_version`""" + """URI indicating the location of the source model artifacts, used when creating ``model_version``""" status: Optional[ModelVersionStatus] = None - """Current status of `model_version`""" + """Current status of ``model_version``""" status_message: Optional[str] = None - """Details on current `status`, if it is pending or failed.""" + """Details on current ``status``, if it is pending or failed.""" tags: Optional[List[ModelVersionTag]] = None - """Tags: Additional metadata key-value pairs for this `model_version`.""" + """Tags: Additional metadata key-value pairs for this ``model_version``.""" user_id: Optional[str] = None - """User that created this `model_version`.""" + """User that created this ``model_version``.""" version: Optional[str] = None """Model's version number.""" @@ -5033,7 +5028,7 @@ class ModelVersionDatabricks: Users get subscribed by interacting with the model version.""" feature_list: Optional[FeatureList] = None - """Feature lineage of `model_version`.""" + """Feature lineage of ``model_version``.""" last_updated_timestamp: Optional[int] = None """Time of the object at last update, as a Unix timestamp in milliseconds.""" @@ -5042,8 +5037,8 @@ class ModelVersionDatabricks: """Name of the model.""" open_requests: Optional[List[Activity]] = None - """Open requests for this `model_versions`. Gap in sequence number is intentional and is done in - order to match field sequence numbers of `ModelVersion` proto message""" + """Open requests for this ``model_versions``. Gap in sequence number is intentional and is done in + order to match field sequence numbers of ``ModelVersion`` proto message""" permission_level: Optional[PermissionLevel] = None @@ -5176,12 +5171,12 @@ def from_dict(cls, d: Dict[str, Any]) -> ModelVersionDatabricks: class ModelVersionStatus(Enum): - """The status of the model version. Valid values are: * `PENDING_REGISTRATION`: Request to register - a new model version is pending as server performs background tasks. - - * `FAILED_REGISTRATION`: Request to register a new model version has failed. + """The status of the model version. Valid values are: - * `READY`: Model version is ready for use.""" + - ``PENDING_REGISTRATION``: Request to register a new model version is pending as server + performs background tasks. + - ``FAILED_REGISTRATION``: Request to register a new model version has failed. + - ``READY``: Model version is ready for use.""" FAILED_REGISTRATION = "FAILED_REGISTRATION" PENDING_REGISTRATION = "PENDING_REGISTRATION" @@ -5536,7 +5531,7 @@ def from_dict(cls, d: Dict[str, Any]) -> Param: class PermissionLevel(Enum): """Permission level of the requesting user on the object. For what is allowed at each level, see - [MLflow Model permissions](..).""" + MLflow Model permissions.""" CAN_CREATE_REGISTERED_MODEL = "CAN_CREATE_REGISTERED_MODEL" CAN_EDIT = "CAN_EDIT" @@ -5861,9 +5856,12 @@ def from_dict(cls, d: Dict[str, Any]) -> RegisteredModelPermissionsDescription: class RegistryEmailSubscriptionType(Enum): """.. note:: Experimental: This entity may change or be removed in a future release without - warning. Email subscription types for registry notifications: - `ALL_EVENTS`: Subscribed to all - events. - `DEFAULT`: Default subscription type. - `SUBSCRIBED`: Subscribed to notifications. - - `UNSUBSCRIBED`: Not subscribed to notifications.""" + warning. Email subscription types for registry notifications: + + - ``ALL_EVENTS``: Subscribed to all events. + - ``DEFAULT``: Default subscription type. + - ``SUBSCRIBED``: Subscribed to notifications. + - ``UNSUBSCRIBED``: Not subscribed to notifications.""" ALL_EVENTS = "ALL_EVENTS" DEFAULT = "DEFAULT" @@ -5880,34 +5878,24 @@ class RegistryWebhook: """User-specified description for the webhook.""" events: Optional[List[RegistryWebhookEvent]] = None - """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. + """Events that can trigger a registry webhook: - * `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.""" + - ``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.""" http_url_spec: Optional[HttpUrlSpecWithoutSecret] = None @@ -6003,12 +5991,12 @@ class RegistryWebhookEvent(Enum): class RegistryWebhookStatus(Enum): """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. + ``ACTIVE``: - * `TEST_MODE`: Webhook can be triggered through the test endpoint, but is not triggered on a - real event.""" + - ``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.""" ACTIVE = "ACTIVE" DISABLED = "DISABLED" @@ -6156,8 +6144,8 @@ def from_dict(cls, d: Dict[str, Any]) -> RestoreRunsResponse: @dataclass class RollingWindow: """A rolling time window with an optional delay. This is the SQL-spec-aligned replacement for - ContinuousWindow: `delay` is the non-negative counterpart of the legacy non-positive - `ContinuousWindow.offset`.""" + ContinuousWindow: ``delay`` is the non-negative counterpart of the legacy non-positive + ``ContinuousWindow.offset``.""" window_duration: Duration """The duration of the rolling window (must be positive).""" @@ -6922,12 +6910,12 @@ def from_dict(cls, d: Dict[str, Any]) -> SlidingWindow: class Status(Enum): - """The status of the model version. Valid values are: * `PENDING_REGISTRATION`: Request to register - a new model version is pending as server performs background tasks. - - * `FAILED_REGISTRATION`: Request to register a new model version has failed. + """The status of the model version. Valid values are: - * `READY`: Model version is ready for use.""" + - ``PENDING_REGISTRATION``: Request to register a new model version is pending as server + performs background tasks. + - ``FAILED_REGISTRATION``: Request to register a new model version has failed. + - ``READY``: Model version is ready for use.""" FAILED_REGISTRATION = "FAILED_REGISTRATION" PENDING_REGISTRATION = "PENDING_REGISTRATION" @@ -6941,8 +6929,8 @@ class StddevPopFunction: input: str """The input column from which the population standard deviation is computed. For Kafka sources, use dot-prefixed path notation (e.g., "value.amount"). For nested fields, the leaf node name is - used. Colon-prefixed notation (e.g., "value:amount") is supported for backwards compatibility - but is deprecated; migrate to dot notation.""" + used. TODO(FS-939): Colon-prefixed notation (e.g., "value:amount") is supported for backwards + compatibility but is deprecated; migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the StddevPopFunction into a dictionary suitable for use as a JSON request body.""" @@ -7110,8 +7098,8 @@ class StreamConnectionConfig: direct_mtls_config: Optional[DirectMtlsConfig] = None """Direct mTLS configuration for stream platform access. This is only used in the short term until - UC Kafka Connections support mTLS . Once UC Kafka Connections support mTLS, this will be - deprecated.""" + UC Kafka Connections support mTLS (XTA-18030). Once UC Kafka Connections support mTLS, this will + be deprecated.""" uc_connection_name: Optional[str] = None """Name of an existing UC Connection for stream platform access. Must be the correct type for the @@ -7318,9 +7306,9 @@ class SumFunction: input: str """The input column from which the sum is computed. For Kafka sources, use dot-prefixed path - notation (e.g., "value.amount"). For nested fields, the leaf node name is used. Colon-prefixed - notation (e.g., "value:amount") is supported for backwards compatibility but is deprecated; - migrate to dot notation.""" + notation (e.g., "value.amount"). For nested fields, the leaf node name is used. TODO(FS-939): + Colon-prefixed notation (e.g., "value:amount") is supported for backwards compatibility but is + deprecated; migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the SumFunction into a dictionary suitable for use as a JSON request body.""" @@ -7448,8 +7436,8 @@ class TimeseriesColumn: reference fields within the key or value schema (e.g., "value.event_timestamp"). For nested fields, the leaf node name (e.g., "event_timestamp" from "value.event_details.event_timestamp") is what will be present in materialized tables and expected to match at query time. - Colon-prefixed notation (e.g., "value:event_timestamp") is supported for backwards compatibility - but is deprecated; migrate to dot notation.""" + TODO(FS-939): Colon-prefixed notation (e.g., "value:event_timestamp") is supported for backwards + compatibility but is deprecated; migrate to dot notation.""" def as_dict(self) -> dict: """Serializes the TimeseriesColumn into a dictionary suitable for use as a JSON request body.""" @@ -7488,13 +7476,10 @@ class TransitionRequest: to_stage: Optional[str] = None """Target stage of the transition (if the activity is stage transition related). Valid values are: - * `None`: The initial stage of a model version. - - * `Staging`: Staging or pre-production stage. - - * `Production`: Production stage. - - * `Archived`: Archived stage.""" + - ``None``: The initial stage of a model version. + - ``Staging``: Staging or pre-production stage. + - ``Production``: Production stage. + - ``Archived``: Archived stage.""" user_id: Optional[str] = None """The username of the user that created the object.""" @@ -7822,8 +7807,9 @@ def create_experiment( another experiment with the same name does not already exist and fails if another experiment with the same name already exists. - Throws `RESOURCE_ALREADY_EXISTS` if an experiment with the given name exists. Note: In some contexts, - this error may be remapped to `ALREADY_EXISTS`. To be safe, clients should check for both error codes. + Throws ``RESOURCE_ALREADY_EXISTS`` if an experiment with the given name exists. Note: In some + contexts, this error may be remapped to ``ALREADY_EXISTS``. To be safe, clients should check for both + error codes. :param name: str Experiment name. @@ -7921,8 +7907,8 @@ def create_run( user_id: Optional[str] = None, ) -> 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. + 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. @@ -8149,7 +8135,7 @@ def get_by_name(self, experiment_name: str) -> GetExperimentByNameResponse: 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. + Throws ``RESOURCE_DOES_NOT_EXIST`` if no experiment with the specified name exists. :param experiment_name: str Name of the associated experiment. @@ -8215,8 +8201,8 @@ def get_history( :param run_id: str (optional) ID of the run from which to fetch metric values. Must be provided. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run from which to fetch metric values. This field will - be removed in a future MLflow version. + [Deprecated, use ``run_id`` instead] ID of the run from which to fetch metric values. This field + will be removed in a future MLflow version. :returns: Iterator over :class:`Metric` """ @@ -8318,7 +8304,7 @@ def get_run(self, run_id: str, *, run_uuid: Optional[str] = None) -> GetRunRespo :param run_id: str ID of the run to fetch. Must be provided. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run to fetch. This field will be removed in a future + [Deprecated, use ``run_id`` instead] ID of the run to fetch. This field will be removed in a future MLflow version. :returns: :class:`GetRunResponse` @@ -8348,25 +8334,23 @@ def list_artifacts( run_id: Optional[str] = None, run_uuid: Optional[str] = None, ) -> Iterator[FileInfo]: - """List artifacts for a run. Takes an optional `artifact_path` prefix which if specified, the response + """List artifacts for a run. Takes an optional ``artifact_path`` prefix which if specified, the response contains only artifacts with the specified prefix. A maximum of 1000 artifacts will be retrieved for - UC Volumes. Please call `/api/2.0/fs/directories{directory_path}` for listing artifacts in UC Volumes, - which supports pagination. See [List directory contents | Files - API](/api/workspace/files/listdirectorycontents). + 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. :param page_token: str (optional) - The token indicating the page of artifact results to fetch. `page_token` is not supported when + The 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). + Please call ``/api/2.0/fs/directories{directory_path}`` for listing artifacts in UC Volumes, which + supports pagination. See List directory contents | Files API. :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. + [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` """ @@ -8407,8 +8391,8 @@ def 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 + 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 @@ -8460,36 +8444,31 @@ def log_batch( 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. + - 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. - * 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** - Request Limits ------------------------------- A single JSON-serialized API request may be up to 1 MB - in size and contain: + A single JSON-serialized API request may be up to 1 MB in size and contain: - * No more than 1000 metrics, params, and tags in total - - * Up to 1000 metrics - - * Up to 100 params - - * Up to 100 tags + - No more than 1000 metrics, params, and tags in total + - Up to 1000 metrics + - Up to 100 params + - Up to 100 tags For example, a valid request might contain 900 metrics, 50 params, and 50 tags, but logging 900 metrics, 50 params, and 51 tags is invalid. The following limits also apply to metric, param, and tag keys and values: - * Metric keys, param keys, and tag keys can be up to 250 characters in length - - * Parameter and tag values can be up to 250 characters in length + - Metric keys, param keys, and tag keys can be up to 250 characters in length + - Parameter and tag values can be up to 250 characters in length :param metrics: List[:class:`Metric`] (optional) Metrics to log. A single request can contain up to 1000 metrics, and up to 1000 metrics, params, and @@ -8620,7 +8599,7 @@ def log_metric( :param run_id: str (optional) ID of the run under which to log the metric. Must be provided. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run under which to log the metric. This field will be + [Deprecated, use ``run_id`` instead] ID of the run under which to log the metric. This field will be removed in a future MLflow version. :param step: int (optional) Step at which to log the metric @@ -8659,8 +8638,7 @@ def log_metric( self._api.do("POST", "/api/2.0/mlflow/runs/log-metric", body=body, headers=headers) def log_model(self, *, model_json: Optional[str] = None, run_id: Optional[str] = None): - """**Note:** the [Create a logged model](/api/workspace/experiments/createloggedmodel) API replaces this - endpoint. + """**Note:** the Create a logged model API replaces this endpoint. Log a model to an MLflow Run. @@ -8727,7 +8705,7 @@ def log_param(self, key: str, value: str, *, run_id: Optional[str] = None, run_u :param run_id: str (optional) ID of the run under which to log the param. Must be provided. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run under which to log the param. This field will be + [Deprecated, use ``run_id`` instead] ID of the run under which to log the param. This field will be removed in a future MLflow version. @@ -8758,7 +8736,7 @@ def restore_experiment(self, experiment_id: str): 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. + Throws ``RESOURCE_DOES_NOT_EXIST`` if experiment was never created or was permanently deleted. :param experiment_id: str ID of the associated experiment. @@ -8783,7 +8761,7 @@ def restore_experiment(self, experiment_id: str): def restore_run(self, run_id: str): """Restores a deleted run. This also restores associated metadata, runs, metrics, params, and tags. - Throws `RESOURCE_DOES_NOT_EXIST` if the run was never created or was permanently deleted. + Throws ``RESOURCE_DOES_NOT_EXIST`` if the run was never created or was permanently deleted. :param run_id: str ID of the run to restore. @@ -8913,7 +8891,7 @@ def search_logged_models( :param datasets: List[:class:`SearchLoggedModelsDataset`] (optional) List of datasets on which to apply the metrics filter clauses. For example, a filter with - `metrics.accuracy > 0.9` and dataset info with name "test_dataset" means we will return all logged + ``metrics.accuracy > 0.9`` and dataset info with name "test_dataset" means we will return all logged models with accuracy > 0.9 on the test_dataset. Metric values from ANY dataset matching the criteria are considered. If no datasets are specified, then metrics across all datasets are considered in the filter. @@ -8971,7 +8949,7 @@ def search_runs( ) -> Iterator[Run]: """Searches for runs that satisfy expressions. - Search expressions can use `mlflowMetric` and `mlflowParam` keys. + Search expressions can use ``mlflowMetric`` and ``mlflowParam`` keys. :param experiment_ids: List[str] (optional) List of experiment IDs to search over. @@ -8980,20 +8958,20 @@ def search_runs( 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'` + 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'` + ``metrics."model class" = 'LinearRegression' and tags."user-name" = 'Tomas'`` - Supported operators are `=`, `!=`, `>`, `>=`, `<`, and `<=`. + 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). + ``"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:`ViewType` (optional) @@ -9127,7 +9105,7 @@ def set_tag(self, key: str, value: str, *, run_id: Optional[str] = None, run_uui :param run_id: str (optional) ID of the run under which to log the tag. Must be provided. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run under which to log the tag. This field will be + [Deprecated, use ``run_id`` instead] ID of the run under which to log the tag. This field will be removed in a future MLflow version. @@ -9225,7 +9203,7 @@ def update_run( :param run_name: str (optional) Updated name of the run. :param run_uuid: str (optional) - [Deprecated, use `run_id` instead] ID of the run to update. This field will be removed in a future + [Deprecated, use ``run_id`` instead] ID of the run to update. This field will be removed in a future MLflow version. :param status: :class:`UpdateRunStatus` (optional) Updated status of the run. @@ -9818,7 +9796,7 @@ def update_materialized_feature( return MaterializedFeature.from_dict(res) def update_stream(self, name: str, stream: Stream, update_mask: FieldMask) -> Stream: - """Update a Stream. Only fields listed in `update_mask` are mutated. + """Update a Stream. Only fields listed in ``update_mask`` are mutated. :param name: str Full three-part (catalog.schema.stream) name of the stream. @@ -10127,8 +10105,10 @@ def create_experiment( :param include_features: List[str] (optional) Specifies the list of feature columns to include in model training. These columns must exist in the training data and be of type string, numerical, or boolean. If not specified, no additional features - will be included. Note: Certain columns are automatically handled: - Automatically excluded: - split_column, target_column, custom_weights_column. - Automatically included: time_column. + will be included. Note: Certain columns are automatically handled: + + - Automatically excluded: split_column, target_column, custom_weights_column. + - Automatically included: time_column. :param max_runtime: int (optional) The maximum duration for the experiment in minutes. The experiment stops automatically if it exceeds this limit. @@ -10470,9 +10450,9 @@ def update_feature_tag( 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. + Models in Unity Catalog 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.""" @@ -10492,13 +10472,10 @@ def approve_transition_request( :param stage: str 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. + - ``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) @@ -10567,7 +10544,7 @@ def create_model( self, name: str, *, description: Optional[str] = None, tags: Optional[List[ModelTag]] = None ) -> 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. + ``RESOURCE_ALREADY_EXISTS`` if a registered model with the given name exists. :param name: str Register models under this name @@ -10617,7 +10594,7 @@ def create_model_version( :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 + 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 @@ -10665,13 +10642,10 @@ def create_transition_request( :param stage: str 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. + - ``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. @@ -10712,34 +10686,24 @@ def create_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. + 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) @@ -10751,12 +10715,12 @@ def create_webhook( events across all versions of all registered models. :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. + ``ACTIVE``: - * `TEST_MODE`: Webhook can be triggered through the test endpoint, but is not triggered on a real - event. + - ``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` """ @@ -10926,13 +10890,10 @@ def delete_transition_request( :param stage: str 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. + - ``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. @@ -11016,11 +10977,9 @@ def get_latest_versions(self, name: str, *, stages: Optional[List[str]] = None) return parsed if parsed is not None else [] def get_model(self, name: str) -> 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 + """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. :param name: str Registered model unique name identifier. @@ -11140,7 +11099,7 @@ def get_permissions(self, registered_model_id: str) -> RegisteredModelPermission return RegisteredModelPermissions.from_dict(res) def list_models(self, *, max_results: Optional[int] = None, page_token: Optional[str] = None) -> Iterator[Model]: - """Lists all available registered models, up to the limit specified in __max_results__. + """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. @@ -11211,37 +11170,28 @@ def list_webhooks( """**NOTE:** This endpoint is in Public Preview. Lists all registry webhooks. :param events: List[:class:`RegistryWebhookEvent`] (optional) - Events that trigger the 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. - - 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. + Events that trigger the 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. + + 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 max_results: int (optional) :param model_name: str (optional) Registered model name If not specified, all webhooks associated with the specified events are @@ -11290,13 +11240,10 @@ def reject_transition_request( :param stage: str 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. + - ``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. @@ -11330,7 +11277,7 @@ def rename_model(self, name: str, *, new_name: Optional[str] = None) -> RenameMo :param name: str Registered model unique name identifier. :param new_name: str (optional) - If provided, updates the name for this `registered_model`. + If provided, updates the name for this ``registered_model``. :returns: :class:`RenameModelResponse` """ @@ -11360,7 +11307,7 @@ def search_model_versions( order_by: Optional[List[str]] = None, page_token: Optional[str] = None, ) -> Iterator[ModelVersion]: - """Searches for specific model versions based on the supplied __filter__. + """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 @@ -11411,7 +11358,7 @@ def search_models( order_by: Optional[List[str]] = None, page_token: Optional[str] = None, ) -> Iterator[Model]: - """Search for registered models based on the specified __filter__. + """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 @@ -11462,8 +11409,8 @@ def set_model_tag(self, name: str, key: str, value: 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. + 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. @@ -11498,8 +11445,8 @@ def set_model_version_tag(self, name: str, version: str, key: str, value: 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. + 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. @@ -11568,8 +11515,8 @@ def test_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. + 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` """ @@ -11594,10 +11541,9 @@ def test_registry_webhook( def transition_stage( self, name: str, version: str, stage: str, archive_existing_versions: bool, *, comment: Optional[str] = None ) -> 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 + """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. :param name: str Name of the model. @@ -11606,13 +11552,10 @@ def transition_stage( :param stage: str 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. + - ``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) @@ -11680,7 +11623,7 @@ def update_model(self, name: str, *, description: Optional[str] = None) -> Updat :param name: str Registered model unique name identifier. :param description: str (optional) - If provided, updates the description for this `registered_model`. + If provided, updates the description for this ``registered_model``. :returns: :class:`UpdateModelResponse` """ @@ -11712,7 +11655,7 @@ def update_model_version( :param version: str Model version number :param description: str (optional) - If provided, updates the description for this `registered_model`. + If provided, updates the description for this ``registered_model``. :returns: :class:`UpdateModelVersionResponse` """ @@ -11786,34 +11729,24 @@ def update_webhook( :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. + 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) diff --git a/databricks/sdk/service/networking.py b/databricks/sdk/service/networking.py index 5f924f3d9..a613a1bd1 100755 --- a/databricks/sdk/service/networking.py +++ b/databricks/sdk/service/networking.py @@ -108,7 +108,7 @@ class Endpoint: """The resource name of the endpoint, which uniquely identifies the endpoint.""" state: Optional[EndpointState] = None - """The state of the endpoint. The endpoint can only be used if the state is `APPROVED`.""" + """The state of the endpoint. The endpoint can only be used if the state is ``APPROVED``.""" use_case: Optional[EndpointUseCase] = None """The use case that determines the type of network connectivity this endpoint provides. This field @@ -235,7 +235,7 @@ def create_endpoint(self, parent: str, endpoint: Endpoint) -> Endpoint: :param parent: str The parent resource name of the account under which the endpoint is created. Format: - `accounts/{account_id}`. + ``accounts/{account_id}``. :param endpoint: :class:`Endpoint` :returns: :class:`Endpoint` @@ -288,7 +288,7 @@ def list_endpoints( """Lists all network connectivity endpoints for the account. :param parent: str - The parent resource name of the account to list endpoints for. Format: `accounts/{account_id}`. + The parent resource name of the account to list endpoints for. Format: ``accounts/{account_id}``. :param page_size: int (optional) :param page_token: str (optional) diff --git a/databricks/sdk/service/oauth2.py b/databricks/sdk/service/oauth2.py index 14f0bd79a..5b2c9ec84 100755 --- a/databricks/sdk/service/oauth2.py +++ b/databricks/sdk/service/oauth2.py @@ -210,9 +210,9 @@ class FederationPolicy: name: Optional[str] = None """Resource name for the federation policy. Example values include - `accounts//federationPolicies/my-federation-policy` for Account Federation Policies, - and - `accounts//servicePrincipals//federationPolicies/my-federation-policy` + ``accounts//federationPolicies/my-federation-policy`` for Account Federation + Policies, and + ``accounts//servicePrincipals//federationPolicies/my-federation-policy`` for Service Principal Federation Policies. Typically an output parameter, which does not need to be specified in create or update requests. If specified in a request, must match the value in the request URL.""" @@ -594,7 +594,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListFederationPoliciesResponse: @dataclass class ListServicePrincipalSecretsResponse: next_page_token: Optional[str] = None - """A token, which can be sent as `page_token` to retrieve the next page.""" + """A token, which can be sent as ``page_token`` to retrieve the next page.""" secrets: Optional[List[SecretInfo]] = None """List of the secrets""" @@ -955,38 +955,55 @@ class AccountFederationPolicyAPI: 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. + 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" ``` + 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: + + .. code-block:: + + 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" } ``` + ``username@mycompany.com`` is: + + .. code-block:: + + { + "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""" + You do not need to configure an OAuth application in Databricks to use token federation.""" def __init__(self, api_client): self._api = api_client @@ -1510,29 +1527,43 @@ class ServicePrincipalFederationPolicyAPI: 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" } ``` + 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: + + .. code-block:: + + 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: + + .. code-block:: + + { + "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. @@ -1696,14 +1727,12 @@ 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]. + 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""" + authenticate with the service principal. For more information, see `Databricks Terraform Provider + `__.""" def __init__(self, api_client): self._api = api_client @@ -1767,12 +1796,12 @@ def list( The service principal ID. :param page_size: int (optional) :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. + 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` """ @@ -1806,14 +1835,12 @@ class ServicePrincipalSecretsProxyAPI: APIs, the service principal must be first added to the current workspace. 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]. + 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 Providerto - 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""" + authenticate with the service principal. For more information, see `Databricks Terraform Provider + `__.""" def __init__(self, api_client): self._api = api_client @@ -1885,12 +1912,12 @@ def list( The service principal ID. :param page_size: int (optional) :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. + 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/databricks/sdk/service/pipelines.py b/databricks/sdk/service/pipelines.py index 16b192170..67d1e45e8 100755 --- a/databricks/sdk/service/pipelines.py +++ b/databricks/sdk/service/pipelines.py @@ -453,8 +453,9 @@ def from_dict(cls, d: Dict[str, Any]) -> DeletePipelineResponse: class DeploymentKind(Enum): - """The deployment method that manages the pipeline: - BUNDLE: The pipeline is managed by a - Databricks Asset Bundle.""" + """The deployment method that manages the pipeline: + + - BUNDLE: The pipeline is managed by a Databricks Asset Bundle.""" BUNDLE = "BUNDLE" @@ -842,7 +843,7 @@ class GetPipelineResponse: """Status of the latest updates for the pipeline. Ordered with the newest update first.""" name: Optional[str] = None - """A human friendly identifier for the pipeline, taken from the `spec`.""" + """A human friendly identifier for the pipeline, taken from the ``spec``.""" parameters: Optional[Dict[str, str]] = None """Key/value map of default parameters to use for pipeline execution. Maximum total size: 10k @@ -853,14 +854,14 @@ class GetPipelineResponse: run_as: Optional[RunAs] = None """The user or service principal that the pipeline runs as, if specified in the request. This field - indicates the explicit configuration of `run_as` for the pipeline. To find the value in all - cases, explicit or implicit, use `run_as_user_name`.""" + indicates the explicit configuration of ``run_as`` for the pipeline. To find the value in all + cases, explicit or implicit, use ``run_as_user_name``.""" run_as_user_name: Optional[str] = None """Username of the user that the pipeline will run on behalf of.""" spec: Optional[PipelineSpec] = None - """The pipeline specification. This field is not returned when called by `ListPipelines`.""" + """The pipeline specification. This field is not returned when called by ``ListPipelines``.""" state: Optional[PipelineState] = None """The pipeline state.""" @@ -1255,8 +1256,8 @@ class IngestionPipelineDefinition: ingest_from_uc_foreign_catalog: Optional[bool] = None """Immutable. If set to true, the pipeline will ingest tables from the UC foreign catalogs directly - without the need to specify a UC connection or ingestion gateway. The `source_catalog` fields in - objects of IngestionConfig are interpreted as the UC foreign catalogs to ingest from.""" + without the need to specify a UC connection or ingestion gateway. The ``source_catalog`` fields + in objects of IngestionConfig are interpreted as the UC foreign catalogs to ingest from.""" ingestion_gateway_id: Optional[str] = None """Identifier for the gateway that is used by this ingestion pipeline to communicate with the @@ -1363,12 +1364,12 @@ class IngestionPipelineDefinitionTableSpecificConfigQueryBasedConnectorConfig: the table to be read and ingested incrementally through structured streaming. The columns are allowed to have repeated values but have to be non-decreasing. If the source data is merged into the destination (e.g., using SCD Type 1 or Type 2), these columns will implicitly define the - `sequence_by` behavior. You can still explicitly set `sequence_by` to override this default.""" + ``sequence_by`` behavior. You can still explicitly set ``sequence_by`` to override this default.""" deletion_condition: Optional[str] = None """Specifies a SQL WHERE condition that specifies that the source row has been deleted. This is sometimes referred to as "soft-deletes". For example: "Operation = 'DELETE'" or "is_deleted = - true". This field is orthogonal to `hard_deletion_sync_interval_in_seconds`, one for + true". This field is orthogonal to ``hard_deletion_sync_interval_in_seconds``, one for soft-deletes and the other for hard-deletes. See also the hard_deletion_sync_min_interval_in_seconds field for handling of "hard deletes" where the source rows are physically removed from the table.""" @@ -1417,7 +1418,7 @@ def from_dict(cls, d: Dict[str, Any]) -> IngestionPipelineDefinitionTableSpecifi class IngestionPipelineDefinitionWorkdayReportParameters: incremental: Optional[bool] = None """(Optional) Marks the report as incremental. This field is deprecated and should not be used. Use - `parameters` instead. The incremental behavior is now controlled by the `parameters` field.""" + ``parameters`` instead. The incremental behavior is now controlled by the ``parameters`` field.""" parameters: Optional[Dict[str, str]] = None """Parameters for the Workday report. Each key represents the parameter name (e.g., "start_date", @@ -1427,7 +1428,7 @@ class IngestionPipelineDefinitionWorkdayReportParameters: report_parameters: Optional[List[IngestionPipelineDefinitionWorkdayReportParametersQueryKeyValue]] = None """(Optional) Additional custom parameters for Workday Report This field is deprecated and should - not be used. Use `parameters` instead.""" + not be used. Use ``parameters`` instead.""" def as_dict(self) -> dict: """Serializes the IngestionPipelineDefinitionWorkdayReportParameters into a dictionary suitable for use as a JSON request body.""" @@ -1469,10 +1470,12 @@ class IngestionPipelineDefinitionWorkdayReportParametersQueryKeyValue: """Key for the report parameter, can be a column name or other metadata""" value: Optional[str] = None - """Value for the report parameter. Possible values it can take are these sql functions: 1. - coalesce(current_offset(), date("YYYY-MM-DD")) -> if current_offset() is null, then the passed - date, else current_offset() 2. current_date() 3. date_sub(current_date(), x) -> subtract x (some - non-negative integer) days from current date""" + """Value for the report parameter. Possible values it can take are these sql functions: + + 1. coalesce(current_offset(), date("YYYY-MM-DD")) -> if current_offset() is null, then the + passed date, else current_offset() + 2. current_date() + 3. date_sub(current_date(), x) -> subtract x (some non-negative integer) days from current date""" def as_dict(self) -> dict: """Serializes the IngestionPipelineDefinitionWorkdayReportParametersQueryKeyValue into a dictionary suitable for use as a JSON request body.""" @@ -1953,9 +1956,10 @@ class Notifications: """A list of alerts that trigger the sending of notifications to the configured destinations. The supported alerts are: - * `on-update-success`: A pipeline update completes successfully. * `on-update-failure`: Each - time a pipeline update fails. * `on-update-fatal-failure`: A pipeline update fails with a - non-retryable (fatal) error. * `on-flow-failure`: A single data flow fails.""" + - ``on-update-success``: A pipeline update completes successfully. + - ``on-update-failure``: Each time a pipeline update fails. + - ``on-update-fatal-failure``: A pipeline update fails with a non-retryable (fatal) error. + - ``on-flow-failure``: A single data flow fails.""" email_recipients: Optional[List[str]] = None """A list of email addresses notified when a configured alert is triggered.""" @@ -2516,18 +2520,17 @@ class PipelineCluster: cluster_log_conf: Optional[compute.ClusterLogConf] = None """The configuration for delivering spark logs to a long-term storage destination. Only dbfs destinations 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`.""" + 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``.""" custom_tags: Optional[Dict[str, str]] = None """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: + 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""" + tags""" driver_instance_pool_id: Optional[str] = None """The optional ID of the instance pool for the driver of the cluster belongs. The pool cluster @@ -2535,7 +2538,7 @@ class PipelineCluster: driver_node_type_id: Optional[str] = None """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.""" + type will be set as the same value as ``node_type_id`` defined above.""" enable_local_disk_encryption: Optional[bool] = None """Whether to enable local disk encryption for the cluster.""" @@ -2546,16 +2549,16 @@ class PipelineCluster: init_scripts: Optional[List[compute.InitScriptInfo]] = None """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`.""" + scripts are executed sequentially in the order provided. If ``cluster_log_conf`` is specified, + init script logs are sent to ``//init_scripts``.""" instance_pool_id: Optional[str] = None """The optional ID of the instance pool to which the cluster belongs.""" label: Optional[str] = None - """A label for the cluster specification, either `default` to configure the default cluster, or - `maintenance` to configure the maintenance cluster. This field is optional. The default value is - `default`.""" + """A label for the cluster specification, either ``default`` to configure the default cluster, or + ``maintenance`` to configure the maintenance cluster. This field is optional. The default value + is ``default``.""" node_type_id: Optional[str] = None """This field encodes, through a single value, the resources available to each of the Spark nodes @@ -2565,13 +2568,13 @@ class PipelineCluster: num_workers: Optional[int] = None """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. + ``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.""" + workers, whereas the workers listed in ``spark_info`` will gradually increase from 5 to 10 as + the new nodes are provisioned.""" policy_id: Optional[str] = None """The ID of the cluster policy used to create the cluster if applicable.""" @@ -2582,21 +2585,21 @@ class PipelineCluster: spark_env_vars: Optional[Dict[str, str]] = None """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. + 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 + 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"}`""" + 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"}``""" ssh_public_keys: Optional[List[str]] = None """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.""" + private keys can be used to login with the user name ``ubuntu`` on port ``2200``. Up to 10 keys + can be specified.""" def as_dict(self) -> dict: """Serializes the PipelineCluster into a dictionary suitable for use as a JSON request body.""" @@ -2717,14 +2720,14 @@ class PipelineClusterAutoscale: initial number of workers the cluster will have after creation.""" max_workers: int - """The maximum number of workers to which the cluster can scale up when overloaded. `max_workers` - must be strictly greater than `min_workers`.""" + """The maximum number of workers to which the cluster can scale up when overloaded. ``max_workers`` + must be strictly greater than ``min_workers``.""" mode: Optional[PipelineClusterAutoscaleMode] = None """Databricks Enhanced Autoscaling optimizes cluster utilization by automatically allocating cluster resources based on workload volume, with minimal impact to the data processing latency - of your pipelines. Enhanced Autoscaling is available for `updates` clusters only. The legacy - autoscaling feature is used for `maintenance` clusters.""" + of your pipelines. Enhanced Autoscaling is available for ``updates`` clusters only. The legacy + autoscaling feature is used for ``maintenance`` clusters.""" def as_dict(self) -> dict: """Serializes the PipelineClusterAutoscale into a dictionary suitable for use as a JSON request body.""" @@ -2761,8 +2764,8 @@ def from_dict(cls, d: Dict[str, Any]) -> PipelineClusterAutoscale: class PipelineClusterAutoscaleMode(Enum): """Databricks Enhanced Autoscaling optimizes cluster utilization by automatically allocating cluster resources based on workload volume, with minimal impact to the data processing latency - of your pipelines. Enhanced Autoscaling is available for `updates` clusters only. The legacy - autoscaling feature is used for `maintenance` clusters.""" + of your pipelines. Enhanced Autoscaling is available for ``updates`` clusters only. The legacy + autoscaling feature is used for ``maintenance`` clusters.""" ENHANCED = "ENHANCED" LEGACY = "LEGACY" @@ -2774,15 +2777,15 @@ class PipelineDeployment: """The deployment method that manages the pipeline.""" deployment_id: Optional[str] = None - """ID of the deployment that manages this pipeline. Only set when `kind` is `BUNDLE`. Used to look - up deployment metadata from the Deployment Metadata service.""" + """ID of the deployment that manages this pipeline. Only set when ``kind`` is ``BUNDLE``. Used to + look up deployment metadata from the Deployment Metadata service.""" metadata_file_path: Optional[str] = None """The path to the file containing metadata about the deployment.""" version_id: Optional[str] = None - """ID of the version of the deployment that produced this pipeline. Only set when `kind` is - `BUNDLE`. Identifies a specific snapshot of the deployment in the Deployment Metadata service.""" + """ID of the version of the deployment that produced this pipeline. Only set when ``kind`` is + ``BUNDLE``. Identifies a specific snapshot of the deployment in the Deployment Metadata service.""" def as_dict(self) -> dict: """Serializes the PipelineDeployment into a dictionary suitable for use as a JSON request body.""" @@ -2929,7 +2932,7 @@ class PipelineLibrary: glob: Optional[PathPattern] = None """The unified field to include source codes. Each entry can be a notebook path, a file path, or a - folder path that ends `/**`. This field cannot be used together with `notebook` or `file`.""" + folder path that ends ``/**``. This field cannot be used together with ``notebook`` or ``file``.""" jar: Optional[str] = None """URI of the jar to be installed. Currently only DBFS is supported.""" @@ -3118,9 +3121,9 @@ class PipelineSpec: """Budget policy of this pipeline.""" catalog: Optional[str] = None - """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 + """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.""" channel: Optional[str] = None @@ -3133,7 +3136,7 @@ class PipelineSpec: """String-String configuration for this pipeline execution.""" continuous: Optional[bool] = None - """Whether the pipeline is continuous or triggered. This replaces `trigger`.""" + """Whether the pipeline is continuous or triggered. This replaces ``trigger``.""" deployment: Optional[PipelineDeployment] = None """Deployment type of this pipeline.""" @@ -3198,12 +3201,12 @@ class PipelineSpec: pipeline.""" target: Optional[str] = None - """Target schema (database) to add tables in this pipeline to. Exactly one of `schema` or `target` - must be specified. To publish to Unity Catalog, also specify `catalog`. This legacy field is - deprecated for pipeline creation in favor of the `schema` field.""" + """Target schema (database) to add tables in this pipeline to. Exactly one of ``schema`` or + ``target`` must be specified. To publish to Unity Catalog, also specify ``catalog``. This legacy + field is deprecated for pipeline creation in favor of the ``schema`` field.""" trigger: Optional[PipelineTrigger] = None - """Which pipeline trigger to use. Deprecated: Use `continuous` instead.""" + """Which pipeline trigger to use. Deprecated: Use ``continuous`` instead.""" usage_policy_id: Optional[str] = None """Usage policy of this pipeline.""" @@ -3522,7 +3525,7 @@ class PipelinesEnvironment: and their included packages, see https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/ - The value should be a string representing the environment version number, for example: `"4"`.""" + The value should be a string representing the environment version number, for example: ``"4"``.""" def as_dict(self) -> dict: """Serializes the PipelinesEnvironment into a dictionary suitable for use as a JSON request body.""" @@ -3624,8 +3627,8 @@ class ReplaceWhereOverride: """Name of the flow to apply this override to.""" predicate_override: Optional[str] = None - """SQL predicate string to use as replace_where condition. Example: `date = '2024-10-10' AND city = - 'xyz'`""" + """SQL predicate string to use as replace_where condition. Example: ``date = '2024-10-10' AND city + = 'xyz'``""" def as_dict(self) -> dict: """Serializes the ReplaceWhereOverride into a dictionary suitable for use as a JSON request body.""" @@ -3856,12 +3859,12 @@ class RunAs: principal that the pipeline runs as. If not specified, the pipeline runs as the user who created the pipeline. - Only `user_name` or `service_principal_name` can be specified. If both are specified, an error - is thrown.""" + Only ``user_name`` or ``service_principal_name`` can be specified. If both are specified, an + error is thrown.""" service_principal_name: Optional[str] = None """Application ID of an active service principal. Setting this field requires the - `servicePrincipal/user` role.""" + ``servicePrincipal/user`` role.""" user_name: Optional[str] = None """The email of an active workspace user. Users can only set this field to their own email.""" @@ -4406,13 +4409,13 @@ class TableSpecificConfig: """A list of column names to be excluded for the ingestion. When not specified, include_columns fully controls what columns to be ingested. When specified, all other columns including future ones will be automatically included for ingestion. This field in mutually exclusive with - `include_columns`.""" + ``include_columns``.""" include_columns: Optional[List[str]] = None """A list of column names to be included for the ingestion. When not specified, all columns except ones in exclude_columns will be included. Future columns will be automatically included. When specified, all other future columns will be automatically excluded from ingestion. This field in - mutually exclusive with `exclude_columns`.""" + mutually exclusive with ``exclude_columns``.""" primary_keys: Optional[List[str]] = None """The primary key of the table used to apply changes.""" @@ -5017,7 +5020,7 @@ def wait_get_pipeline_idle( raise TimeoutError(f"timed out after {timeout}: {status_message}") def apply_environment(self, pipeline_id: str) -> ApplyEnvironmentRequestResponse: - """* Applies the current pipeline environment onto the pipeline compute. The environment applied can be + """Applies the current pipeline environment onto the pipeline compute. The environment applied can be used by subsequent dev-mode updates. :param pipeline_id: str @@ -5083,9 +5086,10 @@ def clone( :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. + 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) SDP Release Channel that specifies which version to use. :param clone_mode: :class:`CloneMode` (optional) @@ -5095,7 +5099,7 @@ def clone( :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`. + Whether the pipeline is continuous or triggered. This replaces ``trigger``. :param deployment: :class:`PipelineDeployment` (optional) Deployment type of this pipeline. :param development: bool (optional) @@ -5142,11 +5146,11 @@ def clone( A map of tags associated with the pipeline. These are forwarded to the cluster as cluster tags, and are therefore subject to the same limitations. A maximum of 25 tags can be added to the pipeline. :param target: str (optional) - Target schema (database) to add tables in this pipeline to. Exactly one of `schema` or `target` must - be specified. To publish to Unity Catalog, also specify `catalog`. This legacy field is deprecated - for pipeline creation in favor of the `schema` field. + Target schema (database) to add tables in this pipeline to. Exactly one of ``schema`` or ``target`` + must be specified. To publish to Unity Catalog, also specify ``catalog``. This legacy field is + deprecated for pipeline creation in favor of the ``schema`` field. :param trigger: :class:`PipelineTrigger` (optional) - Which pipeline trigger to use. Deprecated: Use `continuous` instead. + Which pipeline trigger to use. Deprecated: Use ``continuous`` instead. :param usage_policy_id: str (optional) Usage policy of this pipeline. @@ -5272,9 +5276,10 @@ def create( :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. + 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) SDP Release Channel that specifies which version to use. :param clusters: List[:class:`PipelineCluster`] (optional) @@ -5282,7 +5287,7 @@ def create( :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`. + Whether the pipeline is continuous or triggered. This replaces ``trigger``. :param deployment: :class:`PipelineDeployment` (optional) Deployment type of this pipeline. :param development: bool (optional) @@ -5331,11 +5336,11 @@ def create( A map of tags associated with the pipeline. These are forwarded to the cluster as cluster tags, and are therefore subject to the same limitations. A maximum of 25 tags can be added to the pipeline. :param target: str (optional) - Target schema (database) to add tables in this pipeline to. Exactly one of `schema` or `target` must - be specified. To publish to Unity Catalog, also specify `catalog`. This legacy field is deprecated - for pipeline creation in favor of the `schema` field. + Target schema (database) to add tables in this pipeline to. Exactly one of ``schema`` or ``target`` + must be specified. To publish to Unity Catalog, also specify ``catalog``. This legacy field is + deprecated for pipeline creation in favor of the ``schema`` field. :param trigger: :class:`PipelineTrigger` (optional) - Which pipeline trigger to use. Deprecated: Use `continuous` instead. + Which pipeline trigger to use. Deprecated: Use ``continuous`` instead. :param usage_policy_id: str (optional) Usage policy of this pipeline. @@ -5545,8 +5550,12 @@ def list_pipeline_events( The pipeline to return events for. :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 >=,<,<=,=) + 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' @@ -5604,9 +5613,9 @@ def list_pipelines( :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%'` + - ``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) @@ -5866,9 +5875,10 @@ def update( :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. + 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) SDP Release Channel that specifies which version to use. :param clusters: List[:class:`PipelineCluster`] (optional) @@ -5876,7 +5886,7 @@ def update( :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`. + Whether the pipeline is continuous or triggered. This replaces ``trigger``. :param deployment: :class:`PipelineDeployment` (optional) Deployment type of this pipeline. :param development: bool (optional) @@ -5927,11 +5937,11 @@ def update( A map of tags associated with the pipeline. These are forwarded to the cluster as cluster tags, and are therefore subject to the same limitations. A maximum of 25 tags can be added to the pipeline. :param target: str (optional) - Target schema (database) to add tables in this pipeline to. Exactly one of `schema` or `target` must - be specified. To publish to Unity Catalog, also specify `catalog`. This legacy field is deprecated - for pipeline creation in favor of the `schema` field. + Target schema (database) to add tables in this pipeline to. Exactly one of ``schema`` or ``target`` + must be specified. To publish to Unity Catalog, also specify ``catalog``. This legacy field is + deprecated for pipeline creation in favor of the ``schema`` field. :param trigger: :class:`PipelineTrigger` (optional) - Which pipeline trigger to use. Deprecated: Use `continuous` instead. + Which pipeline trigger to use. Deprecated: Use ``continuous`` instead. :param usage_policy_id: str (optional) Usage policy of this pipeline. diff --git a/databricks/sdk/service/provisioning.py b/databricks/sdk/service/provisioning.py index bf82e9b24..c041acd7a 100755 --- a/databricks/sdk/service/provisioning.py +++ b/databricks/sdk/service/provisioning.py @@ -65,9 +65,9 @@ class AwsKeyInfo: """The AWS KMS key alias.""" reuse_key_for_cluster_volumes: Optional[bool] = None - """This field applies only if the `use_cases` property includes `STORAGE`. If this is set to true - or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use this - key for encrypting EBS volumes, set to false.""" + """This field applies only if the ``use_cases`` property includes ``STORAGE``. If this is set to + true or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use + this key for encrypting EBS volumes, set to false.""" def as_dict(self) -> dict: """Serializes the AwsKeyInfo into a dictionary suitable for use as a JSON request body.""" @@ -243,9 +243,9 @@ class CreateAwsKeyInfo: """The AWS KMS key region.""" reuse_key_for_cluster_volumes: Optional[bool] = None - """This field applies only if the `use_cases` property includes `STORAGE`. If this is set to true - or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use this - key for encrypting EBS volumes, set to false.""" + """This field applies only if the ``use_cases`` property includes ``STORAGE``. If this is set to + true or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use + this key for encrypting EBS volumes, set to false.""" def as_dict(self) -> dict: """Serializes the CreateAwsKeyInfo into a dictionary suitable for use as a JSON request body.""" @@ -950,10 +950,10 @@ def from_dict(cls, d: Dict[str, Any]) -> GkeConfig: class GkeConfigConnectivityType(Enum): """Specifies the network connectivity types for the GKE nodes and the GKE master network. - Set to `PRIVATE_NODE_PUBLIC_MASTER` for a private GKE cluster for the workspace. The GKE nodes + Set to ``PRIVATE_NODE_PUBLIC_MASTER`` for a private GKE cluster for the workspace. The GKE nodes will not have public IPs. - Set to `PUBLIC_NODE_PUBLIC_MASTER` for a public GKE cluster. The nodes of a public GKE cluster + Set to ``PUBLIC_NODE_PUBLIC_MASTER`` for a public GKE cluster. The nodes of a public GKE cluster have public IP addresses.""" PRIVATE_NODE_PUBLIC_MASTER = "PRIVATE_NODE_PUBLIC_MASTER" @@ -1225,7 +1225,7 @@ class PrivateAccessLevel(Enum): @dataclass class PrivateAccessSettings: - """*""" + """""" account_id: Optional[str] = None """The Databricks account ID that hosts the private access settings.""" @@ -1241,9 +1241,9 @@ class PrivateAccessSettings: private_access_level: Optional[PrivateAccessLevel] = None """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 + 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 + your workspace. ``ENDPOINT`` level access allows only specified VPC endpoints connect to your workspace. For details, see allowed_vpc_endpoint_ids.""" private_access_settings_id: Optional[str] = None @@ -1435,21 +1435,21 @@ def from_dict(cls, d: Dict[str, Any]) -> StsRole: @dataclass class VpcEndpoint: - """*""" + """""" account_id: Optional[str] = None - """The Databricks account ID that hosts the VPC endpoint configuration.""" + """The Databricks account ID that hosts the VPC endpoint configuration. TODO - This may signal an + OpenAPI diff; it does not show up in the generated spec""" aws_account_id: Optional[str] = None """The AWS Account in which the VPC endpoint object exists.""" aws_endpoint_service_id: Optional[str] = None - """The ID of the Databricks [endpoint service] that this VPC endpoint is connected to. For a list - of endpoint service IDs for each supported AWS region, see the [Databricks PrivateLink - documentation]. - - [Databricks PrivateLink documentation]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html - [endpoint service]: https://docs.aws.amazon.com/vpc/latest/privatelink/endpoint-service.html""" + """The ID of the Databricks `endpoint service + `__ that this VPC + endpoint is connected to. For a list of endpoint service IDs for each supported AWS region, see + the `Databricks PrivateLink documentation + `__.""" aws_vpc_endpoint_id: Optional[str] = None """The ID of the VPC endpoint object in AWS.""" @@ -1461,10 +1461,9 @@ class VpcEndpoint: """The AWS region in which this VPC endpoint object exists.""" state: Optional[str] = None - """The current state (such as `available` or `rejected`) of the VPC endpoint. Derived from AWS. For - the full set of values, see [AWS DescribeVpcEndpoint documentation]. - - [AWS DescribeVpcEndpoint documentation]: https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-vpc-endpoints.html""" + """The current state (such as ``available`` or ``rejected``) of the VPC endpoint. Derived from AWS. + For the full set of values, see `AWS DescribeVpcEndpoint documentation + `__.""" use_case: Optional[EndpointUseCase] = None """This enumeration represents the type of Databricks VPC endpoint service that was used when @@ -1475,7 +1474,7 @@ class VpcEndpoint: vpc_endpoint_id: Optional[str] = None """Databricks VPC endpoint ID. This is the Databricks-specific name of the VPC endpoint. Do not - confuse this with the `aws_vpc_endpoint_id`, which is the ID within AWS of the VPC endpoint.""" + confuse this with the ``aws_vpc_endpoint_id``, which is the ID within AWS of the VPC endpoint.""" vpc_endpoint_name: Optional[str] = None """The human-readable name of the storage configuration.""" @@ -1569,7 +1568,7 @@ class Workspace: azure_workspace_info: Optional[AzureWorkspaceInfo] = None cloud: Optional[str] = None - """The cloud name. This field can have values like `azure`, `gcp`.""" + """The cloud name. This field can have values like ``azure``, ``gcp``.""" cloud_resource_container: Optional[CloudResourceContainer] = None @@ -1599,7 +1598,7 @@ class Workspace: location: Optional[str] = None """The Google Cloud region of the workspace data plane in your Google account (for example, - `us-east4`).""" + ``us-east4``).""" managed_services_customer_managed_key_id: Optional[str] = None """ID of the key configuration for encrypting managed services.""" @@ -1607,7 +1606,7 @@ class Workspace: network: Optional[WorkspaceNetwork] = None """The network configuration for the workspace. - DEPRECATED. Use `network_id` instead.""" + DEPRECATED. Use ``network_id`` instead.""" network_connectivity_config_id: Optional[str] = None """The object ID of network connectivity config.""" @@ -1620,13 +1619,12 @@ class Workspace: private_access_settings_id: Optional[str] = None """ID of the workspace's private access settings object. Only used for PrivateLink. You must - specify this ID if you are 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].", + specify this ID if you are using `AWS PrivateLink `__ for + either front-end (user-to-workspace connection), back-end (data plane to control plane + connection), or both connection types. - [AWS PrivateLink]: https://aws.amazon.com/privatelink/ - [Databricks article about PrivateLink]: https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html""" + Before configuring PrivateLink, read the `Databricks article about PrivateLink + `__.",""" storage_configuration_id: Optional[str] = None """ID of the workspace's storage configuration object.""" @@ -1884,13 +1882,11 @@ def create(self, credentials_name: str, aws_credentials: CreateCredentialAwsCred 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 + 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 + For information about how to create a new workspace with this API, see `Create a new workspace using + the Account API `__ :param credentials_name: str The human-readable name of the credential configuration object. @@ -1969,9 +1965,9 @@ class EncryptionKeysAPI: 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. + - 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 @@ -2005,12 +2001,11 @@ def create( custom plan that allows multiple workspaces per account. **GCP only**: To create a customer-managed key on GCP, you must include the - `X-Databricks-GCP-SA-Access-Token` HTTP header in your request. This header must contain a Google - Cloud OAuth access token with the `cloud-platform` scope. The Google identity associated with the - token must also have the `setIamPermissions` and `getIamPermissions` IAM permissions on the key - resource. For details on obtaining this token, see [Authenticate with Google ID tokens]. - - [Authenticate with Google ID tokens]: https://docs.databricks.com/gcp/en/dev-tools/auth/authentication-google-id.html + ``X-Databricks-GCP-SA-Access-Token`` HTTP header in your request. This header must contain a Google + Cloud OAuth access token with the ``cloud-platform`` scope. The Google identity associated with the + token must also have the ``setIamPermissions`` and ``getIamPermissions`` IAM permissions on the key + resource. For details on obtaining this token, see `Authenticate with Google ID tokens + `__. :param use_cases: List[:class:`KeyUseCase`] The cases that the key can be used for. @@ -2244,10 +2239,10 @@ def create( internet, see IP access lists. :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. + 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 private_access_settings_name: str (optional) The human-readable name of the private access settings object. :param public_access_enabled: bool (optional) @@ -2484,18 +2479,16 @@ def create( region: Optional[str] = None, vpc_endpoint_name: Optional[str] = None, ) -> VpcEndpoint: - """Creates a VPC endpoint configuration, which represents a [VPC endpoint] object in AWS used to - communicate privately with Databricks over [AWS PrivateLink]. + """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. + 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 + Before configuring PrivateLink, read the `Databricks article about PrivateLink + `__. :param aws_vpc_endpoint_id: str (optional) The ID of the VPC endpoint object in AWS. @@ -2547,11 +2540,9 @@ def delete(self, vpc_endpoint_id: str) -> VpcEndpoint: return VpcEndpoint.from_dict(res) def get(self, vpc_endpoint_id: str) -> 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 + """Gets a VPC endpoint configuration, which represents a `VPC endpoint + `__ object in AWS used to + communicate privately with Databricks over `AWS PrivateLink `__. :param vpc_endpoint_id: str Databricks VPC endpoint ID. @@ -2667,7 +2658,8 @@ def create( information, you cannot reuse a Databricks Account API network configuration across workspaces. For information about how to create a new workspace with this API including error handling, see - [Create a new workspace using the Account API]. + `Create a new workspace using the Account API + `__. Important: Customer-managed VPCs, PrivateLink, and customer-managed keys are supported on a limited set of deployment and subscription types. If you have questions about availability, contact your @@ -2676,18 +2668,16 @@ def create( 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 aws_region: str (optional) :param cloud: str (optional) DEPRECATED: This field is being ignored by the server and will be removed in the future. The cloud - name. This field always has the value `gcp`. + name. This field always has the value ``gcp``. :param cloud_resource_container: :class:`CloudResourceContainer` (optional) :param compute_mode: :class:`CustomerFacingComputeMode` (optional) - If the compute mode is `SERVERLESS`, a serverless workspace is created that comes pre-configured + If the compute mode is ``SERVERLESS``, a serverless workspace is created that comes pre-configured with serverless compute and default storage, providing a fully-managed, enterprise-ready SaaS experience. This means you don't need to provide any resources managed by you, such as credentials, - storage, or network. If the compute mode is `HYBRID` (which is the default option), a classic + storage, or network. If the compute mode is ``HYBRID`` (which is the default option), a classic workspace is created that uses customer-managed resources. :param credentials_id: str (optional) ID of the workspace's credential configuration object. @@ -2715,7 +2705,7 @@ def create( :param gke_config: :class:`GkeConfig` (optional) :param location: str (optional) The Google Cloud region of the workspace data plane in your Google account (for example, - `us-east4`). + ``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 @@ -2730,12 +2720,10 @@ def create( :param pricing_tier: :class:`PricingTier` (optional) :param private_access_settings_id: str (optional) ID of the workspace's private access settings object. Only used for PrivateLink. You must specify - this ID if you are 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 + this ID if you are 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 + `__.", :param storage_configuration_id: str (optional) ID of the workspace's storage configuration object. :param storage_customer_managed_key_id: str (optional) @@ -2864,13 +2852,11 @@ def delete(self, workspace_id: int) -> Workspace: def get(self, workspace_id: int) -> 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]. - - [Create a new workspace using the Account API]: http://docs.databricks.com/administration-guide/account-api/new-workspace.html + ``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 `__. :param workspace_id: int @@ -2910,14 +2896,14 @@ def update( :param customer_facing_workspace: :class:`Workspace` :param update_mask: str (optional) The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: Long-running operation waiter for :class:`Workspace`. diff --git a/databricks/sdk/service/qualitymonitorv2.py b/databricks/sdk/service/qualitymonitorv2.py index 2964142a5..c3053a33a 100755 --- a/databricks/sdk/service/qualitymonitorv2.py +++ b/databricks/sdk/service/qualitymonitorv2.py @@ -313,7 +313,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ValidityCheckConfiguration: class QualityMonitorV2API: """Deprecated: Please use the Data Quality Monitoring API instead (REST: /api/data-quality/v1/monitors). - Manage data quality of UC objects (currently support `schema`).""" + Manage data quality of UC objects (currently support ``schema``).""" def __init__(self, api_client): self._api = api_client diff --git a/databricks/sdk/service/serving.py b/databricks/sdk/service/serving.py index 36da5cf71..35593d5d9 100755 --- a/databricks/sdk/service/serving.py +++ b/databricks/sdk/service/serving.py @@ -35,13 +35,13 @@ class Ai21LabsConfig: ai21labs_api_key: Optional[str] = None """The Databricks secret key reference for an AI21 Labs API key. If you prefer to paste your API - key directly, see `ai21labs_api_key_plaintext`. You must provide an API key using one of the - following fields: `ai21labs_api_key` or `ai21labs_api_key_plaintext`.""" + key directly, see ``ai21labs_api_key_plaintext``. You must provide an API key using one of the + following fields: ``ai21labs_api_key`` or ``ai21labs_api_key_plaintext``.""" ai21labs_api_key_plaintext: Optional[str] = None """An AI21 Labs API key provided as a plaintext string. If you prefer to reference your key using - Databricks Secrets, see `ai21labs_api_key`. You must provide an API key using one of the - following fields: `ai21labs_api_key` or `ai21labs_api_key_plaintext`.""" + Databricks Secrets, see ``ai21labs_api_key``. You must provide an API key using one of the + following fields: ``ai21labs_api_key`` or ``ai21labs_api_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the Ai21LabsConfig into a dictionary suitable for use as a JSON request body.""" @@ -415,32 +415,32 @@ class AmazonBedrockConfig: aws_access_key_id: Optional[str] = None """The Databricks secret key reference for an AWS access key ID with permissions to interact with Bedrock services. If you prefer to paste your API key directly, see - `aws_access_key_id_plaintext`. You must provide an API key using one of the following fields: - `aws_access_key_id` or `aws_access_key_id_plaintext`.""" + ``aws_access_key_id_plaintext``. You must provide an API key using one of the following fields: + ``aws_access_key_id`` or ``aws_access_key_id_plaintext``.""" aws_access_key_id_plaintext: Optional[str] = None """An AWS access key ID with permissions to interact with Bedrock services provided as a plaintext - string. If you prefer to reference your key using Databricks Secrets, see `aws_access_key_id`. - You must provide an API key using one of the following fields: `aws_access_key_id` or - `aws_access_key_id_plaintext`.""" + string. If you prefer to reference your key using Databricks Secrets, see ``aws_access_key_id``. + You must provide an API key using one of the following fields: ``aws_access_key_id`` or + ``aws_access_key_id_plaintext``.""" aws_secret_access_key: Optional[str] = None """The Databricks secret key reference for an AWS secret access key paired with the access key ID, with permissions to interact with Bedrock services. If you prefer to paste your API key - directly, see `aws_secret_access_key_plaintext`. You must provide an API key using one of the - following fields: `aws_secret_access_key` or `aws_secret_access_key_plaintext`.""" + directly, see ``aws_secret_access_key_plaintext``. You must provide an API key using one of the + following fields: ``aws_secret_access_key`` or ``aws_secret_access_key_plaintext``.""" aws_secret_access_key_plaintext: Optional[str] = None """An AWS secret access key paired with the access key ID, with permissions to interact with Bedrock services provided as a plaintext string. If you prefer to reference your key using - Databricks Secrets, see `aws_secret_access_key`. You must provide an API key using one of the - following fields: `aws_secret_access_key` or `aws_secret_access_key_plaintext`.""" + Databricks Secrets, see ``aws_secret_access_key``. You must provide an API key using one of the + following fields: ``aws_secret_access_key`` or ``aws_secret_access_key_plaintext``.""" instance_profile_arn: Optional[str] = None """ARN of the instance profile that the external model will use to access AWS resources. You must authenticate using an instance profile or access keys. If you prefer to authenticate using - access keys, see `aws_access_key_id`, `aws_access_key_id_plaintext`, `aws_secret_access_key` and - `aws_secret_access_key_plaintext`.""" + access keys, see ``aws_access_key_id``, ``aws_access_key_id_plaintext``, + ``aws_secret_access_key`` and ``aws_secret_access_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the AmazonBedrockConfig into a dictionary suitable for use as a JSON request body.""" @@ -505,13 +505,13 @@ class AmazonBedrockConfigBedrockProvider(Enum): class AnthropicConfig: anthropic_api_key: Optional[str] = None """The Databricks secret key reference for an Anthropic API key. If you prefer to paste your API - key directly, see `anthropic_api_key_plaintext`. You must provide an API key using one of the - following fields: `anthropic_api_key` or `anthropic_api_key_plaintext`.""" + key directly, see ``anthropic_api_key_plaintext``. You must provide an API key using one of the + following fields: ``anthropic_api_key`` or ``anthropic_api_key_plaintext``.""" anthropic_api_key_plaintext: Optional[str] = None """The Anthropic API key provided as a plaintext string. If you prefer to reference your key using - Databricks Secrets, see `anthropic_api_key`. You must provide an API key using one of the - following fields: `anthropic_api_key` or `anthropic_api_key_plaintext`.""" + Databricks Secrets, see ``anthropic_api_key``. You must provide an API key using one of the + following fields: ``anthropic_api_key`` or ``anthropic_api_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the AnthropicConfig into a dictionary suitable for use as a JSON request body.""" @@ -547,11 +547,11 @@ class ApiKeyAuth: value: Optional[str] = None """The Databricks secret key reference for an API Key. If you prefer to paste your token directly, - see `value_plaintext`.""" + see ``value_plaintext``.""" value_plaintext: Optional[str] = None """The API Key provided as a plaintext string. If you prefer to reference your token using - Databricks Secrets, see `value`.""" + Databricks Secrets, see ``value``.""" def as_dict(self) -> dict: """Serializes the ApiKeyAuth into a dictionary suitable for use as a JSON request body.""" @@ -730,11 +730,11 @@ def from_dict(cls, d: Dict[str, Any]) -> AutoCaptureState: class BearerTokenAuth: token: Optional[str] = None """The Databricks secret key reference for a token. If you prefer to paste your token directly, see - `token_plaintext`.""" + ``token_plaintext``.""" token_plaintext: Optional[str] = None """The token provided as a plaintext string. If you prefer to reference your token using Databricks - Secrets, see `token`.""" + Secrets, see ``token``.""" def as_dict(self) -> dict: """Serializes the BearerTokenAuth into a dictionary suitable for use as a JSON request body.""" @@ -833,13 +833,13 @@ class CohereConfig: cohere_api_key: Optional[str] = None """The Databricks secret key reference for a Cohere API key. If you prefer to paste your API key - directly, see `cohere_api_key_plaintext`. You must provide an API key using one of the following - fields: `cohere_api_key` or `cohere_api_key_plaintext`.""" + directly, see ``cohere_api_key_plaintext``. You must provide an API key using one of the + following fields: ``cohere_api_key`` or ``cohere_api_key_plaintext``.""" cohere_api_key_plaintext: Optional[str] = None """The Cohere API key provided as a plaintext string. If you prefer to reference your key using - Databricks Secrets, see `cohere_api_key`. You must provide an API key using one of the following - fields: `cohere_api_key` or `cohere_api_key_plaintext`.""" + Databricks Secrets, see ``cohere_api_key``. You must provide an API key using one of the + following fields: ``cohere_api_key`` or ``cohere_api_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the CohereConfig into a dictionary suitable for use as a JSON request body.""" @@ -964,15 +964,15 @@ class DatabricksModelServingConfig: """The Databricks secret key reference for a Databricks API token that corresponds to a user or service principal with Can Query access to the model serving endpoint pointed to by this external model. If you prefer to paste your API key directly, see - `databricks_api_token_plaintext`. You must provide an API key using one of the following fields: - `databricks_api_token` or `databricks_api_token_plaintext`.""" + ``databricks_api_token_plaintext``. You must provide an API key using one of the following + fields: ``databricks_api_token`` or ``databricks_api_token_plaintext``.""" databricks_api_token_plaintext: Optional[str] = None """The Databricks API token that corresponds to a user or service principal with Can Query access to the model serving endpoint pointed to by this external model provided as a plaintext string. - If you prefer to reference your key using Databricks Secrets, see `databricks_api_token`. You - must provide an API key using one of the following fields: `databricks_api_token` or - `databricks_api_token_plaintext`.""" + If you prefer to reference your key using Databricks Secrets, see ``databricks_api_token``. You + must provide an API key using one of the following fields: ``databricks_api_token`` or + ``databricks_api_token_plaintext``.""" def as_dict(self) -> dict: """Serializes the DatabricksModelServingConfig into a dictionary suitable for use as a JSON request body.""" @@ -1808,28 +1808,23 @@ class GoogleCloudVertexAiConfig: """This is the Google Cloud project id that the service account is associated with.""" region: str - """This is the region for the Google Cloud Vertex AI Service. See [supported regions] for more - details. Some models are only available in specific regions. - - [supported regions]: https://cloud.google.com/vertex-ai/docs/general/locations""" + """This is the region for the Google Cloud Vertex AI Service. See `supported regions + `__ for more details. Some models are + only available in specific regions.""" private_key: Optional[str] = None """The Databricks secret key reference for a private key for the service account which has access - to the Google Cloud Vertex AI Service. See [Best practices for managing service account keys]. - If you prefer to paste your API key directly, see `private_key_plaintext`. You must provide an - API key using one of the following fields: `private_key` or `private_key_plaintext` - - [Best practices for managing service account keys]: - https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys""" + to the Google Cloud Vertex AI Service. See `Best practices for managing service account keys + `__. If you + prefer to paste your API key directly, see ``private_key_plaintext``. You must provide an API + key using one of the following fields: ``private_key`` or ``private_key_plaintext``""" private_key_plaintext: Optional[str] = None """The private key for the service account which has access to the Google Cloud Vertex AI Service - provided as a plaintext secret. See [Best practices for managing service account keys]. If you - prefer to reference your key using Databricks Secrets, see `private_key`. You must provide an - API key using one of the following fields: `private_key` or `private_key_plaintext`. - - [Best practices for managing service account keys]: - https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys""" + provided as a plaintext secret. See `Best practices for managing service account keys + `__. If you + prefer to reference your key using Databricks Secrets, see ``private_key``. You must provide an + API key using one of the following fields: ``private_key`` or ``private_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the GoogleCloudVertexAiConfig into a dictionary suitable for use as a JSON request body.""" @@ -1955,14 +1950,15 @@ class OpenAiConfig: microsoft_entra_client_secret: Optional[str] = None """The Databricks secret key reference for a client secret used for Microsoft Entra ID authentication. If you prefer to paste your client secret directly, see - `microsoft_entra_client_secret_plaintext`. You must provide an API key using one of the - following fields: `microsoft_entra_client_secret` or `microsoft_entra_client_secret_plaintext`.""" + ``microsoft_entra_client_secret_plaintext``. You must provide an API key using one of the + following fields: ``microsoft_entra_client_secret`` or + ``microsoft_entra_client_secret_plaintext``.""" microsoft_entra_client_secret_plaintext: Optional[str] = None """The client secret used for Microsoft Entra ID authentication provided as a plaintext string. If - you prefer to reference your key using Databricks Secrets, see `microsoft_entra_client_secret`. - You must provide an API key using one of the following fields: `microsoft_entra_client_secret` - or `microsoft_entra_client_secret_plaintext`.""" + you prefer to reference your key using Databricks Secrets, see + ``microsoft_entra_client_secret``. You must provide an API key using one of the following + fields: ``microsoft_entra_client_secret`` or ``microsoft_entra_client_secret_plaintext``.""" microsoft_entra_tenant_id: Optional[str] = None """This field is only required for Azure AD OpenAI and is the Microsoft Entra Tenant ID.""" @@ -1975,13 +1971,14 @@ class OpenAiConfig: openai_api_key: Optional[str] = None """The Databricks secret key reference for an OpenAI API key using the OpenAI or Azure service. If - you prefer to paste your API key directly, see `openai_api_key_plaintext`. You must provide an - API key using one of the following fields: `openai_api_key` or `openai_api_key_plaintext`.""" + you prefer to paste your API key directly, see ``openai_api_key_plaintext``. You must provide an + API key using one of the following fields: ``openai_api_key`` or ``openai_api_key_plaintext``.""" openai_api_key_plaintext: Optional[str] = None """The OpenAI API key using the OpenAI or Azure service provided as a plaintext string. If you - prefer to reference your key using Databricks Secrets, see `openai_api_key`. You must provide an - API key using one of the following fields: `openai_api_key` or `openai_api_key_plaintext`.""" + prefer to reference your key using Databricks Secrets, see ``openai_api_key``. You must provide + an API key using one of the following fields: ``openai_api_key`` or + ``openai_api_key_plaintext``.""" openai_api_type: Optional[str] = None """This is an optional field to specify the type of OpenAI API to use. For Azure OpenAI, this field @@ -2076,13 +2073,13 @@ def from_dict(cls, d: Dict[str, Any]) -> OpenAiConfig: class PaLmConfig: palm_api_key: Optional[str] = None """The Databricks secret key reference for a PaLM API key. If you prefer to paste your API key - directly, see `palm_api_key_plaintext`. You must provide an API key using one of the following - fields: `palm_api_key` or `palm_api_key_plaintext`.""" + directly, see ``palm_api_key_plaintext``. You must provide an API key using one of the following + fields: ``palm_api_key`` or ``palm_api_key_plaintext``.""" palm_api_key_plaintext: Optional[str] = None """The PaLM API key provided as a plaintext string. If you prefer to reference your key using - Databricks Secrets, see `palm_api_key`. You must provide an API key using one of the following - fields: `palm_api_key` or `palm_api_key_plaintext`.""" + Databricks Secrets, see ``palm_api_key``. You must provide an API key using one of the following + fields: ``palm_api_key`` or ``palm_api_key_plaintext``.""" def as_dict(self) -> dict: """Serializes the PaLmConfig into a dictionary suitable for use as a JSON request body.""" @@ -2337,27 +2334,27 @@ def from_dict(cls, d: Dict[str, Any]) -> PutResponse: @dataclass class QueryEndpointResponse: choices: Optional[List[V1ResponseChoiceElement]] = None - """The list of choices returned by the __chat or completions external/foundation model__ serving + """The list of choices returned by the **chat or completions external/foundation model** serving endpoint.""" created: Optional[int] = None - """The timestamp in seconds when the query was created in Unix time returned by a __completions or - chat external/foundation model__ serving endpoint.""" + """The timestamp in seconds when the query was created in Unix time returned by a **completions or + chat external/foundation model** serving endpoint.""" data: Optional[List[EmbeddingsV1ResponseEmbeddingElement]] = None - """The list of the embeddings returned by the __embeddings external/foundation model__ serving + """The list of the embeddings returned by the **embeddings external/foundation model** serving endpoint.""" id: Optional[str] = None - """The ID of the query that may be returned by a __completions or chat external/foundation model__ + """The ID of the query that may be returned by a **completions or chat external/foundation model** serving endpoint.""" model: Optional[str] = None - """The name of the __external/foundation model__ used for querying. This is the name of the model + """The name of the **external/foundation model** used for querying. This is the name of the model that was specified in the endpoint config.""" object: Optional[QueryEndpointResponseObject] = None - """The type of object returned by the __external/foundation model__ serving endpoint, one of + """The type of object returned by the **external/foundation model** serving endpoint, one of [text_completion, chat.completion, list (of embeddings)].""" outputs: Optional[List[any]] = None @@ -2371,7 +2368,7 @@ class QueryEndpointResponse: models behind the same endpoint with traffic split.""" usage: Optional[ExternalModelUsageElement] = None - """The usage object that may be returned by the __external/foundation model__ serving endpoint. + """The usage object that may be returned by the **external/foundation model** serving endpoint. This contains information about the number of tokens used in the prompt and response.""" def as_dict(self) -> dict: @@ -2442,7 +2439,7 @@ def from_dict(cls, d: Dict[str, Any]) -> QueryEndpointResponse: class QueryEndpointResponseObject(Enum): - """The type of object returned by the __external/foundation model__ serving endpoint, one of + """The type of object returned by the **external/foundation model** serving endpoint, one of [text_completion, chat.completion, list (of embeddings)].""" CHAT_COMPLETION = "chat.completion" @@ -2564,8 +2561,8 @@ class ServedEntityInput: environment_vars: Optional[Dict[str, str]] = None """An object containing a set of optional, user-specified environment variable key-value pairs used for serving this entity. Note: this is an experimental feature and subject to change. Example - entity environment variables that refer to Databricks secrets: `{"OPENAI_API_KEY": - "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}`""" + entity environment variables that refer to Databricks secrets: ``{"OPENAI_API_KEY": + "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}``""" external_model: Optional[ExternalModel] = None """The external model to be served. NOTE: Only one of external_model and (entity_name, @@ -2617,9 +2614,8 @@ class ServedEntityInput: """The workload type of the served entity. The workload type selects which type of compute to use in the endpoint. The default value for this parameter is "CPU". For deep learning workloads, GPU acceleration is available by selecting workload types like GPU_SMALL and others. See the - available [GPU types]. - - [GPU types]: https://docs.databricks.com/en/machine-learning/model-serving/create-manage-serving-endpoints.html#gpu-workload-types""" + available `GPU types + `__.""" def as_dict(self) -> dict: """Serializes the ServedEntityInput into a dictionary suitable for use as a JSON request body.""" @@ -2735,8 +2731,8 @@ class ServedEntityOutput: environment_vars: Optional[Dict[str, str]] = None """An object containing a set of optional, user-specified environment variable key-value pairs used for serving this entity. Note: this is an experimental feature and subject to change. Example - entity environment variables that refer to Databricks secrets: `{"OPENAI_API_KEY": - "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}`""" + entity environment variables that refer to Databricks secrets: ``{"OPENAI_API_KEY": + "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}``""" external_model: Optional[ExternalModel] = None """The external model to be served. NOTE: Only one of external_model and (entity_name, @@ -2792,9 +2788,8 @@ class ServedEntityOutput: """The workload type of the served entity. The workload type selects which type of compute to use in the endpoint. The default value for this parameter is "CPU". For deep learning workloads, GPU acceleration is available by selecting workload types like GPU_SMALL and others. See the - available [GPU types]. - - [GPU types]: https://docs.databricks.com/en/machine-learning/model-serving/create-manage-serving-endpoints.html#gpu-workload-types""" + available `GPU types + `__.""" def as_dict(self) -> dict: """Serializes the ServedEntityOutput into a dictionary suitable for use as a JSON request body.""" @@ -2979,8 +2974,8 @@ class ServedModelInput: environment_vars: Optional[Dict[str, str]] = None """An object containing a set of optional, user-specified environment variable key-value pairs used for serving this entity. Note: this is an experimental feature and subject to change. Example - entity environment variables that refer to Databricks secrets: `{"OPENAI_API_KEY": - "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}`""" + entity environment variables that refer to Databricks secrets: ``{"OPENAI_API_KEY": + "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}``""" instance_profile_arn: Optional[str] = None """ARN of the instance profile that the served entity uses to access AWS resources.""" @@ -3021,9 +3016,8 @@ class ServedModelInput: """The workload type of the served entity. The workload type selects which type of compute to use in the endpoint. The default value for this parameter is "CPU". For deep learning workloads, GPU acceleration is available by selecting workload types like GPU_SMALL and others. See the - available [GPU types]. - - [GPU types]: https://docs.databricks.com/en/machine-learning/model-serving/create-manage-serving-endpoints.html#gpu-workload-types""" + available `GPU types + `__.""" def as_dict(self) -> dict: """Serializes the ServedModelInput into a dictionary suitable for use as a JSON request body.""" @@ -3137,8 +3131,8 @@ class ServedModelOutput: environment_vars: Optional[Dict[str, str]] = None """An object containing a set of optional, user-specified environment variable key-value pairs used for serving this entity. Note: this is an experimental feature and subject to change. Example - entity environment variables that refer to Databricks secrets: `{"OPENAI_API_KEY": - "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}`""" + entity environment variables that refer to Databricks secrets: ``{"OPENAI_API_KEY": + "{{secrets/my_scope/my_key}}", "DATABRICKS_TOKEN": "{{secrets/my_scope2/my_key2}}"}``""" instance_profile_arn: Optional[str] = None """ARN of the instance profile that the served entity uses to access AWS resources.""" @@ -3182,9 +3176,8 @@ class ServedModelOutput: """The workload type of the served entity. The workload type selects which type of compute to use in the endpoint. The default value for this parameter is "CPU". For deep learning workloads, GPU acceleration is available by selecting workload types like GPU_SMALL and others. See the - available [GPU types]. - - [GPU types]: https://docs.databricks.com/en/machine-learning/model-serving/create-manage-serving-endpoints.html#gpu-workload-types""" + available `GPU types + `__.""" def as_dict(self) -> dict: """Serializes the ServedModelOutput into a dictionary suitable for use as a JSON request body.""" @@ -3985,16 +3978,16 @@ class V1ResponseChoiceElement: """The finish reason returned by the endpoint.""" index: Optional[int] = None - """The index of the choice in the __chat or completions__ response.""" + """The index of the choice in the **chat or completions** response.""" logprobs: Optional[int] = None - """The logprobs returned only by the __completions__ endpoint.""" + """The logprobs returned only by the **completions** endpoint.""" message: Optional[ChatMessage] = None - """The message response from the __chat__ endpoint.""" + """The message response from the **chat** endpoint.""" text: Optional[str] = None - """The text response from the __completions__ endpoint.""" + """The text response from the **completions** endpoint.""" def as_dict(self) -> dict: """Serializes the V1ResponseChoiceElement into a dictionary suitable for use as a JSON request body.""" @@ -4445,8 +4438,8 @@ def http_request( :param sub_domain: str (optional) Optional subdomain to prepend to the connection URL's host. If provided, this will be added as a prefix to the connection URL's host. For example, if the connection URL is - `https://api.example.com/v1` and `sub_domain` is `"custom"`, the resulting URL will be - `https://custom.api.example.com/v1`. + ``https://api.example.com/v1`` and ``sub_domain`` is ``"custom"``, the resulting URL will be + ``https://custom.api.example.com/v1``. :returns: :class:`HttpRequestResponse` """ @@ -4666,40 +4659,40 @@ def query( :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 + 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 + 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 + 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 an + The messages field used ONLY for **chat external & foundation model** serving endpoints. This is an array of ChatMessage objects 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 + 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. + 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__ + 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 + 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 + 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. :param usage_context: Dict[str,str] (optional) @@ -5033,40 +5026,40 @@ def query( :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 + 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 + 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 + 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 an + The messages field used ONLY for **chat external & foundation model** serving endpoints. This is an array of ChatMessage objects 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 + 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. + 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__ + 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 + 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 + 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. :param usage_context: Dict[str,str] (optional) diff --git a/databricks/sdk/service/settings.py b/databricks/sdk/service/settings.py index 4e86b0ed2..c1b6d7e14 100755 --- a/databricks/sdk/service/settings.py +++ b/databricks/sdk/service/settings.py @@ -1978,12 +1978,15 @@ class CustomerFacingNetworkConnectivityConfigAwsPrivateEndpointRule: ] = None """The current status of this private endpoint. The private endpoint rules are effective only if the connection state is ESTABLISHED. Remember that you must approve new endpoints on your - resources in the AWS console before they take effect. The possible values are: - PENDING: The - endpoint has been created and pending approval. - ESTABLISHED: The endpoint has been approved - and is ready to use in your serverless compute resources. - REJECTED: Connection was rejected by - the private link resource owner. - DISCONNECTED: Connection was removed by the private link - resource owner, the private endpoint becomes informative and should be deleted for clean-up. - - EXPIRED: If the endpoint is created but not approved in 14 days, it is EXPIRED.""" + resources in the AWS console before they take effect. The possible values are: + + - PENDING: The endpoint has been created and pending approval. + - ESTABLISHED: The endpoint has been approved and is ready to use in your serverless compute + resources. + - REJECTED: Connection was rejected by the private link resource owner. + - DISCONNECTED: Connection was removed by the private link resource owner, the private endpoint + becomes informative and should be deleted for clean-up. + - EXPIRED: If the endpoint is created but not approved in 14 days, it is EXPIRED.""" creation_time: Optional[int] = None """Time in epoch milliseconds when this object was created.""" @@ -4439,8 +4442,9 @@ def from_dict(cls, d: Dict[str, Any]) -> ListTokensResponse: class ListType(Enum): """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.""" + - ``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.""" ALLOW = "ALLOW" BLOCK = "BLOCK" @@ -4732,13 +4736,16 @@ class NccAzurePrivateEndpointRule: connection_state: Optional[NccAzurePrivateEndpointRuleConnectionState] = None """The current status of this private endpoint. The private endpoint rules are effective only if the connection state is ESTABLISHED. Remember that you must approve new endpoints on your - resources in the Azure portal before they take effect. The possible values are: - INIT: - (deprecated) The endpoint has been created and pending approval. - PENDING: The endpoint has - been created and pending approval. - ESTABLISHED: The endpoint has been approved and is ready to - use in your serverless compute resources. - REJECTED: Connection was rejected by the private - link resource owner. - DISCONNECTED: Connection was removed by the private link resource owner, - the private endpoint becomes informative and should be deleted for clean-up. - EXPIRED: If the - endpoint was created but not approved in 14 days, it will be EXPIRED.""" + resources in the Azure portal before they take effect. The possible values are: + + - INIT: (deprecated) The endpoint has been created and pending approval. + - PENDING: The endpoint has been created and pending approval. + - ESTABLISHED: The endpoint has been approved and is ready to use in your serverless compute + resources. + - REJECTED: Connection was rejected by the private link resource owner. + - DISCONNECTED: Connection was removed by the private link resource owner, the private endpoint + becomes informative and should be deleted for clean-up. + - EXPIRED: If the endpoint was created but not approved in 14 days, it will be EXPIRED.""" creation_time: Optional[int] = None """Time in epoch milliseconds when this object was created.""" @@ -5036,15 +5043,19 @@ class NccPrivateEndpointRule: connection_state: Optional[NccPrivateEndpointRulePrivateLinkConnectionState] = None """The current status of this private endpoint. The private endpoint rules are effective only if the connection state is ESTABLISHED. Remember that you must approve new endpoints on your - resources in the Cloud console before they take effect. The possible values are: - PENDING: The - endpoint has been created and pending approval. - ESTABLISHED: The endpoint has been approved - and is ready to use in your serverless compute resources. - REJECTED: Connection was rejected by - the private link resource owner. - DISCONNECTED: Connection was removed by the private link - resource owner, the private endpoint becomes informative and should be deleted for clean-up. - - EXPIRED: If the endpoint was created but not approved in 14 days, it will be EXPIRED. - - CREATING: The endpoint creation is in progress. Once successfully created, the state will - transition to PENDING. - CREATE_FAILED: The endpoint creation failed. You can check the - error_message field for more details.""" + resources in the Cloud console before they take effect. The possible values are: + + - PENDING: The endpoint has been created and pending approval. + - ESTABLISHED: The endpoint has been approved and is ready to use in your serverless compute + resources. + - REJECTED: Connection was rejected by the private link resource owner. + - DISCONNECTED: Connection was removed by the private link resource owner, the private endpoint + becomes informative and should be deleted for clean-up. + - EXPIRED: If the endpoint was created but not approved in 14 days, it will be EXPIRED. + - CREATING: The endpoint creation is in progress. Once successfully created, the state will + transition to PENDING. + - CREATE_FAILED: The endpoint creation failed. You can check the error_message field for more + details.""" creation_time: Optional[int] = None """Time in epoch milliseconds when this object was created.""" @@ -5305,7 +5316,11 @@ def from_dict(cls, d: Dict[str, Any]) -> NetworkConnectivityConfiguration: @dataclass class NetworkPolicyEgress: - """The network policies applying for egress traffic.""" + """The network policies applying for egress traffic. This message is used by the UI/REST API. We + translate this message to the format expected by the dataplane in Lakehouse Network Manager (for + the format expected by the dataplane, see networkconfig.textproto). This policy should be + consistent with [[com.databricks.api.proto.settingspolicy.EgressNetworkPolicy]]. Details see + API-design: https://docs.google.com/document/d/1DKWO_FpZMCY4cF2O62LpwII1lx8gsnDGG-qgE3t3TOA/""" network_access: Optional[EgressNetworkPolicyNetworkAccessPolicy] = None """The access policy enforced for egress traffic to the internet.""" @@ -6212,7 +6227,7 @@ def from_dict(cls, d: Dict[str, Any]) -> TokenPermissionsDescription: class TokenType(Enum): - """The type of token request. As of now, only `AZURE_ACTIVE_DIRECTORY_TOKEN` is supported.""" + """The type of token request. As of now, only ``AZURE_ACTIVE_DIRECTORY_TOKEN`` is supported.""" ARCLIGHT_AZURE_EXCHANGE_TOKEN = "ARCLIGHT_AZURE_EXCHANGE_TOKEN" ARCLIGHT_AZURE_EXCHANGE_TOKEN_WITH_USER_DELEGATION_KEY = "ARCLIGHT_AZURE_EXCHANGE_TOKEN_WITH_USER_DELEGATION_KEY" @@ -6354,9 +6369,11 @@ class AccountIpAccessListsAPI: 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. + 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. @@ -6379,10 +6396,11 @@ def create( 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`. + - 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. @@ -6471,12 +6489,13 @@ def replace( """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. + 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 @@ -6526,10 +6545,11 @@ def update( 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`. + - 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. @@ -6695,14 +6715,14 @@ def update( :param setting: :class:`AibiDashboardEmbeddingAccessPolicySetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AibiDashboardEmbeddingAccessPolicySetting` """ @@ -6812,14 +6832,14 @@ def update( :param setting: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AibiDashboardEmbeddingApprovedDomainsSetting` """ @@ -6889,23 +6909,23 @@ def update( self, allow_missing: bool, setting: AutomaticClusterUpdateSetting, field_mask: str ) -> AutomaticClusterUpdateSetting: """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. + ``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 The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AutomaticClusterUpdateSetting` """ @@ -6974,23 +6994,23 @@ def update( self, allow_missing: bool, setting: ComplianceSecurityProfileSetting, field_mask: str ) -> ComplianceSecurityProfileSetting: """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. + 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 The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`ComplianceSecurityProfileSetting` """ @@ -7030,14 +7050,14 @@ def exchange_token( """Exchange tokens with an Identity Provider to get a new access token. It allows specifying scopes to determine token permissions. - POST /exchange-tokens/token is the documented public form, expressed via `google.api.http` below. GET - /exchange-tokens/$exchange is a legacy alias used by the Spark driver's OAuth refresh path - (DBHttpClient#get sends a body via HttpGetWithEntity) and stays on the legacy `option (rpc).endpoints` - annotation: its path contains a literal `$`, which `google.api.http`'s LITERAL grammar does not allow, - and `HttpPathParser` does not percent-decode template segments (so encoding as `%24exchange` would not - match the literal `$exchange` path the Spark driver sends). Per-endpoint `visibility: - PUBLIC_UNDOCUMENTED` preserves the DECO-7732 intent of suppressing the GET alias from the public API - spec. + POST /exchange-tokens/token is the documented public form, expressed via ``google.api.http`` below. + GET /exchange-tokens/$exchange is a legacy alias used by the Spark driver's OAuth refresh path + (DBHttpClient#get sends a body via HttpGetWithEntity) and stays on the legacy ``option + (rpc).endpoints`` annotation: its path contains a literal ``$``, which ``google.api.http``'s LITERAL + grammar does not allow, and ``HttpPathParser`` does not percent-decode template segments (so encoding + as ``%24exchange`` would not match the literal ``$exchange`` path the Spark driver sends). + Per-endpoint ``visibility: PUBLIC_UNDOCUMENTED`` preserves the DECO-7732 intent of suppressing the GET + alias from the public API spec. :param partition_id: :class:`PartitionId` The partition of Credentials store @@ -7118,14 +7138,14 @@ def update( :param setting: :class:`CspEnablementAccountSetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`CspEnablementAccountSetting` """ @@ -7154,7 +7174,7 @@ def update( class DashboardEmailSubscriptionsAPI: """Controls whether schedules or workload tasks for refreshing AI/BI Dashboards in the workspace can send subscription emails containing PDFs and/or images of the dashboard. By default, this setting is enabled - (set to `true`)""" + (set to ``true``)""" def __init__(self, api_client): self._api = api_client @@ -7230,14 +7250,14 @@ def update( :param setting: :class:`DashboardEmailSubscriptions` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DashboardEmailSubscriptions` """ @@ -7280,10 +7300,10 @@ def __init__(self, api_client): self._api = api_client def delete(self, *, etag: Optional[str] = None) -> 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. + """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 @@ -7341,26 +7361,26 @@ def get(self, *, etag: Optional[str] = None) -> DefaultNamespaceSetting: return DefaultNamespaceSetting.from_dict(res) def update(self, allow_missing: bool, setting: DefaultNamespaceSetting, field_mask: str) -> DefaultNamespaceSetting: - """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. + """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` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DefaultNamespaceSetting` """ @@ -7460,14 +7480,14 @@ def update(self, allow_missing: bool, setting: DefaultWarehouseId, field_mask: s :param setting: :class:`DefaultWarehouseId` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DefaultWarehouseId` """ @@ -7498,8 +7518,9 @@ class DisableLegacyAccessAPI: """'Disabling legacy access' has the following impacts: 1. Disables direct access to Hive Metastores from the workspace. However, you can still access a Hive - Metastore through Hive Metastore federation. 2. Disables fallback mode on external location access from - the workspace. 3. Disables Databricks Runtime versions prior to 13.3LTS.""" + Metastore through Hive Metastore federation. + 2. Disables fallback mode on external location access from the workspace. + 3. Disables Databricks Runtime versions prior to 13.3LTS.""" def __init__(self, api_client): self._api = api_client @@ -7570,14 +7591,14 @@ def update(self, allow_missing: bool, setting: DisableLegacyAccess, field_mask: :param setting: :class:`DisableLegacyAccess` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DisableLegacyAccess` """ @@ -7607,8 +7628,8 @@ def update(self, allow_missing: bool, setting: DisableLegacyAccess, field_mask: class DisableLegacyDbfsAPI: """Disabling legacy DBFS has the following implications: - 1. Access to DBFS root and DBFS mounts is disallowed (as well as the creation of new mounts). 2. Disables - Databricks Runtime versions prior to 13.3LTS. + 1. Access to DBFS root and DBFS mounts is disallowed (as well as the creation of new mounts). + 2. Disables Databricks Runtime versions prior to 13.3LTS. When the setting is off, all DBFS functionality is enabled and no restrictions are imposed on Databricks Runtime versions. This setting can take up to 20 minutes to take effect and requires a manual restart of @@ -7683,14 +7704,14 @@ def update(self, allow_missing: bool, setting: DisableLegacyDbfs, field_mask: st :param setting: :class:`DisableLegacyDbfs` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DisableLegacyDbfs` """ @@ -7720,9 +7741,12 @@ def update(self, allow_missing: bool, setting: DisableLegacyDbfs, field_mask: st 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.""" def __init__(self, api_client): self._api = api_client @@ -7791,14 +7815,14 @@ def update(self, allow_missing: bool, setting: DisableLegacyFeatures, field_mask :param setting: :class:`DisableLegacyFeatures` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`DisableLegacyFeatures` """ @@ -7860,14 +7884,14 @@ def patch_enable_export_notebook( :param setting: :class:`EnableExportNotebook` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EnableExportNotebook` """ @@ -7965,14 +7989,14 @@ def update(self, allow_missing: bool, setting: AccountIpAccessEnable, field_mask :param setting: :class:`AccountIpAccessEnable` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AccountIpAccessEnable` """ @@ -8036,14 +8060,14 @@ def patch_enable_notebook_table_clipboard( :param setting: :class:`EnableNotebookTableClipboard` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EnableNotebookTableClipboard` """ @@ -8105,14 +8129,14 @@ def patch_enable_results_downloading( :param setting: :class:`EnableResultsDownloading` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EnableResultsDownloading` """ @@ -8183,23 +8207,23 @@ def update( self, allow_missing: bool, setting: EnhancedSecurityMonitoringSetting, field_mask: str ) -> EnhancedSecurityMonitoringSetting: """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. + 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 The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EnhancedSecurityMonitoringSetting` """ @@ -8272,14 +8296,14 @@ def update( :param setting: :class:`EsmEnablementAccountSetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`EsmEnablementAccountSetting` """ @@ -8312,9 +8336,11 @@ class IpAccessListsAPI: 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. + 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. @@ -8337,10 +8363,11 @@ def create( 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`. + - 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 @@ -8440,13 +8467,15 @@ def replace( """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. + 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 @@ -8495,10 +8524,11 @@ def update( 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`. + - 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. @@ -8579,14 +8609,14 @@ def update( :param setting: :class:`LlmProxyPartnerPoweredAccount` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`LlmProxyPartnerPoweredAccount` """ @@ -8657,14 +8687,14 @@ def update( :param setting: :class:`LlmProxyPartnerPoweredEnforce` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`LlmProxyPartnerPoweredEnforce` """ @@ -8764,14 +8794,14 @@ def update( :param setting: :class:`LlmProxyPartnerPoweredWorkspace` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`LlmProxyPartnerPoweredWorkspace` """ @@ -8803,9 +8833,8 @@ class NetworkConnectivityAPI: resources. This API provides stable subnets for your workspace so that you can configure your firewalls on your Azure Storage accounts to allow access from Databricks. You can also use the API to provision private endpoints for Databricks to privately connect serverless compute resources to your Azure resources using - Azure Private Link. See [configure serverless secure connectivity]. - - [configure serverless secure connectivity]: https://learn.microsoft.com/azure/databricks/security/network/serverless-network-security""" + Azure Private Link. See `configure serverless secure connectivity + `__.""" def __init__(self, api_client): self._api = api_client @@ -8821,9 +8850,8 @@ def create_network_connectivity_configuration( **IMPORTANT**: After you create the network connectivity configuration, you must assign one or more workspaces to the new network connectivity configuration. You can share one network connectivity configuration with multiple workspaces from the same Azure region within the same Databricks account. - See [configure serverless secure connectivity]. - - [configure serverless secure connectivity]: https://learn.microsoft.com/azure/databricks/security/network/serverless-network-security + See `configure serverless secure connectivity + `__. :param network_connectivity_config: :class:`CreateNetworkConnectivityConfiguration` @@ -8850,10 +8878,9 @@ def create_private_endpoint_rule( 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 + 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 + `__. :param network_connectivity_config_id: str Your Network Connectivity Configuration ID. @@ -8901,8 +8928,8 @@ def delete_private_endpoint_rule( ) -> NccPrivateEndpointRule: """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 one day 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. + after one day 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. @@ -9053,8 +9080,8 @@ def update_private_endpoint_rule( :param private_endpoint_rule: :class:`UpdatePrivateEndpointRule` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. @@ -9421,14 +9448,14 @@ def update(self, allow_missing: bool, setting: PersonalComputeSetting, field_mas :param setting: :class:`PersonalComputeSetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`PersonalComputeSetting` """ @@ -9470,9 +9497,9 @@ def __init__(self, api_client): def delete(self, *, etag: Optional[str] = None) -> 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. + 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 @@ -9533,8 +9560,8 @@ def update( self, allow_missing: bool, setting: RestrictWorkspaceAdminsSetting, field_mask: str ) -> RestrictWorkspaceAdminsSetting: """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 + ``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 @@ -9542,14 +9569,14 @@ def update( :param setting: :class:`RestrictWorkspaceAdminsSetting` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`RestrictWorkspaceAdminsSetting` """ @@ -9682,7 +9709,7 @@ def sql_results_download(self) -> SqlResultsDownloadAPI: class SqlResultsDownloadAPI: """Controls whether users within the workspace are allowed to download results from the SQL Editor and AI/BI - Dashboards UIs. By default, this setting is enabled (set to `true`)""" + Dashboards UIs. By default, this setting is enabled (set to ``true``)""" def __init__(self, api_client): self._api = api_client @@ -9753,14 +9780,14 @@ def update(self, allow_missing: bool, setting: SqlResultsDownload, field_mask: s :param setting: :class:`SqlResultsDownload` :param field_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`SqlResultsDownload` """ @@ -10005,14 +10032,14 @@ def update_token_management(self, token_id: str, token: TokenInfo, update_mask: A list of field name under token, For example, {"update_mask": "comment,scopes"} The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`TokenInfo` """ @@ -10146,14 +10173,14 @@ def update(self, token_id: str, token: PublicTokenInfo, update_mask: FieldMask) A list of field name under token, For example, {"update_mask": "comment,scopes"} The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`UpdateTokenResponse` """ diff --git a/databricks/sdk/service/settingsv2.py b/databricks/sdk/service/settingsv2.py index b87b2815a..f5a2ed35e 100755 --- a/databricks/sdk/service/settingsv2.py +++ b/databricks/sdk/service/settingsv2.py @@ -411,7 +411,7 @@ def from_dict(cls, d: Dict[str, Any]) -> IntegerMessage: @dataclass class ListAccountSettingsMetadataResponse: next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" settings_metadata: Optional[List[SettingsMetadata]] = None @@ -447,7 +447,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListAccountSettingsMetadataResponse: @dataclass class ListAccountUserPreferencesMetadataResponse: next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" settings_metadata: Optional[List[SettingsMetadata]] = None @@ -483,7 +483,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListAccountUserPreferencesMetadataRespo @dataclass class ListWorkspaceSettingsMetadataResponse: next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" settings_metadata: Optional[List[SettingsMetadata]] = None @@ -1109,10 +1109,10 @@ def list_account_settings_metadata( unspecified, at most 200 settings will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. :param page_token: str (optional) - A page token, received from a previous `ListAccountSettingsMetadataRequest` call. Provide this to + A page token, received from a previous ``ListAccountSettingsMetadataRequest`` call. Provide this to retrieve the subsequent page. - When paginating, all other parameters provided to `ListAccountSettingsMetadataRequest` must match + When paginating, all other parameters provided to ``ListAccountSettingsMetadataRequest`` must match the call that provided the page token. :returns: Iterator over :class:`SettingsMetadata` @@ -1153,10 +1153,10 @@ def list_account_user_preferences_metadata( unspecified, at most 200 settings will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. :param page_token: str (optional) - A page token, received from a previous `ListAccountUserPreferencesMetadataRequest` call. Provide + A page token, received from a previous ``ListAccountUserPreferencesMetadataRequest`` call. Provide this to retrieve the subsequent page. - When paginating, all other parameters provided to `ListAccountUserPreferencesMetadataRequest` must + When paginating, all other parameters provided to ``ListAccountUserPreferencesMetadataRequest`` must match the call that provided the page token. :returns: Iterator over :class:`SettingsMetadata` @@ -1282,11 +1282,11 @@ def list_workspace_settings_metadata( unspecified, at most 200 settings will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. :param page_token: str (optional) - A page token, received from a previous `ListWorkspaceSettingsMetadataRequest` call. Provide this to - retrieve the subsequent page. + A page token, received from a previous ``ListWorkspaceSettingsMetadataRequest`` call. Provide this + to retrieve the subsequent page. - When paginating, all other parameters provided to `ListWorkspaceSettingsMetadataRequest` must match - the call that provided the page token. + When paginating, all other parameters provided to ``ListWorkspaceSettingsMetadataRequest`` must + match the call that provided the page token. :returns: Iterator over :class:`SettingsMetadata` """ diff --git a/databricks/sdk/service/sharing.py b/databricks/sdk/service/sharing.py index 72a0d85e9..ff375c4b6 100755 --- a/databricks/sdk/service/sharing.py +++ b/databricks/sdk/service/sharing.py @@ -578,7 +578,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GetActivationUrlInfoResponse: class GetRecipientSharePermissionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" permissions_out: Optional[List[ShareToPrivilegeAssignment]] = None """An array of data share permissions for a recipient.""" @@ -614,7 +614,7 @@ def from_dict(cls, d: Dict[str, Any]) -> GetRecipientSharePermissionsResponse: class GetSharePermissionsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" privilege_assignments: Optional[List[PrivilegeAssignment]] = None """The privileges assigned to each principal""" @@ -768,7 +768,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListProviderShareAssetsResponse: class ListProviderSharesResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" shares: Optional[List[ProviderShare]] = None """An array of provider shares.""" @@ -801,7 +801,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListProviderSharesResponse: class ListProvidersResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" providers: Optional[List[ProviderInfo]] = None """An array of provider information objects.""" @@ -836,7 +836,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListProvidersResponse: class ListRecipientsResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" recipients: Optional[List[RecipientInfo]] = None """An array of recipient information objects.""" @@ -871,7 +871,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListRecipientsResponse: class ListSharesResponse: next_page_token: Optional[str] = None """Opaque token to retrieve the next page of results. Absent if there are no more pages. - __page_token__ should be set to this value for the next request (for the next page of results).""" + **page_token** should be set to this value for the next request (for the next page of results).""" shares: Optional[List[ShareInfo]] = None """An array of data share information objects.""" @@ -978,20 +978,34 @@ class OidcFederationPolicy: subject_claim: str """The claim that contains the subject of the token. Depending on the identity provider and the use - case (U2M or M2M), this can vary: - For Entra ID (AAD): * U2M flow (group access): Use `groups`. - * U2M flow (user access): Use `oid`. * M2M flow (OAuth App access): Use `azp`. - For other IdPs, - refer to the specific IdP documentation. + case (U2M or M2M), this can vary: - Supported `subject_claim` values are: - `oid`: Object ID of the user. - `azp`: Client ID of the - OAuth app. - `groups`: Object ID of the group. - `sub`: Subject identifier for other use cases.""" + - For Entra ID (AAD): + + - U2M flow (group access): Use ``groups``. + - U2M flow (user access): Use ``oid``. + - M2M flow (OAuth App access): Use ``azp``. + + - For other IdPs, refer to the specific IdP documentation. + + Supported ``subject_claim`` values are: + + - ``oid``: Object ID of the user. + - ``azp``: Client ID of the OAuth app. + - ``groups``: Object ID of the group. + - ``sub``: Subject identifier for other use cases.""" subject: str """The required token subject, as specified in the subject claim of federated tokens. The subject claim identifies the identity of the user or machine accessing the resource. Examples for Entra - ID (AAD): - U2M flow (group access): If the subject claim is `groups`, this must be the Object - ID of the group in Entra ID. - U2M flow (user access): If the subject claim is `oid`, this must - be the Object ID of the user in Entra ID. - M2M flow (OAuth App access): If the subject claim is - `azp`, this must be the client ID of the OAuth app registered in Entra ID.""" + ID (AAD): + + - U2M flow (group access): If the subject claim is ``groups``, this must be the Object ID of the + group in Entra ID. + - U2M flow (user access): If the subject claim is ``oid``, this must be the Object ID of the + user in Entra ID. + - M2M flow (OAuth App access): If the subject claim is ``azp``, this must be the client ID of + the OAuth app registered in Entra ID.""" audiences: Optional[List[str]] = None """The allowed token audiences, as specified in the 'aud' claim of federated tokens. The audience @@ -1070,11 +1084,11 @@ class PartitionValue: recipient_property_key: Optional[str] = None """The key of a Delta Sharing recipient's property. For example "databricks-account-id". When this - field is set, field `value` can not be set.""" + field is set, field ``value`` can not be set.""" value: Optional[str] = None - """The value of the partition column. When this value is not set, it means `null` value. When this - field is set, field `recipient_property_key` can not be set.""" + """The value of the partition column. When this value is not set, it means ``null`` value. When + this field is set, field ``recipient_property_key`` can not be set.""" def as_dict(self) -> dict: """Serializes the PartitionValue into a dictionary suitable for use as a JSON request body.""" @@ -1209,8 +1223,8 @@ class Privilege(Enum): @dataclass class PrivilegeAssignment: principal: Optional[str] = None - """The principal (user email address or group name). For deleted principals, `principal` is empty - while `principal_id` is populated.""" + """The principal (user email address or group name). For deleted principals, ``principal`` is empty + while ``principal_id`` is populated.""" privileges: Optional[List[Privilege]] = None """The privileges assigned to the principal.""" @@ -1245,7 +1259,7 @@ class ProviderInfo: cloud: Optional[str] = None """Cloud vendor of the provider's UC metastore. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" comment: Optional[str] = None """Description about the provider.""" @@ -1258,11 +1272,11 @@ class ProviderInfo: data_provider_global_metastore_id: Optional[str] = None """The global UC metastore id of the data provider. This field is only present when the - __authentication_type__ is **DATABRICKS**. The identifier is of format - __cloud__:__region__:__metastore-uuid__.""" + **authentication_type** is **DATABRICKS**. The identifier is of format + **cloud**:**region**:**metastore-uuid**.""" metastore_id: Optional[str] = None - """UUID of the provider's UC metastore. This field is only present when the __authentication_type__ + """UUID of the provider's UC metastore. This field is only present when the **authentication_type** is **DATABRICKS**.""" name: Optional[str] = None @@ -1272,16 +1286,16 @@ class ProviderInfo: """Username of Provider owner.""" recipient_profile: Optional[RecipientProfile] = None - """The recipient profile. This field is only present when the authentication_type is `TOKEN` or - `OAUTH_CLIENT_CREDENTIALS`.""" + """The recipient profile. This field is only present when the authentication_type is ``TOKEN`` or + ``OAUTH_CLIENT_CREDENTIALS``.""" recipient_profile_str: Optional[str] = None - """This field is required when the __authentication_type__ is **TOKEN**, + """This field is required when the **authentication_type** is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** or not provided.""" region: Optional[str] = None """Cloud region of the provider's UC metastore. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" updated_at: Optional[int] = None """Time at which this Provider was created, in epoch milliseconds.""" @@ -1414,7 +1428,7 @@ class RecipientInfo: cloud: Optional[str] = None """Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" comment: Optional[str] = None """Description about the recipient.""" @@ -1427,8 +1441,8 @@ class RecipientInfo: data_recipient_global_metastore_id: Optional[str] = None """The global Unity Catalog metastore id provided by the data recipient. This field is only present - when the __authentication_type__ is **DATABRICKS**. The identifier is of format - __cloud__:__region__:__metastore-uuid__.""" + when the **authentication_type** is **DATABRICKS**. The identifier is of format + **cloud**:**region**:**metastore-uuid**.""" expiration_time: Optional[int] = None """Expiration timestamp of the token, in epoch milliseconds.""" @@ -1441,7 +1455,7 @@ class RecipientInfo: metastore_id: Optional[str] = None """Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" name: Optional[str] = None """Name of Recipient.""" @@ -1456,14 +1470,14 @@ class RecipientInfo: region: Optional[str] = None """Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" sharing_code: Optional[str] = None """The one-time sharing code provided by the data recipient. This field is only present when the - __authentication_type__ is **DATABRICKS**.""" + **authentication_type** is **DATABRICKS**.""" tokens: Optional[List[RecipientTokenInfo]] = None - """This field is only present when the __authentication_type__ is **TOKEN**.""" + """This field is only present when the **authentication_type** is **TOKEN**.""" updated_at: Optional[int] = None """Time at which the recipient was updated, in epoch milliseconds.""" @@ -1792,7 +1806,7 @@ def from_dict(cls, d: Dict[str, Any]) -> RetrieveTokenResponse: @dataclass class SecurablePropertiesKvPairs: - """An object with __properties__ containing map of key-value properties attached to the securable.""" + """An object with **properties** containing map of key-value properties attached to the securable.""" properties: Dict[str, str] """A map of key-value properties attached to the securable.""" @@ -1985,7 +1999,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ShareToPrivilegeAssignment: class SharedDataObject: name: str """A fully qualified name that uniquely identifies a data object. For example, a table's fully - qualified name is in the format of `..`,""" + qualified name is in the format of ``..
``,""" added_at: Optional[int] = None """The time when this data object is added to the share, in epoch milliseconds.""" @@ -2019,22 +2033,29 @@ class SharedDataObject: Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, - NOTEBOOK_FILE, FUNCTION), use `string_shared_as` instead. + NOTEBOOK_FILE, FUNCTION), use ``string_shared_as`` instead. Important: For non-table objects, this field must be omitted entirely. - Format: Must be a 2-part name `.` (e.g., "sales_schema.orders_table") - - Both schema and table names must contain only alphanumeric characters and underscores - No - periods, spaces, forward slashes, or control characters are allowed within each part - Do not - include the catalog name (use 2 parts, not 3) + Format: Must be a 2-part name ``.`` (e.g., "sales_schema.orders_table") - Behavior: - If not provided, the service automatically generates the alias as `.
` - from the object's original name - If you don't want to specify this field, omit it entirely from - the request (do not pass an empty string) - The `shared_as` name must be unique within the share + - Both schema and table names must contain only alphanumeric characters and underscores + - No periods, spaces, forward slashes, or control characters are allowed within each part + - Do not include the catalog name (use 2 parts, not 3) - Examples: - Valid: "analytics_schema.customer_view" - Invalid: - "catalog.analytics_schema.customer_view" (3 parts not allowed) - Invalid: - "analytics-schema.customer-view" (hyphens not allowed)""" + Behavior: + + - If not provided, the service automatically generates the alias as ``.
`` from + the object's original name + - If you don't want to specify this field, omit it entirely from the request (do not pass an + empty string) + - The ``shared_as`` name must be unique within the share + + Examples: + + - Valid: "analytics_schema.customer_view" + - Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed) + - Invalid: "analytics-schema.customer-view" (hyphens not allowed)""" start_version: Optional[int] = None """The start version associated with the object. This allows data providers to control the lowest @@ -2042,7 +2063,7 @@ class SharedDataObject: changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share. - NOTE: The start_version should be <= the `current` version of the object.""" + NOTE: The start_version should be <= the ``current`` version of the object.""" status: Optional[SharedDataObjectStatus] = None """One of: **ACTIVE**, **PERMISSION_DENIED**.""" @@ -2052,26 +2073,35 @@ class SharedDataObject: Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, - FOREIGN_TABLE), use `shared_as` instead. + FOREIGN_TABLE), use ``shared_as`` instead. Important: For table-like objects, this field must be omitted entirely. - Format: - For VOLUME: Must be a 2-part name `.` (e.g., - "data_schema.ml_models") - For FUNCTION: Must be a 2-part name `.` - (e.g., "udf_schema.calculate_tax") - For MODEL: Must be a 2-part name - `.` (e.g., "models.prediction_model") - For NOTEBOOK_FILE: Should be - the notebook file name (e.g., "analysis_notebook.py") - All names must contain only alphanumeric - characters and underscores - No periods, spaces, forward slashes, or control characters are - allowed within each part + Format: + + - For VOLUME: Must be a 2-part name ``.`` (e.g., + "data_schema.ml_models") + - For FUNCTION: Must be a 2-part name ``.`` (e.g., + "udf_schema.calculate_tax") + - For MODEL: Must be a 2-part name ``.`` (e.g., + "models.prediction_model") + - For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py") + - All names must contain only alphanumeric characters and underscores + - No periods, spaces, forward slashes, or control characters are allowed within each part - Behavior: - If not provided, the service automatically generates the alias from the object's - original name - If you don't want to specify this field, omit it entirely from the request (do - not pass an empty string) - The `string_shared_as` name must be unique for objects of the same - type within the share + Behavior: - Examples: - Valid for VOLUME: "data_schema.training_data" - Valid for FUNCTION: - "analytics.calculate_revenue" - Invalid: "catalog.data_schema.training_data" (3 parts not - allowed for volumes) - Invalid: "data-schema.training-data" (hyphens not allowed)""" + - If not provided, the service automatically generates the alias from the object's original name + - If you don't want to specify this field, omit it entirely from the request (do not pass an + empty string) + - The ``string_shared_as`` name must be unique for objects of the same type within the share + + Examples: + + - Valid for VOLUME: "data_schema.training_data" + - Valid for FUNCTION: "analytics.calculate_revenue" + - Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes) + - Invalid: "data-schema.training-data" (hyphens not allowed)""" def as_dict(self) -> dict: """Serializes the SharedDataObject into a dictionary suitable for use as a JSON request body.""" @@ -2447,7 +2477,7 @@ def create( :param comment: str (optional) Description about the provider. :param recipient_profile_str: str (optional) - This field is required when the __authentication_type__ is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** + This field is required when the **authentication_type** is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** or not provided. :returns: :class:`ProviderInfo` @@ -2529,13 +2559,16 @@ def list( 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. + 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. @@ -2624,18 +2657,22 @@ def list_shares( ) -> Iterator[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. + - 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. + 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. @@ -2688,7 +2725,7 @@ def update( :param owner: str (optional) Username of Provider owner. :param recipient_profile_str: str (optional) - This field is required when the __authentication_type__ is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** + This field is required when the **authentication_type** is **TOKEN**, **OAUTH_CLIENT_CREDENTIALS** or not provided. :returns: :class:`ProviderInfo` @@ -2718,7 +2755,7 @@ def update( 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 + 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. @@ -2774,20 +2811,23 @@ def retrieve_token(self, activation_url: str) -> RetrieveTokenResponse: class RecipientFederationPoliciesAPI: """The Recipient Federation Policies APIs are only applicable in the open sharing model where the recipient - object has the authentication type of `OIDC_RECIPIENT`, enabling data sharing from Databricks to + object has the authentication type of ``OIDC_RECIPIENT``, enabling data sharing from Databricks to non-Databricks recipients. OIDC Token Federation enables secure, secret-less authentication for accessing Delta Sharing servers. Users and applications authenticate using short-lived OIDC tokens issued by their own Identity Provider (IdP), such as Azure Entra ID or Okta, without the need for managing static credentials or client secrets. A federation policy defines how non-Databricks recipients authenticate using OIDC tokens. It validates the OIDC claims in federated tokens and is set at the recipient level. The caller must be the owner of the recipient to create or manage a federation policy. Federation policies - support the following scenarios: - User-to-Machine (U2M) flow: A user accesses Delta Shares using their - own identity, such as connecting through PowerBI Delta Sharing Client. - Machine-to-Machine (M2M) flow: An - application accesses Delta Shares using its own identity, typically for automation tasks like nightly jobs - through Python Delta Sharing Client. OIDC Token Federation enables fine-grained access control, supports - Multi-Factor Authentication (MFA), and enhances security by minimizing the risk of credential leakage - through the use of short-lived, expiring tokens. It is designed for strong identity governance, secure - cross-platform data sharing, and reduced operational overhead for credential management. + support the following scenarios: + + - User-to-Machine (U2M) flow: A user accesses Delta Shares using their own identity, such as connecting + through PowerBI Delta Sharing Client. + - Machine-to-Machine (M2M) flow: An application accesses Delta Shares using its own identity, typically + for automation tasks like nightly jobs through Python Delta Sharing Client. OIDC Token Federation + enables fine-grained access control, supports Multi-Factor Authentication (MFA), and enhances security + by minimizing the risk of credential leakage through the use of short-lived, expiring tokens. It is + designed for strong identity governance, secure cross-platform data sharing, and reduced operational + overhead for credential management. For more information, see https://www.databricks.com/blog/announcing-oidc-token-federation-enhanced-delta-sharing-security and @@ -2804,20 +2844,26 @@ def create(self, recipient_name: str, policy: FederationPolicy) -> FederationPol defined at the recipient level. This enables secretless sharing clients to authenticate using OIDC tokens. - Supported scenarios for federation policies: 1. **User-to-Machine (U2M) flow** (e.g., PowerBI): A user - accesses a resource using their own identity. 2. **Machine-to-Machine (M2M) flow** (e.g., OAuth App): - An OAuth App accesses a resource using its own identity, typically for tasks like running nightly - jobs. + Supported scenarios for federation policies: + + 1. **User-to-Machine (U2M) flow** (e.g., PowerBI): A user accesses a resource using their own + identity. + 2. **Machine-to-Machine (M2M) flow** (e.g., OAuth App): An OAuth App accesses a resource using its own + identity, typically for tasks like running nightly jobs. - For an overview, refer to: - Blog post: Overview of feature: - https://www.databricks.com/blog/announcing-oidc-token-federation-enhanced-delta-sharing-security + For an overview, refer to: - For detailed configuration guides based on your use case: - Creating a Federation Policy as a - provider: https://docs.databricks.com/en/delta-sharing/create-recipient-oidc-fed - Configuration and - usage for Machine-to-Machine (M2M) applications (e.g., Python Delta Sharing Client): - https://docs.databricks.com/aws/en/delta-sharing/sharing-over-oidc-m2m - Configuration and usage for - User-to-Machine (U2M) applications (e.g., PowerBI): - https://docs.databricks.com/aws/en/delta-sharing/sharing-over-oidc-u2m + - Blog post: Overview of feature: + https://www.databricks.com/blog/announcing-oidc-token-federation-enhanced-delta-sharing-security + + For detailed configuration guides based on your use case: + + - Creating a Federation Policy as a provider: + https://docs.databricks.com/en/delta-sharing/create-recipient-oidc-fed + - Configuration and usage for Machine-to-Machine (M2M) applications (e.g., Python Delta Sharing + Client): https://docs.databricks.com/aws/en/delta-sharing/sharing-over-oidc-m2m + - Configuration and usage for User-to-Machine (U2M) applications (e.g., PowerBI): + https://docs.databricks.com/aws/en/delta-sharing/sharing-over-oidc-u2m :param recipient_name: str Name of the recipient. This is the name of the recipient for which the policy is being created. @@ -2940,14 +2986,14 @@ class RecipientsAPI: 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**. - + 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**.""" + 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**.""" def __init__(self, api_client): self._api = api_client @@ -2976,8 +3022,8 @@ def create( 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 only present - when the __authentication_type__ is **DATABRICKS**. The identifier is of format - __cloud__:__region__:__metastore-uuid__. + 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 id: str (optional) @@ -2992,7 +3038,7 @@ def create( need to perform a read-modify-write. :param sharing_code: str (optional) The one-time sharing code provided by the data recipient. This field is only present when the - __authentication_type__ is **DATABRICKS**. + **authentication_type** is **DATABRICKS**. :returns: :class:`RecipientInfo` """ @@ -3048,8 +3094,11 @@ def delete(self, name: str): self._api.do("DELETE", f"/api/2.1/unity-catalog/recipients/{name}", headers=headers) def get(self, name: str) -> RecipientInfo: - """Gets a share recipient from the metastore. The caller must be one of: * A user with **USE_RECIPIENT** - privilege on the metastore * The owner of the share recipient * A metastore admin + """Gets a share recipient from the metastore. The caller must be one of: + + - A user with **USE_RECIPIENT** privilege on the metastore + - The owner of the share recipient + - A metastore admin :param name: str Name of the recipient. @@ -3077,20 +3126,23 @@ def list( ) -> Iterator[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. + - 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. + 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. @@ -3161,13 +3213,16 @@ def share_permissions( :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. + 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. @@ -3351,13 +3406,16 @@ def list_shares( 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. + 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. @@ -3397,13 +3455,16 @@ def share_permissions( :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. + 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. @@ -3439,12 +3500,12 @@ def update( """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. + When the caller is a metastore admin, only the **owner** field can be updated. In the case the share name is changed, **updateShare** requires that the caller is the owner of the share and has the CREATE_SHARE privilege. - If there are notebook files in the share, the __storage_root__ field cannot be updated. + 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 diff --git a/databricks/sdk/service/sql.py b/databricks/sdk/service/sql.py index 5f193aa45..25033d98a 100755 --- a/databricks/sdk/service/sql.py +++ b/databricks/sdk/service/sql.py @@ -35,8 +35,10 @@ class AccessControl: group_name: Optional[str] = None permission_level: Optional[PermissionLevel] = None - """* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query - * `CAN_MANAGE`: Can manage the query""" + """- ``CAN_VIEW``: Can view the query + - ``CAN_RUN``: Can run the query + - ``CAN_EDIT``: Can edit the query + - ``CAN_MANAGE``: Can manage the query""" user_name: Optional[str] = None @@ -92,15 +94,13 @@ class Alert: """The timestamp indicating when the alert was created.""" custom_body: Optional[str] = None - """Custom body of alert notification, if it exists. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + """Custom body of alert notification, if it exists. See `here + `__ for custom templating instructions.""" custom_subject: Optional[str] = None """Custom subject of alert notification, if it exists. This can include email subject entries and - Slack notification headers, for example. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + Slack notification headers, for example. See `here + `__ for custom templating instructions.""" display_name: Optional[str] = None """The display name of the alert.""" @@ -426,22 +426,20 @@ class AlertOptions: """Name of column in the query result to compare in alert evaluation.""" op: str - """Operator used to compare in alert evaluation: `>`, `>=`, `<`, `<=`, `==`, `!=`""" + """Operator used to compare in alert evaluation: ``>``, ``>=``, ``<``, ``<=``, ``==``, ``!=``""" value: Any """Value used to compare in alert evaluation. Supported types include strings (eg. 'foobar'), floats (eg. 123.4), and booleans (true).""" custom_body: Optional[str] = None - """Custom body of alert notification, if it exists. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + """Custom body of alert notification, if it exists. See `here + `__ for custom templating instructions.""" custom_subject: Optional[str] = None """Custom subject of alert notification, if it exists. This includes email subject, Slack - notification header, etc. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + notification header, etc. See `here `__ + for custom templating instructions.""" empty_result_state: Optional[AlertOptionsEmptyResultState] = None """State that alert evaluates to when query result is empty.""" @@ -517,9 +515,7 @@ class AlertQuery: data_source_id: Optional[str] = None """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""" + warehouse ID. `Learn more `__""" description: Optional[str] = None """General description that conveys additional information about this query such as usage notes.""" @@ -529,8 +525,8 @@ class AlertQuery: is_archived: Optional[bool] = None """Indicates whether the query is trashed. Trashed queries can't be used in dashboards, or appear - in search results. If this boolean is `true`, the `options` property for this query includes a - `moved_to_trash_at` timestamp. Trashed queries are permanently deleted after 30 days.""" + in search results. If this boolean is ``true``, the ``options`` property for this query includes + a ``moved_to_trash_at`` timestamp. Trashed queries are permanently deleted after 30 days.""" is_draft: Optional[bool] = None """Whether the query is a draft. Draft queries only appear in list views for their owners. @@ -538,7 +534,7 @@ class AlertQuery: is_safe: Optional[bool] = None """Text parameter types are not safe from SQL injection for all types of data source. Set this - Boolean parameter to `true` if a query either does not use any text type parameters or uses a + Boolean parameter to ``true`` if a query either does not use any text type parameters or uses a data source type where text type parameters are handled safely.""" name: Optional[str] = None @@ -688,15 +684,17 @@ class AlertV2: run_as: Optional[AlertV2RunAs] = None """Specifies the identity that will be used to run the alert. This field allows you to configure - alerts to run as a specific user or service principal. - For user identity: Set `user_name` to - the email of an active workspace user. Users can only set this to their own email. - For service - principal: Set `service_principal_name` to the application ID. Requires the - `servicePrincipal/user` role. If not specified, the alert will run as the request user.""" + alerts to run as a specific user or service principal. + + - For user identity: Set ``user_name`` to the email of an active workspace user. Users can only + set this to their own email. + - For service principal: Set ``service_principal_name`` to the application ID. Requires the + ``servicePrincipal/user`` role. If not specified, the alert will run as the request user.""" run_as_user_name: Optional[str] = None """The run as username or application ID of service principal. On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the - servicePrincipal/user role. Deprecated: Use `run_as` field instead. This field will be removed + servicePrincipal/user role. Deprecated: Use ``run_as`` field instead. This field will be removed in a future release.""" update_time: Optional[str] = None @@ -808,8 +806,8 @@ class AlertV2Evaluation: """Operator used for comparison in alert evaluation.""" empty_result_state: Optional[AlertEvaluationState] = None - """Alert state if result is empty. Please avoid setting this field to be `UNKNOWN` because - `UNKNOWN` state is planned to be deprecated.""" + """Alert state if result is empty. Please avoid setting this field to be ``UNKNOWN`` because + ``UNKNOWN`` state is planned to be deprecated.""" last_evaluated_at: Optional[str] = None """Timestamp of the last evaluation.""" @@ -958,7 +956,7 @@ class AlertV2OperandColumn: name: str aggregation: Optional[Aggregation] = None - """If not set, the behavior is equivalent to using `First row` in the UI.""" + """If not set, the behavior is equivalent to using ``First row`` in the UI.""" display: Optional[str] = None @@ -1036,7 +1034,7 @@ def from_dict(cls, d: Dict[str, Any]) -> AlertV2OperandValue: class AlertV2RunAs: service_principal_name: Optional[str] = None """Application ID of an active service principal. Setting this field requires the - `servicePrincipal/user` role.""" + ``servicePrincipal/user`` role.""" user_name: Optional[str] = None """The email of an active workspace user. Can only set this field to their own email.""" @@ -1098,7 +1096,7 @@ def from_dict(cls, d: Dict[str, Any]) -> AlertV2Subscription: @dataclass class BaseChunkInfo: byte_count: Optional[int] = None - """The number of bytes in the result chunk. This field is not available when using `INLINE` + """The number of bytes in the result chunk. This field is not available when using ``INLINE`` disposition.""" chunk_index: Optional[int] = None @@ -1150,7 +1148,7 @@ def from_dict(cls, d: Dict[str, Any]) -> BaseChunkInfo: @dataclass class Channel: """Configures the channel name and DBSQL version of the warehouse. CHANNEL_NAME_CUSTOM should be - chosen only when `dbsql_version` is specified.""" + chosen only when ``dbsql_version`` is specified.""" dbsql_version: Optional[str] = None @@ -1430,15 +1428,13 @@ class CreateAlertRequestAlert: """Trigger conditions of the alert.""" custom_body: Optional[str] = None - """Custom body of alert notification, if it exists. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + """Custom body of alert notification, if it exists. See `here + `__ for custom templating instructions.""" custom_subject: Optional[str] = None """Custom subject of alert notification, if it exists. This can include email subject entries and - Slack notification headers, for example. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + Slack notification headers, for example. See `here + `__ for custom templating instructions.""" display_name: Optional[str] = None """The display name of the alert.""" @@ -1771,15 +1767,15 @@ class Dashboard: dashboard_filters_enabled: Optional[bool] = None """In the web application, query filters that share a name are coupled to a single selection box if - this value is `true`.""" + this value is ``true``.""" id: Optional[str] = None """The ID for this dashboard.""" is_archived: Optional[bool] = None """Indicates whether a dashboard is trashed. Trashed dashboards won't appear in list views. If this - boolean is `true`, the `options` property for this dashboard includes a `moved_to_trash_at` - timestamp. Items in trash are permanently deleted after 30 days.""" + boolean is ``true``, the ``options`` property for this dashboard includes a + ``moved_to_trash_at`` timestamp. Items in trash are permanently deleted after 30 days.""" is_draft: Optional[bool] = None """Whether a dashboard is a draft. Draft dashboards only appear in list views for their owners.""" @@ -1797,12 +1793,14 @@ class Dashboard: """The identifier of the workspace folder containing the object.""" permission_tier: Optional[PermissionLevel] = None - """* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query - * `CAN_MANAGE`: Can manage the query""" + """- ``CAN_VIEW``: Can view the query + - ``CAN_RUN``: Can run the query + - ``CAN_EDIT``: Can edit the query + - ``CAN_MANAGE``: Can manage the query""" slug: Optional[str] = None - """URL slug. Usually mirrors the query name with dashes (`-`) instead of spaces. Appears in the URL - for this query.""" + """URL slug. Usually mirrors the query name with dashes (``-``) instead of spaces. Appears in the + URL for this query.""" tags: Optional[List[str]] = None @@ -1921,8 +1919,8 @@ def from_dict(cls, d: Dict[str, Any]) -> Dashboard: @dataclass class DashboardOptions: moved_to_trash_at: Optional[str] = None - """The timestamp when this dashboard was moved to trash. Only present when the `is_archived` - property is `true`. Trashed items are deleted after thirty days.""" + """The timestamp when this dashboard was moved to trash. Only present when the ``is_archived`` + property is ``true``. Trashed items are deleted after thirty days.""" def as_dict(self) -> dict: """Serializes the DashboardOptions into a dictionary suitable for use as a JSON request body.""" @@ -1950,9 +1948,7 @@ class DataSource: id: Optional[str] = None """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""" + warehouse ID. `Learn more `__""" name: Optional[str] = None """The string name of this data source / SQL warehouse as it appears in the Databricks SQL web @@ -1971,7 +1967,7 @@ class DataSource: """Reserved for internal use.""" type: Optional[str] = None - """The type of data source. For SQL warehouses, this will be `databricks_internal`.""" + """The type of data source. For SQL warehouses, this will be ``databricks_internal``.""" view_only: Optional[bool] = None """Reserved for internal use.""" @@ -2442,7 +2438,10 @@ class EndpointInfo: """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. + Supported values: + + - Must be == 0 or >= 10 mins + - 0 indicates no autostop. Defaults to 120 mins""" @@ -2454,8 +2453,18 @@ class EndpointInfo: 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 - 5X-Large - Auto""" + Supported values: + + - 2X-Small + - X-Small + - Small + - Medium + - Large + - X-Large + - 2X-Large + - 3X-Large + - 4X-Large + - 5X-Large""" creator_name: Optional[str] = None """warehouse creator name""" @@ -2483,7 +2492,10 @@ class EndpointInfo: max_num_clusters: Optional[int] = None """Maximum number of clusters that the autoscaler will create to handle concurrent queries. - Supported values: - Must be >= min_num_clusters - Must be <= 40. + Supported values: + + - Must be >= min_num_clusters + - Must be <= 40. Defaults to min_clusters if unset.""" @@ -2493,14 +2505,20 @@ class EndpointInfo: 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) + Supported values: + + - Must be > 0 + - Must be <= min(max_num_clusters, 30) Defaults to 1""" name: Optional[str] = None """Logical name for the cluster. - Supported values: - Must be unique within an org. - Must be less than 100 characters.""" + Supported values: + + - Must be unique within an org. + - Must be less than 100 characters.""" num_active_sessions: Optional[int] = None """Deprecated. current number of active sessions for the warehouse""" @@ -2521,11 +2539,13 @@ class EndpointInfo: """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.""" + Supported values: + + - Number of tags < 45.""" warehouse_type: Optional[EndpointInfoWarehouseType] = None - """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`.""" + """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``.""" def as_dict(self) -> dict: """Serializes the EndpointInfo into a dictionary suitable for use as a JSON request body.""" @@ -2748,12 +2768,12 @@ def from_dict(cls, d: Dict[str, Any]) -> EnumValue: class ExecuteStatementRequestOnWaitTimeout(Enum): - """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 + """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.""" + :method:statementexecution/getStatement. When set to ``CANCEL``, the statement execution is + canceled and the call returns with a ``CANCELED`` state.""" CANCEL = "CANCEL" CONTINUE = "CONTINUE" @@ -2762,7 +2782,7 @@ class ExecuteStatementRequestOnWaitTimeout(Enum): @dataclass class ExternalLink: byte_count: Optional[int] = None - """The number of bytes in the result chunk. This field is not available when using `INLINE` + """The number of bytes in the result chunk. This field is not available when using ``INLINE`` disposition.""" chunk_index: Optional[int] = None @@ -2770,7 +2790,7 @@ class ExternalLink: expiration: Optional[str] = None """Indicates the date-time that the given external link will expire and becomes invalid, after - which point a new `external_link` must be requested.""" + which point a new ``external_link`` must be requested.""" external_link: Optional[str] = None """A URL pointing to a chunk of result data, hosted by an external service, with a short expiration @@ -2778,20 +2798,20 @@ class ExternalLink: sensitive and the client should not expose this URL in a log.""" http_headers: Optional[Dict[str, str]] = None - """HTTP headers that must be included with a GET request to the `external_link`. Each header is + """HTTP headers that must be included with a GET request to the ``external_link``. Each header is provided as a key-value pair. Headers are typically used to pass a decryption key to the external service. The values of these headers should be considered sensitive and the client should not expose these values in a log.""" next_chunk_index: Optional[int] = None - """When fetching, provides the `chunk_index` for the _next_ chunk. If absent, indicates there are + """When fetching, provides the ``chunk_index`` for the *next* chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a :method:statementexecution/getstatementresultchunkn request.""" next_chunk_internal_link: Optional[str] = None - """When fetching, provides a link to fetch the _next_ chunk. If absent, indicates there are no more - chunks. This link is an absolute `path` to be joined with your `$DATABRICKS_HOST`, and should be - treated as an opaque link. This is an alternative to using `next_chunk_index`.""" + """When fetching, provides a link to fetch the *next* chunk. If absent, indicates there are no more + chunks. This link is an absolute ``path`` to be joined with your ``$DATABRICKS_HOST``, and + should be treated as an opaque link. This is an alternative to using ``next_chunk_index``.""" row_count: Optional[int] = None """The number of rows within the result chunk.""" @@ -3057,7 +3077,10 @@ class GetWarehouseResponse: """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. + Supported values: + + - Must be == 0 or >= 10 mins + - 0 indicates no autostop. Defaults to 120 mins""" @@ -3069,8 +3092,18 @@ class GetWarehouseResponse: 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 - 5X-Large - Auto""" + Supported values: + + - 2X-Small + - X-Small + - Small + - Medium + - Large + - X-Large + - 2X-Large + - 3X-Large + - 4X-Large + - 5X-Large""" creator_name: Optional[str] = None """warehouse creator name""" @@ -3098,7 +3131,10 @@ class GetWarehouseResponse: max_num_clusters: Optional[int] = None """Maximum number of clusters that the autoscaler will create to handle concurrent queries. - Supported values: - Must be >= min_num_clusters - Must be <= 40. + Supported values: + + - Must be >= min_num_clusters + - Must be <= 40. Defaults to min_clusters if unset.""" @@ -3108,14 +3144,20 @@ class GetWarehouseResponse: 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) + Supported values: + + - Must be > 0 + - Must be <= min(max_num_clusters, 30) Defaults to 1""" name: Optional[str] = None """Logical name for the cluster. - Supported values: - Must be unique within an org. - Must be less than 100 characters.""" + Supported values: + + - Must be unique within an org. + - Must be less than 100 characters.""" num_active_sessions: Optional[int] = None """Deprecated. current number of active sessions for the warehouse""" @@ -3136,11 +3178,13 @@ class GetWarehouseResponse: """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.""" + Supported values: + + - Number of tags < 45.""" warehouse_type: Optional[GetWarehouseResponseWarehouseType] = None - """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`.""" + """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``.""" def as_dict(self) -> dict: """Serializes the GetWarehouseResponse into a dictionary suitable for use as a JSON request body.""" @@ -3402,11 +3446,12 @@ class LegacyAlert: rearm: Optional[int] = None """Number of seconds after being triggered before the alert rearms itself and can be triggered - again. If `null`, alert will never be triggered again.""" + again. If ``null``, alert will never be triggered again.""" state: Optional[LegacyAlertState] = None - """State of the alert. Possible values are: `unknown` (yet to be evaluated), `triggered` (evaluated - and fulfilled trigger conditions), or `ok` (evaluated and did not fulfill trigger conditions).""" + """State of the alert. Possible values are: ``unknown`` (yet to be evaluated), ``triggered`` + (evaluated and fulfilled trigger conditions), or ``ok`` (evaluated and did not fulfill trigger + conditions).""" updated_at: Optional[str] = None """Timestamp when the alert was last updated.""" @@ -3501,9 +3546,7 @@ class LegacyQuery: data_source_id: Optional[str] = None """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""" + warehouse ID. `Learn more `__""" description: Optional[str] = None """General description that conveys additional information about this query such as usage notes.""" @@ -3513,8 +3556,8 @@ class LegacyQuery: is_archived: Optional[bool] = None """Indicates whether the query is trashed. Trashed queries can't be used in dashboards, or appear - in search results. If this boolean is `true`, the `options` property for this query includes a - `moved_to_trash_at` timestamp. Trashed queries are permanently deleted after 30 days.""" + in search results. If this boolean is ``true``, the ``options`` property for this query includes + a ``moved_to_trash_at`` timestamp. Trashed queries are permanently deleted after 30 days.""" is_draft: Optional[bool] = None """Whether the query is a draft. Draft queries only appear in list views for their owners. @@ -3526,7 +3569,7 @@ class LegacyQuery: is_safe: Optional[bool] = None """Text parameter types are not safe from SQL injection for all types of data source. Set this - Boolean parameter to `true` if a query either does not use any text type parameters or uses a + Boolean parameter to ``true`` if a query either does not use any text type parameters or uses a data source type where text type parameters are handled safely.""" last_modified_by: Optional[User] = None @@ -3547,8 +3590,10 @@ class LegacyQuery: """The identifier of the workspace folder containing the object.""" permission_tier: Optional[PermissionLevel] = None - """* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query - * `CAN_MANAGE`: Can manage the query""" + """- ``CAN_VIEW``: Can view the query + - ``CAN_RUN``: Can run the query + - ``CAN_EDIT``: Can edit the query + - ``CAN_MANAGE``: Can manage the query""" query: Optional[str] = None """The text of the query to be run.""" @@ -3557,8 +3602,8 @@ class LegacyQuery: """A SHA-256 hash of the query text along with the authenticated user ID.""" run_as_role: Optional[RunAsRole] = None - """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)""" + """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)""" tags: Optional[List[str]] = None @@ -3712,7 +3757,7 @@ def from_dict(cls, d: Dict[str, Any]) -> LegacyQuery: @dataclass class LegacyVisualization: """The visualization description API changes frequently and is unsupported. You can duplicate a - visualization by copying description objects received _from the API_ and then using them to + visualization by copying description objects received *from the API* and then using them to create a new one with a POST request to the same endpoint. Databricks does not recommend constructing ad-hoc visualizations entirely in JSON.""" @@ -3842,15 +3887,13 @@ class ListAlertsResponseAlert: """The timestamp indicating when the alert was created.""" custom_body: Optional[str] = None - """Custom body of alert notification, if it exists. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + """Custom body of alert notification, if it exists. See `here + `__ for custom templating instructions.""" custom_subject: Optional[str] = None """Custom subject of alert notification, if it exists. This can include email subject entries and - Slack notification headers, for example. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + Slack notification headers, for example. See `here + `__ for custom templating instructions.""" display_name: Optional[str] = None """The display name of the alert.""" @@ -4009,8 +4052,8 @@ class ListDefaultWarehouseOverridesResponse: """The default warehouse overrides in the workspace.""" next_page_token: Optional[str] = None - """A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, - there are no subsequent pages.""" + """A token, which can be sent as ``page_token`` to retrieve the next page. If this field is + omitted, there are no subsequent pages.""" def as_dict(self) -> dict: """Serializes the ListDefaultWarehouseOverridesResponse into a dictionary suitable for use as a JSON request body.""" @@ -4349,8 +4392,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ListVisualizationsForQueryResponse: @dataclass class ListWarehousesResponse: next_page_token: Optional[str] = None - """A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, - there are no subsequent pages.""" + """A token, which can be sent as ``page_token`` to retrieve the next page. If this field is + omitted, there are no subsequent pages.""" warehouses: Optional[List[EndpointInfo]] = None """A list of warehouses and their configurations.""" @@ -4601,8 +4644,10 @@ class ParameterType(Enum): class PermissionLevel(Enum): - """* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query - * `CAN_MANAGE`: Can manage the query""" + """- ``CAN_VIEW``: Can view the query + - ``CAN_RUN``: Can run the query + - ``CAN_EDIT``: Can edit the query + - ``CAN_MANAGE``: Can manage the query""" CAN_EDIT = "CAN_EDIT" CAN_MANAGE = "CAN_MANAGE" @@ -4828,7 +4873,7 @@ class QueryFilter: statuses: Optional[List[QueryStatus]] = None """A list of statuses (QUEUED, RUNNING, CANCELED, FAILED, FINISHED) to match query results. - Corresponds to the `status` field in the response. Filtering for multiple statuses is not + Corresponds to the ``status`` field in the response. Filtering for multiple statuses is not recommended. Instead, opt to filter by a single status multiple times and then combine the results.""" @@ -4899,7 +4944,7 @@ class QueryInfo: wall-clock time.""" endpoint_id: Optional[str] = None - """Alias for `warehouse_id`.""" + """Alias for ``warehouse_id``.""" error_message: Optional[str] = None """Message describing why the query could not complete.""" @@ -4961,9 +5006,11 @@ class QueryInfo: status: Optional[QueryStatus] = None """Query status with one the following values: - - `QUEUED`: Query has been received and queued. - `RUNNING`: Query has started. - `CANCELED`: - Query has been cancelled by the user. - `FAILED`: Query has failed. - `FINISHED`: Query has - completed.""" + - ``QUEUED``: Query has been received and queued. + - ``RUNNING``: Query has started. + - ``CANCELED``: Query has been cancelled by the user. + - ``FAILED``: Query has failed. + - ``FINISHED``: Query has completed.""" user_id: Optional[int] = None """The ID of the user who ran the query.""" @@ -5245,7 +5292,7 @@ class QueryMetrics: """Time spent fetching the query results after the execution finished, in milliseconds.""" result_from_cache: Optional[bool] = None - """`true` if the query result was fetched from cache, `false` otherwise.""" + """``true`` if the query result was fetched from cache, ``false`` otherwise.""" rows_produced_count: Optional[int] = None """Total number of rows returned by the query.""" @@ -5446,8 +5493,8 @@ class QueryOptions: """The name of the catalog to execute this query in.""" moved_to_trash_at: Optional[str] = None - """The timestamp when this query was moved to trash. Only present when the `is_archived` property - is `true`. Trashed items are deleted after thirty days.""" + """The timestamp when this query was moved to trash. Only present when the ``is_archived`` property + is ``true``. Trashed items are deleted after thirty days.""" parameters: Optional[List[Parameter]] = None @@ -5494,11 +5541,11 @@ def from_dict(cls, d: Dict[str, Any]) -> QueryOptions: @dataclass class QueryParameter: date_range_value: Optional[DateRangeValue] = None - """Date-range query parameter value. Can only specify one of `dynamic_date_range_value` or - `date_range_value`.""" + """Date-range query parameter value. Can only specify one of ``dynamic_date_range_value`` or + ``date_range_value``.""" date_value: Optional[DateValue] = None - """Date query parameter value. Can only specify one of `dynamic_date_value` or `date_value`.""" + """Date query parameter value. Can only specify one of ``dynamic_date_value`` or ``date_value``.""" enum_value: Optional[EnumValue] = None """Dropdown query parameter value.""" @@ -5616,7 +5663,7 @@ class QueryStatus(Enum): @dataclass class QueryTag: - """* A query execution can be annotated with an optional key-value pair to allow users to attribute + """- A query execution can be annotated with an optional key-value pair to allow users to attribute the executions by key and optional value to filter by. QueryTag is the user-facing representation.""" @@ -5702,34 +5749,34 @@ def from_dict(cls, d: Dict[str, Any]) -> RestoreResponse: @dataclass class ResultData: - """Contains the result data of a single chunk when using `INLINE` disposition. When using - `EXTERNAL_LINKS` disposition, the array `external_links` is used instead to provide URLs to the - result data in cloud storage. Exactly one of these alternatives is used. (While the - `external_links` array prepares the API to return multiple links in a single response. Currently - only a single link is returned.)""" + """Contains the result data of a single chunk when using ``INLINE`` disposition. When using + ``EXTERNAL_LINKS`` disposition, the array ``external_links`` is used instead to provide URLs to + the result data in cloud storage. Exactly one of these alternatives is used. (While the + ``external_links`` array prepares the API to return multiple links in a single response. + Currently only a single link is returned.)""" byte_count: Optional[int] = None - """The number of bytes in the result chunk. This field is not available when using `INLINE` + """The number of bytes in the result chunk. This field is not available when using ``INLINE`` disposition.""" chunk_index: Optional[int] = None """The position within the sequence of result set chunks.""" data_array: Optional[List[List[str]]] = None - """The `JSON_ARRAY` format is an array of arrays of values, where each non-null value is formatted - as a string. Null values are encoded as JSON `null`.""" + """The ``JSON_ARRAY`` format is an array of arrays of values, where each non-null value is + formatted as a string. Null values are encoded as JSON ``null``.""" external_links: Optional[List[ExternalLink]] = None next_chunk_index: Optional[int] = None - """When fetching, provides the `chunk_index` for the _next_ chunk. If absent, indicates there are + """When fetching, provides the ``chunk_index`` for the *next* chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a :method:statementexecution/getstatementresultchunkn request.""" next_chunk_internal_link: Optional[str] = None - """When fetching, provides a link to fetch the _next_ chunk. If absent, indicates there are no more - chunks. This link is an absolute `path` to be joined with your `$DATABRICKS_HOST`, and should be - treated as an opaque link. This is an alternative to using `next_chunk_index`.""" + """When fetching, provides a link to fetch the *next* chunk. If absent, indicates there are no more + chunks. This link is an absolute ``path`` to be joined with your ``$DATABRICKS_HOST``, and + should be treated as an opaque link. This is an alternative to using ``next_chunk_index``.""" row_count: Optional[int] = None """The number of rows within the result chunk.""" @@ -5806,7 +5853,7 @@ class ResultManifest: schema: Optional[ResultSchema] = None total_byte_count: Optional[int] = None - """The total number of bytes in the result set. This field is not available when using `INLINE` + """The total number of bytes in the result set. This field is not available when using ``INLINE`` disposition.""" total_chunk_count: Optional[int] = None @@ -5816,7 +5863,7 @@ class ResultManifest: """The total number of rows in the result set.""" truncated: Optional[bool] = None - """Indicates whether the result is truncated due to `row_limit` or `byte_limit`.""" + """Indicates whether the result is truncated due to ``row_limit`` or ``byte_limit``.""" def as_dict(self) -> dict: """Serializes the ResultManifest into a dictionary suitable for use as a JSON request body.""" @@ -6043,7 +6090,11 @@ class SpotInstancePolicy(Enum): +-------+--------------------------------------+--------------------------------+ | AWS | On Demand Driver with Spot Executors | On Demand Driver and Executors | | AZURE | On Demand Driver and Executors | On Demand Driver and Executors | - +-------+--------------------------------------+--------------------------------+""" + +-------+--------------------------------------+--------------------------------+ + + While including "spot" in the enum name may limit the the future extensibility of this field + because it limits this enum to denoting "spot or not", this is the field that PM recommends + after discussion with customers per SC-48783.""" COST_OPTIMIZED = "COST_OPTIMIZED" POLICY_UNSPECIFIED = "POLICY_UNSPECIFIED" @@ -6069,7 +6120,7 @@ def from_dict(cls, d: Dict[str, Any]) -> StartWarehouseResponse: class State(Enum): - """* State of a warehouse.""" + """State of a warehouse.""" DELETED = "DELETED" DELETING = "DELETING" @@ -6085,12 +6136,11 @@ class StatementParameterListItem: """The name of a parameter marker to be substituted in the statement.""" type: Optional[str] = None - """The data type, given as a string. For example: `INT`, `STRING`, `DECIMAL(10,2)`. If no type is - given the type is assumed to be `STRING`. Complex types, such as `ARRAY`, `MAP`, and `STRUCT` - are not supported. For valid types, refer to the section [Data types] of the SQL language - reference. - - [Data types]: https://docs.databricks.com/sql/language-manual/functions/cast.html""" + """The data type, given as a string. For example: ``INT``, ``STRING``, ``DECIMAL(10,2)``. If no + type is given the type is assumed to be ``STRING``. Complex types, such as ``ARRAY``, ``MAP``, + and ``STRUCT`` are not supported. For valid types, refer to the section `Data types + `__ of the SQL language + reference.""" value: Optional[str] = None """The value to substitute, represented as a string. If omitted, the value is interpreted as NULL.""" @@ -6189,14 +6239,18 @@ class StatementStatus: sql_state: Optional[str] = None """SQLSTATE error code returned when the statement execution fails. Only populated when the - statement status is `FAILED`.""" + statement status is ``FAILED``.""" state: Optional[StatementState] = None - """Statement execution state: - `PENDING`: waiting for warehouse - `RUNNING`: running - - `SUCCEEDED`: execution was successful, result data available for fetch - `FAILED`: execution - failed; reason for failure described in accompanying error message - `CANCELED`: user canceled; - can come from explicit cancel call, or timeout with `on_wait_timeout=CANCEL` - `CLOSED`: - execution successful, and statement closed; result no longer available for fetch""" + """Statement execution state: + + - ``PENDING``: waiting for warehouse + - ``RUNNING``: running + - ``SUCCEEDED``: execution was successful, result data available for fetch + - ``FAILED``: execution failed; reason for failure described in accompanying error message + - ``CANCELED``: user canceled; can come from explicit cancel call, or timeout with + ``on_wait_timeout=CANCEL`` + - ``CLOSED``: execution successful, and statement closed; result no longer available for fetch""" def as_dict(self) -> dict: """Serializes the StatementStatus into a dictionary suitable for use as a JSON request body.""" @@ -6674,15 +6728,13 @@ class UpdateAlertRequestAlert: """Trigger conditions of the alert.""" custom_body: Optional[str] = None - """Custom body of alert notification, if it exists. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + """Custom body of alert notification, if it exists. See `here + `__ for custom templating instructions.""" custom_subject: Optional[str] = None """Custom subject of alert notification, if it exists. This can include email subject entries and - Slack notification headers, for example. See [here] for custom templating instructions. - - [here]: https://docs.databricks.com/sql/user/alerts/index.html""" + Slack notification headers, for example. See `here + `__ for custom templating instructions.""" display_name: Optional[str] = None """The display name of the alert.""" @@ -7289,7 +7341,7 @@ def from_dict(cls, d: Dict[str, Any]) -> WarehousePermissionsDescription: @dataclass class WarehouseTypePair: - """* Configuration values to enable or disable the access to specific warehouse types in the + """Configuration values to enable or disable the access to specific warehouse types in the workspace.""" enabled: Optional[bool] = None @@ -7339,7 +7391,7 @@ class Widget: visualization: Optional[LegacyVisualization] = None """The visualization description API changes frequently and is unsupported. You can duplicate a - visualization by copying description objects received _from the API_ and then using them to + visualization by copying description objects received *from the API* and then using them to create a new one with a POST request to the same endpoint. Databricks does not recommend constructing ad-hoc visualizations entirely in JSON.""" @@ -7525,7 +7577,7 @@ def from_dict(cls, d: Dict[str, Any]) -> WidgetPosition: 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 + 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.""" def __init__(self, api_client): @@ -7647,14 +7699,14 @@ def update( :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :param alert: :class:`UpdateAlertRequestAlert` (optional) :param auto_resolve_display_name: bool (optional) If true, automatically resolve alert display name conflicts. Otherwise, fail the request if the @@ -7686,12 +7738,11 @@ def update( 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 + 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. - **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html""" + **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. `Learn more + `__""" def __init__(self, api_client): self._api = api_client @@ -7708,9 +7759,8 @@ def create( """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. - **Warning**: This API is deprecated. Please use :method:alerts/create instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:alerts/create instead. `Learn more + `__ :param name: str Name of the alert. @@ -7722,7 +7772,7 @@ def create( 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. + If ``null``, alert will never be triggered again. :returns: :class:`LegacyAlert` """ @@ -7754,9 +7804,8 @@ def delete(self, 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. - **Warning**: This API is deprecated. Please use :method:alerts/delete instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:alerts/delete instead. `Learn more + `__ :param alert_id: str @@ -7776,9 +7825,8 @@ def delete(self, alert_id: str): def get(self, alert_id: str) -> LegacyAlert: """Gets an alert. - **Warning**: This API is deprecated. Please use :method:alerts/get instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:alerts/get instead. `Learn more + `__ :param alert_id: str @@ -7799,9 +7847,8 @@ def get(self, alert_id: str) -> LegacyAlert: def list(self) -> Iterator[LegacyAlert]: """Gets a list of alerts. - **Warning**: This API is deprecated. Please use :method:alerts/list instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:alerts/list instead. `Learn more + `__ :returns: Iterator over :class:`LegacyAlert` @@ -7821,9 +7868,8 @@ def list(self) -> Iterator[LegacyAlert]: def update(self, alert_id: str, name: str, options: AlertOptions, query_id: str, *, rearm: Optional[int] = None): """Updates an alert. - **Warning**: This API is deprecated. Please use :method:alerts/update instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:alerts/update instead. `Learn more + `__ :param alert_id: str :param name: str @@ -7834,7 +7880,7 @@ def update(self, alert_id: str, name: str, options: AlertOptions, 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. + If ``null``, alert will never be triggered again. """ @@ -7971,14 +8017,14 @@ def update_alert(self, id: str, alert: AlertV2, update_mask: str) -> AlertV2: :param alert: :class:`AlertV2` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`AlertV2` """ @@ -8025,7 +8071,7 @@ def create( 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. + contains a visualization in the ``visualization`` field. :param visualization_id: str (optional) Query Vizualization ID returned by :method:queryvisualizations/create. @@ -8095,7 +8141,7 @@ def update( 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. + contains a visualization in the ``visualization`` field. :param visualization_id: str (optional) Query Vizualization ID returned by :method:queryvisualizations/create. @@ -8130,12 +8176,11 @@ 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. + to create a new one. Dashboards can be scheduled using the ``sql_task`` type of the Jobs API, e.g. :method:jobs/create. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/""" + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__""" def __init__(self, api_client): self._api = api_client @@ -8144,9 +8189,8 @@ def delete(self, dashboard_id: str): """Moves a dashboard to the trash. Trashed dashboards do not appear in list views or searches, and cannot be shared. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/ + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__ :param dashboard_id: str @@ -8166,9 +8210,8 @@ def delete(self, dashboard_id: str): def get(self, dashboard_id: str) -> Dashboard: """Returns a JSON representation of a dashboard object, including its visualization and query objects. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/ + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__ :param dashboard_id: str @@ -8199,9 +8242,8 @@ def list( **Warning**: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/ + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__ :param order: :class:`ListOrder` (optional) Name of dashboard attribute to order by. @@ -8245,9 +8287,8 @@ def list( def restore(self, dashboard_id: str): """A restored dashboard appears in list views and searches and can be shared. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/ + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__ :param dashboard_id: str @@ -8277,16 +8318,15 @@ def update( **Note**: You cannot undo this operation. - **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/dashboards/ + **Warning**: This API is deprecated. Please use the AI/BI Dashboards API instead. `Learn more + `__ :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) + 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` @@ -8314,28 +8354,26 @@ def update( 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. + 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 + 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. - **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html""" + **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. `Learn more + `__""" def __init__(self, api_client): self._api = api_client def list(self) -> Iterator[DataSource]: """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 + API response are enumerated for clarity. However, you need only a SQL warehouse's ``id`` to create new queries against it. - **Warning**: This API is deprecated. Please use :method:warehouses/list instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:warehouses/list instead. `Learn more + `__ :returns: Iterator over :class:`DataSource` @@ -8360,15 +8398,13 @@ class DbsqlPermissionsAPI: 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_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``) - - `CAN_MANAGE`: Allows all actions: read, run, edit, delete, modify permissions (superset of `CAN_RUN`) - - **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html""" + **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. `Learn more + `__""" def __init__(self, api_client): self._api = api_client @@ -8376,9 +8412,8 @@ def __init__(self, api_client): def get(self, object_type: ObjectTypePlural, object_id: str) -> GetResponse: """Gets a JSON representation of the access control list (ACL) for a specified object. - **Warning**: This API is deprecated. Please use :method:workspace/getpermissions instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:workspace/getpermissions instead. `Learn more + `__ :param object_type: :class:`ObjectTypePlural` The type of object permissions to check. @@ -8409,9 +8444,8 @@ def set( """Sets the access control list (ACL) for a specified object. This operation will complete rewrite the ACL. - **Warning**: This API is deprecated. Please use :method:workspace/setpermissions instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:workspace/setpermissions instead. `Learn more + `__ :param object_type: :class:`ObjectTypePlural` The type of object permission to set. @@ -8445,9 +8479,8 @@ def transfer_ownership( """Transfers ownership of a dashboard, query, or alert to an active user. Requires an admin API key. **Warning**: This API is deprecated. 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 + :method:alerts/update respectively instead. `Learn more + `__ :param object_type: :class:`OwnableObjectType` The type of object on which to change ownership. @@ -8483,7 +8516,7 @@ def transfer_ownership( 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.""" + scheduled using the ``sql_task`` type of the Jobs API, e.g. :method:jobs/create.""" def __init__(self, api_client): self._api = api_client @@ -8638,14 +8671,14 @@ def update( :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :param auto_resolve_display_name: bool (optional) If true, automatically resolve alert display name conflicts. Otherwise, fail the request if the alert's display name conflicts with an existing alert's display name. @@ -8677,11 +8710,10 @@ def update( 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. - - **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. [Learn more] + scheduled using the ``sql_task`` type of the Jobs API, e.g. :method:jobs/create. - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html""" + **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. `Learn more + `__""" def __init__(self, api_client): self._api = api_client @@ -8701,36 +8733,33 @@ def create( """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 + 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. + ``data_source_id`` from an existing query. **Note**: You cannot add a visualization until you create the query. - **Warning**: This API is deprecated. Please use :method:queries/create instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queries/create instead. `Learn more + `__ :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 + warehouse ID. `Learn more `__ :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. + 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) + 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` @@ -8769,9 +8798,8 @@ def delete(self, 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. - **Warning**: This API is deprecated. Please use :method:queries/delete instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queries/delete instead. `Learn more + `__ :param query_id: str @@ -8792,9 +8820,8 @@ def get(self, query_id: str) -> LegacyQuery: """Retrieve a query object definition along with contextual permissions information about the currently authenticated user. - **Warning**: This API is deprecated. Please use :method:queries/get instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queries/get instead. `Learn more + `__ :param query_id: str @@ -8825,24 +8852,19 @@ def list( **Warning**: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban. - **Warning**: This API is deprecated. Please use :method:queries/list instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queries/list instead. `Learn more + `__ :param order: str (optional) - Name of query attribute to order by. Default sort order is ascending. Append a dash (`-`) to order + 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. + - ``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) @@ -8884,9 +8906,8 @@ def restore(self, 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. - **Warning**: This API is deprecated. Please see the latest version. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please see the latest version. `Learn more + `__ :param query_id: str @@ -8919,29 +8940,26 @@ def update( **Note**: You cannot undo this operation. - **Warning**: This API is deprecated. Please use :method:queries/update instead. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queries/update instead. `Learn more + `__ :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 + warehouse ID. `Learn more `__ :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. + 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) + 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` @@ -8999,7 +9017,7 @@ def list( :param filter_by: :class:`QueryFilter` (optional) An optional filter object to limit query history results. Accepts parameters such as user IDs, endpoint IDs, and statuses to narrow the returned data. In a URL, the parameters of this filter are - specified with dot notation. For example: `filter_by.statement_ids`. + specified with dot notation. For example: ``filter_by.statement_ids``. :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. @@ -9090,14 +9108,14 @@ def update( :param id: str :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :param visualization: :class:`UpdateVisualizationRequestVisualization` (optional) :returns: :class:`Visualization` @@ -9125,9 +9143,8 @@ 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. - **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. [Learn more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html""" + **Warning**: This API is deprecated. Please see the latest version of the Databricks SQL API. `Learn more + `__""" def __init__(self, api_client): self._api = api_client @@ -9137,10 +9154,8 @@ def create( ) -> LegacyVisualization: """Creates visualization in the query. - **Warning**: This API is deprecated. Please use :method:queryvisualizations/create instead. [Learn - more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queryvisualizations/create instead. `Learn + more `__ :param options: Any The options object varies widely from one visualization type to the next and is unsupported. @@ -9183,10 +9198,8 @@ def create( def delete(self, id: str): """Removes a visualization from the query. - **Warning**: This API is deprecated. Please use :method:queryvisualizations/delete instead. [Learn - more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queryvisualizations/delete instead. `Learn + more `__ :param id: str Widget ID returned by :method:queryvisualizations/create @@ -9218,10 +9231,8 @@ def update( ) -> LegacyVisualization: """Updates visualization in the query. - **Warning**: This API is deprecated. Please use :method:queryvisualizations/update instead. [Learn - more] - - [Learn more]: https://docs.databricks.com/en/sql/dbsql-api-latest.html + **Warning**: This API is deprecated. Please use :method:queryvisualizations/update instead. `Learn + more `__ :param created_at: str (optional) :param description: str (optional) @@ -9302,7 +9313,8 @@ class StatementExecutionAPI: **Getting started** - We suggest beginning with the [Databricks SQL Statement Execution API tutorial]. + We suggest beginning with the `Databricks SQL Statement Execution API tutorial + `__. **Overview of statement execution and result fetching** @@ -9315,71 +9327,73 @@ class StatementExecutionAPI: :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` and `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. - **[Default] Hybrid mode** (`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. + 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`` and ``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. + - **[Default] Hybrid mode** (``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. + ``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`. + 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`: + 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. + - ``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``. - - `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`. + 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""" + - 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.""" def __init__(self, api_client): self._api = api_client @@ -9425,181 +9439,183 @@ def execute_statement( **Use case: small result sets with INLINE + JSON_ARRAY** - For flows that generate small and predictable result sets (<= 25 MiB), `INLINE` responses of - `JSON_ARRAY` result data are typically the simplest way to execute and fetch result data. + For flows that generate small and predictable result sets (<= 25 MiB), ``INLINE`` responses of + ``JSON_ARRAY`` result data are typically the simplest way to execute and fetch result data. **Use case: large result sets with EXTERNAL_LINKS** - Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result sets efficiently. The - main differences from using `INLINE` disposition are that the result data is accessed with URLs, and - that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV` compared to only - `JSON_ARRAY` with `INLINE`. + Using ``EXTERNAL_LINKS`` to fetch result data allows you to fetch large result sets efficiently. The + main differences from using ``INLINE`` disposition are that the result data is accessed with URLs, and + that there are 3 supported formats: ``JSON_ARRAY``, ``ARROW_STREAM`` and ``CSV`` compared to only + ``JSON_ARRAY`` with ``INLINE``. ** URLs** External links point to data stored within your workspace's internal storage, in the form of a URL. - The URLs are valid for only a short period, <= 15 minutes. Alongside each `external_link` is an - expiration field indicating the time at which the URL is no longer valid. In `EXTERNAL_LINKS` mode, + The URLs are valid for only a short period, <= 15 minutes. Alongside each ``external_link`` is an + expiration field indicating the time at which the URL is no longer valid. In ``EXTERNAL_LINKS`` mode, chunks can be resolved and fetched multiple times and in parallel. - ---- - - ### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the - `EXTERNAL_LINKS` disposition.** + ****Warning: Databricks strongly recommends that you protect the URLs that are returned by the ``EXTERNAL_LINKS`` disposition.**** - When you use the `EXTERNAL_LINKS` disposition, a short-lived, URL is generated, which can be used to + When you use the ``EXTERNAL_LINKS`` disposition, a short-lived, URL is generated, which can be used to download the results directly from . As a short-lived is embedded in this URL, you should protect the URL. - Because URLs are already generated with embedded temporary s, you must not set an `Authorization` + Because URLs are already generated with embedded temporary s, you must not set an ``Authorization`` header in the download requests. - The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a support case. - - See also [Security best practices]. + The ``EXTERNAL_LINKS`` disposition can be disabled upon request by creating a support case. - ---- + See also `Security best practices + `__. - StatementResponse contains `statement_id` and `status`; other fields might be absent or present + StatementResponse contains ``statement_id`` and ``status``; other fields might be absent or present depending on context. If the SQL warehouse fails to execute the provided statement, a 200 response is - returned with `status.state` set to `FAILED` (in contrast to a failure when accepting the request, - which results in a non-200 response). Details of the error can be found at `status.error` in case of + returned with ``status.state`` set to ``FAILED`` (in contrast to a failure when accepting the request, + which results in a non-200 response). Details of the error can be found at ``status.error`` in case of execution failures. - [Security best practices]: https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices - :param statement: str - The SQL statement to execute. The statement can optionally be parameterized, see `parameters`. The + The SQL statement to execute. The statement can optionally be parameterized, see ``parameters``. The maximum query text size is 16 MiB. :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 + Warehouse upon which to execute a statement. See also `What are SQL warehouses? + `__ :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 - explicitly set. + 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 explicitly 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 + Sets default catalog for statement execution, similar to ```USE CATALOG`` + `__ in SQL. :param disposition: :class:`Disposition` (optional) - The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`. + The fetch disposition provides two modes of fetching results: ``INLINE`` and ``EXTERNAL_LINKS``. - Statements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` + Statements executed with ``INLINE`` disposition will return result data inline, in ``JSON_ARRAY`` format, in a series of chunks. If a given statement produces a result set with a size larger than 25 MiB, that statement execution is aborted, and no result set will be available. **NOTE** Byte limits are computed based upon internal representations of the result set data, and might not match the sizes visible in JSON responses. - Statements executed with `EXTERNAL_LINKS` disposition will return result data as external links: - URLs that point to cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition + Statements executed with ``EXTERNAL_LINKS`` disposition will return result data as external links: + URLs that point to cloud storage internal to the workspace. Using ``EXTERNAL_LINKS`` disposition allows statements to generate arbitrarily sized result sets for fetching up to 100 GiB. The resulting links have two important properties: - 1. They point to resources _external_ to the Databricks compute; therefore any associated - authentication information (typically a personal access token, OAuth token, or similar) _must be - removed_ when fetching from these links. - + 1. They point to resources *external* to the Databricks compute; therefore any associated + authentication information (typically a personal access token, OAuth token, or similar) *must be + removed* when fetching from these links. 2. These are URLs with a specific expiration, indicated in the response. The behavior when - attempting to use an expired link is cloud specific. + attempting to use an expired link is cloud specific. :param format: :class:`Format` (optional) - Statement execution supports three result formats: `JSON_ARRAY` (default), `ARROW_STREAM`, and - `CSV`. + 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. - 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: - 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: + .. code-block:: - ``` [ [ "id-1", "1", null ], [ "id-2", "2", null ], [ "id-3", "3", null ], ] ``` + [ + [ "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 + 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=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: + 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 ``` + .. code-block:: - [Apache Arrow streaming format]: https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format - [RFC 4180]: https://www.rfc-editor.org/rfc/rfc4180 + strCol,intCol,nullCol + id-1,1,null + id-2,2,null + id-3,3,null :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. + 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. + 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 + 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`: + For example, the following statement contains two parameters, ``my_name`` and ``my_date``: + + .. code-block:: - ``` SELECT * FROM my_table WHERE name = :my_name AND date = :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", + ``{ ..., "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" } ] } ` + "2020-01-01", "type": "DATE" } ] }`` - Currently, positional parameters denoted by a `?` marker are not supported by the Databricks SQL + 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 + Also see the section `Parameter markers + `__ of the SQL + language reference. :param query_tags: List[:class:`QueryTag`] (optional) An array of query tags to annotate a SQL statement. A query tag consists of a non-empty key and, - optionally, a value. To represent a NULL value, either omit the `value` field or manually set it to - `null` or white space. Refer to the SQL language reference for the format specification of query - tags. There's no significance to the order of tags. Only one value per key will be recorded. A + optionally, a value. To represent a NULL value, either omit the ``value`` field or manually set it + to ``null`` or white space. Refer to the SQL language reference for the format specification of + query tags. There's no significance to the order of tags. Only one value per key will be recorded. A sequence in excess of 20 query tags will be coerced to 20. Example: { ..., "query_tags": [ { "key": "team", "value": "eng" }, { "key": "some key only tag" } ] } :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. + 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 + Sets default schema for statement execution, similar to ```USE SCHEMA`` + `__ in SQL. :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. + 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 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. + 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` """ @@ -9642,12 +9658,12 @@ def execute_statement( return StatementResponse.from_dict(res) def get_statement(self, statement_id: str) -> StatementResponse: - """This request can be used to poll for the statement's status. StatementResponse contains `statement_id` - and `status`; other fields might be absent or present depending on context. 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. + """This request can be used to poll for the statement's status. StatementResponse contains + ``statement_id`` and ``status``; other fields might be absent or present depending on context. 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. @@ -9670,13 +9686,13 @@ def get_statement(self, statement_id: str) -> StatementResponse: return StatementResponse.from_dict(res) def get_statement_result_chunk_n(self, statement_id: str, chunk_index: int) -> ResultData: - """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 + """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` + 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. - Depending on `disposition`, the response returns chunks of data either inline, or as links. + ``next_chunk_index`` and ``next_chunk_internal_link`` fields for simple iteration through the result + set. Depending on ``disposition``, the response returns chunks of data either inline, or as links. :param statement_id: str The statement ID is returned upon successfully submitting a SQL statement, and is a required @@ -9791,7 +9807,10 @@ def create( 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. + Supported values: + + - Must be == 0 or >= 10 mins + - 0 indicates no autostop. Defaults to 120 mins :param channel: :class:`Channel` (optional) @@ -9801,8 +9820,18 @@ def create( 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 - 5X-Large - Auto + Supported values: + + - 2X-Small + - X-Small + - Small + - Medium + - Large + - X-Large + - 2X-Large + - 3X-Large + - 4X-Large + - 5X-Large :param creator_name: str (optional) warehouse creator name :param enable_photon: bool (optional) @@ -9816,7 +9845,10 @@ def create( :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 <= 40. + Supported values: + + - Must be >= min_num_clusters + - Must be <= 40. Defaults to min_clusters if unset. :param min_num_clusters: int (optional) @@ -9824,23 +9856,31 @@ def create( 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) + 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. + Supported values: + + - Must be unique within an org. + - Must be less than 100 characters. :param spot_instance_policy: :class:`SpotInstancePolicy` (optional) Configurations whether the endpoint 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. + 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`. + 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`. @@ -10024,7 +10064,10 @@ def edit( 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. + Supported values: + + - Must be == 0 or >= 10 mins + - 0 indicates no autostop. Defaults to 120 mins :param channel: :class:`Channel` (optional) @@ -10034,8 +10077,18 @@ def edit( 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 - 5X-Large - Auto + Supported values: + + - 2X-Small + - X-Small + - Small + - Medium + - Large + - X-Large + - 2X-Large + - 3X-Large + - 4X-Large + - 5X-Large :param creator_name: str (optional) warehouse creator name :param enable_photon: bool (optional) @@ -10049,7 +10102,10 @@ def edit( :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 <= 40. + Supported values: + + - Must be >= min_num_clusters + - Must be <= 40. Defaults to min_clusters if unset. :param min_num_clusters: int (optional) @@ -10057,23 +10113,31 @@ def edit( 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) + 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. + Supported values: + + - Must be unique within an org. + - Must be less than 100 characters. :param spot_instance_policy: :class:`SpotInstancePolicy` (optional) Configurations whether the endpoint 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. + 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`. + 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`. @@ -10266,11 +10330,11 @@ def list( :param page_size: int (optional) The max number of warehouses to return. :param page_token: str (optional) - A page token, received from a previous `ListWarehouses` call. Provide this to retrieve the + A page token, received from a previous ``ListWarehouses`` call. Provide this to retrieve the subsequent page; otherwise the first will be retrieved. - When paginating, all other parameters provided to `ListWarehouses` must match the call that provided - the page token. + When paginating, all other parameters provided to ``ListWarehouses`` must match the call that + provided the page token. :param run_as_user_id: int (optional) Deprecated: this field is ignored by the server. Service Principal which will be used to fetch the list of endpoints. If not specified, SQL Gateway will use the user from the session header. @@ -10313,10 +10377,10 @@ def list_default_warehouse_overrides( unspecified, at most 100 overrides will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. :param page_token: str (optional) - A page token, received from a previous `ListDefaultWarehouseOverrides` call. Provide this to + A page token, received from a previous ``ListDefaultWarehouseOverrides`` call. Provide this to retrieve the subsequent page. - When paginating, all other parameters provided to `ListDefaultWarehouseOverrides` must match the + When paginating, all other parameters provided to ``ListDefaultWarehouseOverrides`` must match the call that provided the page token. :returns: Iterator over :class:`DefaultWarehouseOverride` @@ -10523,7 +10587,7 @@ def update_default_warehouse_override( fields are applied. :param allow_missing: bool (optional) If set to true, and the override is not found, a new override will be created. In this situation, - `update_mask` is ignored and all fields are applied. Defaults to false. + ``update_mask`` is ignored and all fields are applied. Defaults to false. :returns: :class:`DefaultWarehouseOverride` """ diff --git a/databricks/sdk/service/supervisoragents.py b/databricks/sdk/service/supervisoragents.py index 1662aa278..fb9b6a1d2 100755 --- a/databricks/sdk/service/supervisoragents.py +++ b/databricks/sdk/service/supervisoragents.py @@ -228,7 +228,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListExamplesResponse: @dataclass class ListSupervisorAgentsResponse: next_page_token: Optional[str] = None - """A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, + """A token that can be sent as ``page_token`` to retrieve the next page. If this field is omitted, there are no subsequent pages.""" supervisor_agents: Optional[List[SupervisorAgent]] = None @@ -1058,8 +1058,8 @@ def list_examples( The maximum number of examples to return. If unspecified, at most 100 examples will be returned. The maximum value is 100; values above 100 will be coerced to 100. :param page_token: str (optional) - A page token, received from a previous `ListExamples` call. Provide this to retrieve the subsequent - page. If unspecified, the first page will be returned. + A page token, received from a previous ``ListExamples`` call. Provide this to retrieve the + subsequent page. If unspecified, the first page will be returned. :returns: Iterator over :class:`Example` """ @@ -1095,7 +1095,7 @@ def list_supervisor_agents( The maximum number of supervisor agents to return. If unspecified, at most 100 supervisor agents will be returned. The maximum value is 100; values above 100 will be coerced to 100. :param page_token: str (optional) - A page token, received from a previous `ListSupervisorAgents` call. Provide this to retrieve the + A page token, received from a previous ``ListSupervisorAgents`` call. Provide this to retrieve the subsequent page. If unspecified, the first page will be returned. :returns: Iterator over :class:`SupervisorAgent` @@ -1199,8 +1199,11 @@ def update_example(self, name: str, example: Example, update_mask: FieldMask) -> supervisor-agents/{supervisor_agent_id}/examples/{example_id} :param example: :class:`Example` :param update_mask: FieldMask - Comma-delimited list of fields to update on the example. Allowed values: `question`, `guidelines`. - Examples: - `question` - `question,guidelines` + Comma-delimited list of fields to update on the example. Allowed values: ``question``, + ``guidelines``. Examples: + + - ``question`` + - ``question,guidelines`` :returns: :class:`Example` """ @@ -1258,7 +1261,7 @@ def update_supervisor_agent( self, name: str, supervisor_agent: SupervisorAgent, update_mask: FieldMask ) -> SupervisorAgent: """Updates a Supervisor Agent. The fields that are required depend on the paths specified in - `update_mask`. Only fields included in the mask will be updated. + ``update_mask``. Only fields included in the mask will be updated. :param name: str The resource name of the SupervisorAgent. Format: supervisor-agents/{supervisor_agent_id} @@ -1287,7 +1290,7 @@ def update_supervisor_agent( return SupervisorAgent.from_dict(res) def update_tool(self, name: str, tool: Tool, update_mask: FieldMask) -> Tool: - """Updates a Tool. Only the `description` field can be updated. To change immutable fields such as tool + """Updates a Tool. Only the ``description`` field can be updated. To change immutable fields such as tool type, spec, or tool ID, delete the tool and recreate it. :param name: str diff --git a/databricks/sdk/service/tags.py b/databricks/sdk/service/tags.py index cf4d9246f..63e387c92 100755 --- a/databricks/sdk/service/tags.py +++ b/databricks/sdk/service/tags.py @@ -227,22 +227,20 @@ def from_dict(cls, d: Dict[str, Any]) -> Value: class TagPoliciesAPI: """The Tag Policy API allows you to manage policies for governed tags in Databricks. For Terraform usage, see - the [Tag Policy Terraform documentation]. Permissions for tag policies can be managed using the [Account - Access Control Proxy API]. - - [Account Access Control Proxy API]: https://docs.databricks.com/api/workspace/accountaccesscontrolproxy - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/tag_policy""" + the `Tag Policy Terraform documentation + `__. + Permissions for tag policies can be managed using the `Account Access Control Proxy API + `__.""" def __init__(self, api_client): self._api = api_client def create_tag_policy(self, tag_policy: TagPolicy) -> TagPolicy: - """Creates a new tag policy, making the associated tag key governed. For Terraform usage, see the [Tag - Policy Terraform documentation]. To manage permissions for tag policies, use the [Account Access - Control Proxy API]. - - [Account Access Control Proxy API]: https://docs.databricks.com/api/workspace/accountaccesscontrolproxy - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/tag_policy + """Creates a new tag policy, making the associated tag key governed. For Terraform usage, see the `Tag + Policy Terraform documentation + `__. + To manage permissions for tag policies, use the `Account Access Control Proxy API + `__. :param tag_policy: :class:`TagPolicy` @@ -265,9 +263,8 @@ def create_tag_policy(self, tag_policy: TagPolicy) -> TagPolicy: def delete_tag_policy(self, tag_key: str): """Deletes a tag policy by its associated governed tag's key, leaving that tag key ungoverned. For - Terraform usage, see the [Tag Policy Terraform documentation]. - - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/tag_policy + Terraform usage, see the `Tag Policy Terraform documentation + `__. :param tag_key: str @@ -285,12 +282,11 @@ def delete_tag_policy(self, tag_key: str): self._api.do("DELETE", f"/api/2.1/tag-policies/{tag_key}", headers=headers) def get_tag_policy(self, tag_key: str) -> TagPolicy: - """Gets a single tag policy by its associated governed tag's key. For Terraform usage, see the [Tag - Policy Terraform documentation]. To list granted permissions for tag policies, use the [Account Access - Control Proxy API]. - - [Account Access Control Proxy API]: https://docs.databricks.com/api/workspace/accountaccesscontrolproxy - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/data-sources/tag_policy + """Gets a single tag policy by its associated governed tag's key. For Terraform usage, see the `Tag + Policy Terraform documentation + `__. + To list granted permissions for tag policies, use the `Account Access Control Proxy API + `__. :param tag_key: str @@ -311,12 +307,11 @@ def get_tag_policy(self, tag_key: str) -> TagPolicy: def list_tag_policies( self, *, page_size: Optional[int] = None, page_token: Optional[str] = None ) -> Iterator[TagPolicy]: - """Lists the tag policies for all governed tags in the account. For Terraform usage, see the [Tag Policy - Terraform documentation]. To list granted permissions for tag policies, use the [Account Access - Control Proxy API]. - - [Account Access Control Proxy API]: https://docs.databricks.com/api/workspace/accountaccesscontrolproxy - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/data-sources/tag_policies + """Lists the tag policies for all governed tags in the account. For Terraform usage, see the `Tag Policy + Terraform documentation + `__. + To list granted permissions for tag policies, use the `Account Access Control Proxy API + `__. :param page_size: int (optional) The maximum number of results to return in this request. Fewer results may be returned than @@ -351,25 +346,24 @@ def list_tag_policies( query["page_token"] = json["next_page_token"] def update_tag_policy(self, tag_key: str, tag_policy: TagPolicy, update_mask: str) -> TagPolicy: - """Updates an existing tag policy for a single governed tag. For Terraform usage, see the [Tag Policy - Terraform documentation]. To manage permissions for tag policies, use the [Account Access Control - Proxy API]. - - [Account Access Control Proxy API]: https://docs.databricks.com/api/workspace/accountaccesscontrolproxy - [Tag Policy Terraform documentation]: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/tag_policy + """Updates an existing tag policy for a single governed tag. For Terraform usage, see the `Tag Policy + Terraform documentation + `__. + To manage permissions for tag policies, use the `Account Access Control Proxy API + `__. :param tag_key: str :param tag_policy: :class:`TagPolicy` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`TagPolicy` """ @@ -529,14 +523,14 @@ def update_tag_assignment( :param tag_assignment: :class:`TagAssignment` :param update_mask: str The field mask must be a single string, with multiple fields separated by commas (no spaces). The - field path is relative to the resource object, using a dot (`.`) to navigate sub-fields (e.g., - `author.given_name`). Specification of elements in sequence or map fields is not allowed, as only + field path is relative to the resource object, using a dot (``.``) to navigate sub-fields (e.g., + ``author.given_name``). Specification of elements in sequence or map fields is not allowed, as only the entire collection field can be specified. Field names must exactly match the resource field names. - A field mask of `*` indicates full replacement. It’s recommended to always explicitly list the - fields being updated and avoid using `*` wildcards, as it can lead to unintended results if the API - changes in the future. + A field mask of ``*`` indicates full replacement. It’s recommended to always explicitly list the + fields being updated and avoid using ``*`` wildcards, as it can lead to unintended results if the + API changes in the future. :returns: :class:`TagAssignment` """ diff --git a/databricks/sdk/service/vectorsearch.py b/databricks/sdk/service/vectorsearch.py index 9d38c06cb..9e4bb74c3 100755 --- a/databricks/sdk/service/vectorsearch.py +++ b/databricks/sdk/service/vectorsearch.py @@ -223,11 +223,13 @@ class DeltaSyncVectorIndexSpecRequest: """[Optional] Name of the Delta table to sync the vector index contents and computed embeddings to.""" pipeline_type: Optional[PipelineType] = None - """Pipeline execution mode. - `TRIGGERED`: If the pipeline uses the triggered execution mode, the - system stops processing after successfully refreshing the source table in the pipeline once, - ensuring the table is updated based on the data available when the update started. - - `CONTINUOUS`: If the pipeline uses continuous execution, the pipeline processes new data as it - arrives in the source table to keep vector index fresh.""" + """Pipeline execution mode. + + - ``TRIGGERED``: If the pipeline uses the triggered execution mode, the system stops processing + after successfully refreshing the source table in the pipeline once, ensuring the table is + updated based on the data available when the update started. + - ``CONTINUOUS``: If the pipeline uses continuous execution, the pipeline processes new data as + it arrives in the source table to keep vector index fresh.""" source_table: Optional[str] = None """The name of the source table.""" @@ -310,11 +312,13 @@ class DeltaSyncVectorIndexSpecResponse: """The ID of the pipeline that is used to sync the index.""" pipeline_type: Optional[PipelineType] = None - """Pipeline execution mode. - `TRIGGERED`: If the pipeline uses the triggered execution mode, the - system stops processing after successfully refreshing the source table in the pipeline once, - ensuring the table is updated based on the data available when the update started. - - `CONTINUOUS`: If the pipeline uses continuous execution, the pipeline processes new data as it - arrives in the source table to keep vector index fresh.""" + """Pipeline execution mode. + + - ``TRIGGERED``: If the pipeline uses the triggered execution mode, the system stops processing + after successfully refreshing the source table in the pipeline once, ensuring the table is + updated based on the data available when the update started. + - ``CONTINUOUS``: If the pipeline uses continuous execution, the pipeline processes new data as + it arrives in the source table to keep vector index fresh.""" source_table: Optional[str] = None """The name of the source table.""" @@ -385,9 +389,9 @@ class DirectAccessVectorIndexSpec: """The columns that contain the embedding vectors. The format should be array[double].""" schema_json: Optional[str] = None - """The schema of the index in JSON format. Supported types are `integer`, `long`, `float`, - `double`, `boolean`, `string`, `date`, `timestamp`. Supported types for vector column: - `array`, `array`,`.""" + """The schema of the index in JSON format. Supported types are ``integer``, ``long``, ``float``, + ``double``, ``boolean``, ``string``, ``date``, ``timestamp``. Supported types for vector column: + ``array``, ``array``,`.""" def as_dict(self) -> dict: """Serializes the DirectAccessVectorIndexSpec into a dictionary suitable for use as a JSON request body.""" @@ -711,7 +715,7 @@ class FacetResultData: """Facet aggregation rows returned by a query.""" facet_array: Optional[List[List[str]]] = None - """Facet rows. Each row is `[facet_column_name, value_or_range, count]`.""" + """Facet rows. Each row is ``[facet_column_name, value_or_range, count]``.""" facet_row_count: Optional[int] = None """Number of facet rows returned.""" @@ -766,10 +770,11 @@ def from_dict(cls, d: Dict[str, Any]) -> GetVectorSearchEndpointPermissionLevels class IndexSubtype(Enum): - """The subtype of the AI Search index, determining the indexing and retrieval strategy. - `VECTOR`: - Not supported. Use `HYBRID` instead. - `FULL_TEXT`: An index that uses full-text search without - vector embeddings. - `HYBRID`: An index that uses vector embeddings for similarity search and - hybrid search.""" + """The subtype of the AI Search index, determining the indexing and retrieval strategy. + + - ``VECTOR``: Not supported. Use ``HYBRID`` instead. + - ``FULL_TEXT``: An index that uses full-text search without vector embeddings. + - ``HYBRID``: An index that uses vector embeddings for similarity search and hybrid search.""" FULL_TEXT = "FULL_TEXT" HYBRID = "HYBRID" @@ -1153,11 +1158,13 @@ def from_dict(cls, d: Dict[str, Any]) -> PatchEndpointBudgetPolicyResponse: class PipelineType(Enum): - """Pipeline execution mode. - `TRIGGERED`: If the pipeline uses the triggered execution mode, the - system stops processing after successfully refreshing the source table in the pipeline once, - ensuring the table is updated based on the data available when the update started. - - `CONTINUOUS`: If the pipeline uses continuous execution, the pipeline processes new data as it - arrives in the source table to keep vector index fresh.""" + """Pipeline execution mode. + + - ``TRIGGERED``: If the pipeline uses the triggered execution mode, the system stops processing + after successfully refreshing the source table in the pipeline once, ensuring the table is + updated based on the data available when the update started. + - ``CONTINUOUS``: If the pipeline uses continuous execution, the pipeline processes new data as + it arrives in the source table to keep vector index fresh.""" CONTINUOUS = "CONTINUOUS" TRIGGERED = "TRIGGERED" @@ -1172,9 +1179,9 @@ class QueryVectorIndexResponse: """Metadata about the result set.""" next_page_token: Optional[str] = None - """[Optional] Token that can be used in `QueryVectorIndexNextPage` API to get next page of results. - If more than 1000 results satisfy the query, they are returned in groups of 1000. Empty value - means no more results. The maximum number of results that can be returned is 10,000.""" + """[Optional] Token that can be used in ``QueryVectorIndexNextPage`` API to get next page of + results. If more than 1000 results satisfy the query, they are returned in groups of 1000. Empty + value means no more results. The maximum number of results that can be returned is 10,000.""" result: Optional[ResultData] = None """Data returned in the query result.""" @@ -1219,8 +1226,10 @@ def from_dict(cls, d: Dict[str, Any]) -> QueryVectorIndexResponse: @dataclass class RerankerConfig: model: Optional[str] = None - """Reranker identifier: - When model_type=BASE/UNSPECIFIED: must be "databricks_reranker". - When - model_type=FINETUNED: the Model Serving endpoint name hosting a finetuned reranker.""" + """Reranker identifier: + + - When model_type=BASE/UNSPECIFIED: must be "databricks_reranker". + - When model_type=FINETUNED: the Model Serving endpoint name hosting a finetuned reranker.""" parameters: Optional[RerankerConfigRerankerParameters] = None """Parameters that control how the reranker processes the query results.""" @@ -1318,10 +1327,10 @@ class ResultManifest: """Information about each column in the result set.""" facet_column_count: Optional[int] = None - """Number of columns in `facet_result`.""" + """Number of columns in ``facet_result``.""" facet_columns: Optional[List[ColumnInfo]] = None - """Information about each column in `facet_result`.""" + """Information about each column in ``facet_result``.""" def as_dict(self) -> dict: """Serializes the ResultManifest into a dictionary suitable for use as a JSON request body.""" @@ -1778,11 +1787,12 @@ def from_dict(cls, d: Dict[str, Any]) -> VectorIndexStatus: class VectorIndexType(Enum): - """There are 2 types of AI 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.""" + """There are 2 types of AI 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.""" DELTA_SYNC = "DELTA_SYNC" DIRECT_ACCESS = "DIRECT_ACCESS" @@ -2445,10 +2455,12 @@ 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 AI 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.""" + There are 2 types of AI 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.""" def __init__(self, api_client): self._api = api_client @@ -2474,11 +2486,11 @@ def create_index( Primary key of the index :param index_type: :class:`VectorIndexType` :param delta_sync_index_spec: :class:`DeltaSyncVectorIndexSpecRequest` (optional) - Specification for Delta Sync Index. Required if `index_type` is `DELTA_SYNC`. + 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`. + Specification for Direct Vector Access Index. Required if ``index_type`` is ``DIRECT_ACCESS``. :param index_subtype: :class:`IndexSubtype` (optional) - The subtype of the index. Use `HYBRID` or `FULL_TEXT`. `VECTOR` is not supported. + The subtype of the index. Use ``HYBRID`` or ``FULL_TEXT``. ``VECTOR`` is not supported. :returns: :class:`VectorIndex` """ @@ -2642,40 +2654,42 @@ def query_index( :param columns_to_rerank: List[str] (optional) Column names used to retrieve data to send to the reranker. :param facets: List[str] (optional) - Facets to compute over the matched results. Each entry has one of these forms: `""` - top 10 - distinct values by count `" TOP "` - top n distinct values, where n > 0 `" - BUCKETS [[from,to],...]"` - inclusive numeric ranges `TOP` and `BUCKETS` are case-insensitive. A - column may appear at most once. + Facets to compute over the matched results. Each entry has one of these forms: ``""`` - top + 10 distinct values by count ``" TOP "`` - top n distinct values, where n > 0 ``" + BUCKETS [[from,to],...]"`` - inclusive numeric ranges ``TOP`` and ``BUCKETS`` are case-insensitive. + A column may appear at most once. :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. + - ``{"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_columns: List[str] (optional) - Text columns to search for `query_text`. When empty, all text columns are searched. + Text columns to search for ``query_text``. When empty, all text columns are searched. :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` and `FULL_TEXT`. Defaults to `ANN`. + The query type to use. Choices are ``ANN`` and ``HYBRID`` and ``FULL_TEXT``. 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 reranker: :class:`RerankerConfig` (optional) If set, the top 50 results are reranked with the Databricks Reranker model before returning the - `num_results` results to the user. The setting `columns_to_rerank` selects which columns are used - for reranking. For each datapoint, the columns selected are concatenated before being sent to the - reranking model. See https://docs.databricks.com/aws/en/vector-search/query-vector-search#rerank for - more information. + ``num_results`` results to the user. The setting ``columns_to_rerank`` selects which columns are + used for reranking. For each datapoint, the columns selected are concatenated before being sent to + the reranking model. See https://docs.databricks.com/aws/en/vector-search/query-vector-search#rerank + for more information. :param score_threshold: float (optional) Threshold for the approximate nearest neighbor search. Defaults to 0.0. :param sort_columns: List[str] (optional) Sort results by column values instead of the default relevance ordering. Each clause has the form - `" ASC"` or `" DESC"`, for example `["rating DESC", "price ASC"]`. + ``" ASC"`` or ``" DESC"``, for example ``["rating DESC", "price ASC"]``. :returns: :class:`QueryVectorIndexResponse` """ @@ -2720,15 +2734,15 @@ def query_index( def query_next_page( self, index_name: str, *, endpoint_name: Optional[str] = None, page_token: Optional[str] = None ) -> QueryVectorIndexResponse: - """Use `next_page_token` returned from previous `QueryVectorIndex` or `QueryVectorIndexNextPage` request - to fetch next page of results. + """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. + Page token returned from previous ``QueryVectorIndex`` or ``QueryVectorIndexNextPage`` API. :returns: :class:`QueryVectorIndexResponse` """ @@ -2755,8 +2769,8 @@ def query_next_page( def scan_index( self, index_name: str, *, last_primary_key: Optional[str] = None, num_results: Optional[int] = None ) -> ScanVectorIndexResponse: - """Scan the specified vector index and return the first `num_results` entries after the exclusive - `primary_key`. + """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. diff --git a/databricks/sdk/service/workspace.py b/databricks/sdk/service/workspace.py index e6bff5f50..70292f6e1 100755 --- a/databricks/sdk/service/workspace.py +++ b/databricks/sdk/service/workspace.py @@ -67,7 +67,7 @@ class AclPermission(Enum): @dataclass class AzureKeyVaultSecretScopeMetadata: - """The metadata of the Azure KeyVault for a secret scope of type `AZURE_KEYVAULT`""" + """The metadata of the Azure KeyVault for a secret scope of type ``AZURE_KEYVAULT``""" resource_id: str """The resource id of the azure KeyVault that user wants to associate the scope with.""" @@ -187,9 +187,9 @@ class CreateRepoResponse: """Path of the Git folder (repo) in the workspace.""" provider: Optional[str] = None - """Git provider of the linked Git repository, e.g. `gitHub`, `azureDevOpsServices`, - `bitbucketServer` (Bitbucket Data Center), `gitLabEnterpriseEdition` (GitLab Self-Managed), or - `awsCodeCommit` (deprecated).""" + """Git provider of the linked Git repository, e.g. ``gitHub``, ``azureDevOpsServices``, + ``bitbucketServer`` (Bitbucket Data Center), ``gitLabEnterpriseEdition`` (GitLab Self-Managed), + or ``awsCodeCommit`` (deprecated).""" sparse_checkout: Optional[SparseCheckout] = None """Sparse checkout settings for the Git folder (repo).""" @@ -261,10 +261,10 @@ class CredentialInfo: https://docs.databricks.com/aws/en/repos/get-access-tokens-from-git-provider""" git_provider: Optional[str] = None - """The Git provider associated with the credential. One of `gitHub`, `bitbucketCloud`, `gitLab`, - `azureDevOpsServices` (Azure DevOps Services, including Microsoft Entra ID authentication), - `gitHubEnterprise`, `bitbucketServer` (Bitbucket Data Center), `gitLabEnterpriseEdition` (GitLab - Self-Managed), or `awsCodeCommit` (deprecated).""" + """The Git provider associated with the credential. One of ``gitHub``, ``bitbucketCloud``, + ``gitLab``, ``azureDevOpsServices`` (Azure DevOps Services, including Microsoft Entra ID + authentication), ``gitHubEnterprise``, ``bitbucketServer`` (Bitbucket Data Center), + ``gitLabEnterpriseEdition`` (GitLab Self-Managed), or ``awsCodeCommit`` (deprecated).""" git_username: Optional[str] = None """The username provided with your Git provider account and associated with the credential. For @@ -411,7 +411,7 @@ class ExportFormat(Enum): @dataclass class ExportResponse: - """The request field `direct_download` determines whether a JSON response or binary contents are + """The request field ``direct_download`` determines whether a JSON response or binary contents are returned by this endpoint.""" content: Optional[str] = None @@ -558,9 +558,9 @@ class GetRepoResponse: """Path of the Git folder (repo) in the workspace.""" provider: Optional[str] = None - """Git provider of the linked Git repository, e.g. `gitHub`, `azureDevOpsServices`, - `bitbucketServer` (Bitbucket Data Center), `gitLabEnterpriseEdition` (GitLab Self-Managed), or - `awsCodeCommit` (deprecated).""" + """Git provider of the linked Git repository, e.g. ``gitHub``, ``azureDevOpsServices``, + ``bitbucketServer`` (Bitbucket Data Center), ``gitLabEnterpriseEdition`` (GitLab Self-Managed), + or ``awsCodeCommit`` (deprecated).""" sparse_checkout: Optional[SparseCheckout] = None """Sparse checkout settings for the Git folder (repo).""" @@ -769,7 +769,7 @@ def from_dict(cls, d: Dict[str, Any]) -> ListCredentialsResponse: @dataclass class ListReposResponse: next_page_token: Optional[str] = None - """Token that can be specified as a query parameter to the `GET /repos` endpoint to retrieve the + """Token that can be specified as a query parameter to the ``GET /repos`` endpoint to retrieve the next page of results.""" repos: Optional[List[RepoInfo]] = None @@ -912,9 +912,12 @@ class ObjectInfo: object_type: Optional[ObjectType] = None """The type of the object in workspace. - - `NOTEBOOK`: document that contains runnable code, visualizations, and explanatory text. - - `DIRECTORY`: directory - `LIBRARY`: library - `FILE`: file - `REPO`: repository - `DASHBOARD`: - Lakeview dashboard""" + - ``NOTEBOOK``: document that contains runnable code, visualizations, and explanatory text. + - ``DIRECTORY``: directory + - ``LIBRARY``: library + - ``FILE``: file + - ``REPO``: repository + - ``DASHBOARD``: Lakeview dashboard""" path: Optional[str] = None """The absolute path of the object.""" @@ -1119,9 +1122,9 @@ class RepoInfo: """Root path of the git folder (repo) in the Workspace.""" provider: Optional[str] = None - """Git provider of the remote git repository, e.g. `gitHub`, `azureDevOpsServices`, - `bitbucketServer` (Bitbucket Data Center), `gitLabEnterpriseEdition` (GitLab Self-Managed), or - `awsCodeCommit` (deprecated).""" + """Git provider of the remote git repository, e.g. ``gitHub``, ``azureDevOpsServices``, + ``bitbucketServer`` (Bitbucket Data Center), ``gitLabEnterpriseEdition`` (GitLab Self-Managed), + or ``awsCodeCommit`` (deprecated).""" sparse_checkout: Optional[SparseCheckout] = None """Sparse checkout config for the git folder (repo).""" @@ -1397,9 +1400,8 @@ class SparseCheckout: """Sparse checkout configuration, it contains options like cone patterns.""" patterns: Optional[List[str]] = None - """List of sparse checkout cone patterns, see [cone mode handling] for details. - - [cone mode handling]: https://git-scm.com/docs/git-sparse-checkout#_internalscone_mode_handling""" + """List of sparse checkout cone patterns, see `cone mode handling + `__ for details.""" def as_dict(self) -> dict: """Serializes the SparseCheckout into a dictionary suitable for use as a JSON request body.""" @@ -1426,9 +1428,8 @@ class SparseCheckoutUpdate: """Sparse checkout configuration, it contains options like cone patterns.""" patterns: Optional[List[str]] = None - """List of sparse checkout cone patterns, see [cone mode handling] for details. - - [cone mode handling]: https://git-scm.com/docs/git-sparse-checkout#_internalscone_mode_handling""" + """List of sparse checkout cone patterns, see `cone mode handling + `__ for details.""" def as_dict(self) -> dict: """Serializes the SparseCheckoutUpdate into a dictionary suitable for use as a JSON request body.""" @@ -1720,9 +1721,7 @@ def from_dict(cls, d: Dict[str, Any]) -> WorkspaceObjectPermissionsDescription: 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 `__.""" def __init__(self, api_client): self._api = api_client @@ -1742,10 +1741,10 @@ def create( 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` (Azure DevOps Services, including Microsoft Entra - ID authentication), `gitHubEnterprise`, `bitbucketServer` (Bitbucket Data Center), - `gitLabEnterpriseEdition` (GitLab Self-Managed), and `awsCodeCommit` (deprecated by AWS, not + Git provider. This field is case-insensitive. The available Git providers are ``gitHub``, + ``bitbucketCloud``, ``gitLab``, ``azureDevOpsServices`` (Azure DevOps Services, including Microsoft + Entra ID authentication), ``gitHubEnterprise``, ``bitbucketServer`` (Bitbucket Data Center), + ``gitLabEnterpriseEdition`` (GitLab Self-Managed), and ``awsCodeCommit`` (deprecated by AWS, not accepting new customers). :param git_email: str (optional) The authenticating email associated with your Git provider user account. Used for authentication @@ -1763,9 +1762,8 @@ def create( the name of the git credential, used for identification and ease of lookup :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 + providers, support may exist for other types of scoped access tokens. `Learn more + `__. :param principal_id: int (optional) The ID of the service principal whose credentials will be modified. Only service principal managers can perform this action. @@ -1893,10 +1891,10 @@ def update( :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` (Azure DevOps Services, including Microsoft Entra - ID authentication), `gitHubEnterprise`, `bitbucketServer` (Bitbucket Data Center), - `gitLabEnterpriseEdition` (GitLab Self-Managed), and `awsCodeCommit` (deprecated by AWS, not + Git provider. This field is case-insensitive. The available Git providers are ``gitHub``, + ``bitbucketCloud``, ``gitLab``, ``azureDevOpsServices`` (Azure DevOps Services, including Microsoft + Entra ID authentication), ``gitHubEnterprise``, ``bitbucketServer`` (Bitbucket Data Center), + ``gitLabEnterpriseEdition`` (GitLab Self-Managed), and ``awsCodeCommit`` (deprecated by AWS, not accepting new customers). :param git_email: str (optional) The authenticating email associated with your Git provider user account. Used for authentication @@ -1914,9 +1912,8 @@ def update( the name of the git credential, used for identification and ease of lookup :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 + providers, support may exist for other types of scoped access tokens. `Learn more + `__. :param principal_id: int (optional) The ID of the service principal whose credentials will be modified. Only service principal managers can perform this action. @@ -1974,14 +1971,14 @@ def create( :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` (Azure DevOps Services, including Microsoft Entra - ID authentication), `gitHubEnterprise`, `bitbucketServer` (Bitbucket Data Center), - `gitLabEnterpriseEdition` (GitLab Self-Managed), and `awsCodeCommit` (deprecated by AWS, not + Git provider. This field is case-insensitive. The available Git providers are ``gitHub``, + ``bitbucketCloud``, ``gitLab``, ``azureDevOpsServices`` (Azure DevOps Services, including Microsoft + Entra ID authentication), ``gitHubEnterprise``, ``bitbucketServer`` (Bitbucket Data Center), + ``gitLabEnterpriseEdition`` (GitLab Self-Managed), and ``awsCodeCommit`` (deprecated by AWS, not accepting new customers). :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}`. + 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. @@ -2090,7 +2087,7 @@ def get_permissions(self, repo_id: str) -> RepoPermissions: return RepoPermissions.from_dict(res) def list(self, *, next_page_token: Optional[str] = None, path_prefix: Optional[str] = None) -> Iterator[RepoInfo]: - """Returns repos that the calling user has Manage permissions on. Use `next_page_token` to iterate + """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) @@ -2098,8 +2095,8 @@ def list(self, *, next_page_token: Optional[str] = None, path_prefix: Optional[s 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. + an effectively empty prefix (``/`` or ``/Workspace``) Git folders (repos) from ``/Workspace/Repos`` + will be served. :returns: Iterator over :class:`RepoInfo` """ @@ -2272,7 +2269,10 @@ def create_scope( .. code:: { "scope": "my-simple-databricks-scope", "initial_manage_principal": "users" "scope_backend_type": - "databricks|azure_keyvault", # below is only required if scope type is azure_keyvault + "databricks|azure_keyvault", + + **below is only required if scope type is azure_keyvault** + "backend_azure_keyvault": { "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/xxxx/providers/Microsoft.KeyVault/vaults/xxxx", "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dns_name": "https://xxxx.vault.azure.net/", } } @@ -2630,9 +2630,9 @@ def put_acl(self, scope: str, principal: str, permission: AclPermission): 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. + - ``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. @@ -2753,17 +2753,18 @@ def __init__(self, api_client): self._api = api_client def delete(self, path: str, *, recursive: Optional[bool] = None): - """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`. + """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 + 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. @@ -2789,25 +2790,28 @@ def delete(self, path: str, *, recursive: Optional[bool] = None): def export(self, path: str, *, format: Optional[ExportFormat] = None) -> 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 ``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`. + 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. + 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`. + 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. + - ``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` """ @@ -2886,8 +2890,8 @@ def get_permissions(self, workspace_object_type: str, workspace_object_id: str) return WorkspaceObjectPermissions.from_dict(res) def get_status(self, path: str) -> ObjectInfo: - """Gets the status of an object or a directory. If `path` does not exist, this call returns an error - `RESOURCE_DOES_NOT_EXIST`. + """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. @@ -2919,14 +2923,14 @@ def import_( overwrite: Optional[bool] = None, ): """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. Zip files within directories are not supported. + 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. Zip files within directories are not supported. :param path: str - The absolute path of the object or directory. Importing a directory is only supported for the `DBC` - and `SOURCE` formats. + 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. @@ -2937,17 +2941,19 @@ def import_( 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. + - ``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`. + 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. + 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. """ @@ -2976,7 +2982,7 @@ def import_( def list(self, path: str, *, notebooks_modified_after: Optional[int] = None) -> Iterator[ObjectInfo]: """Lists the contents of a directory, or the object if it is not a directory. If the input path does not - exist, this call returns an error `RESOURCE_DOES_NOT_EXIST`. + exist, this call returns an error ``RESOURCE_DOES_NOT_EXIST``. :param path: str The absolute path of the notebook or directory. @@ -3006,7 +3012,7 @@ def list(self, path: str, *, notebooks_modified_after: Optional[int] = None) -> def mkdirs(self, path: str): """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`. + ``RESOURCE_ALREADY_EXISTS``. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories.