diff --git a/mkdocs/docs/api.md b/mkdocs/docs/api.md index 4c1e0f58ce..f86048cd9c 100644 --- a/mkdocs/docs/api.md +++ b/mkdocs/docs/api.md @@ -1529,15 +1529,72 @@ cleanup_old_snapshots("analytics.user_events", [12345, 67890, 11111]) ## Views -PyIceberg supports view operations. +If the REST server does not indicate support for view endpoints, you can enable it by setting `"view-endpoints-supported": "true"`: -### Check if a view exists +```python +from pyiceberg.catalog import load_catalog + +catalog = load_catalog( + "docs", + **{ + "uri": "http://127.0.0.1:8181", + "s3.endpoint": "http://127.0.0.1:9000", + "py-io-impl": "pyiceberg.io.pyarrow.PyArrowFileIO", + "s3.access-key-id": "admin", + "s3.secret-access-key": "password", + "view-endpoints-supported": "true", + } +) +``` + +## Create a view + +To create a view from the catalog: ```python +import time from pyiceberg.catalog import load_catalog +from pyiceberg.schema import Schema +from pyiceberg.types import IntegerType, NestedField +from pyiceberg.view import SQLViewRepresentation, ViewVersion catalog = load_catalog("default") -catalog.view_exists("default.bar") + +schema = Schema(NestedField(field_id=1, name="some_col", field_type=IntegerType(), required=False)) +view_version = ViewVersion( + version_id=1, + schema_id=1, + timestamp_ms=int(time.time() * 1000), + summary={"spark-version": "4.1"}, + representations=[ + SQLViewRepresentation( + type="sql", + sql="SELECT 1 as some_col", + dialect="spark", + ) + ], + default_namespace=["default"], +) + +catalog.create_view( + identifier="default.some_view", + schema=schema, + view_version=view_version, +) +``` + +`catalog.create_view` also accepts a PyArrow schema, so the following is equivalent: + +```python +import pyarrow as pa + +schema = pa.schema([pa.field("some_col", pa.int32())]) + +catalog.create_view( + identifier="default.some_view", + schema=schema, + view_version=view_version, +) ``` ## Register a view @@ -1551,6 +1608,48 @@ catalog.register_view( ) ``` +## Load a view + +Loading the `some_view` view: + +```python +view = catalog.load_view("default.some_view") +# Equivalent to: +view = catalog.load_view(("default", "some_view")) +# The tuple syntax can be used if the namespace or view contains a dot. +``` + +This returns a `View` that represents an Iceberg view. You can access the SQL representation for a specific dialect: + +```python +sql_representation = view.sql_for("spark") +print(sql_representation.sql) +``` + +## Check if a view exists + +To check whether the `some_view` view exists: + +```python +catalog.view_exists("default.some_view") +``` + +## List views + +To list views in the `default` namespace: + +```python +catalog.list_views("default") +``` + +## Drop a view + +To drop a view: + +```python +catalog.drop_view("default.some_view") +``` + ## Table Statistics Management Manage table statistics with operations through the `Table` API: diff --git a/mkdocs/docs/configuration.md b/mkdocs/docs/configuration.md index 3f82f78895..dcf9e4581e 100644 --- a/mkdocs/docs/configuration.md +++ b/mkdocs/docs/configuration.md @@ -347,6 +347,7 @@ catalog: | warehouse | myWarehouse | Warehouse location or identifier to request from the catalog service. May be used to determine server-side overrides, such as the warehouse location. | | snapshot-loading-mode | refs | The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags. | | `header.X-Iceberg-Access-Delegation` | `vended-credentials` | Signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms. When using `vended-credentials`, the server provides temporary credentials to the client. When using `remote-signing`, the server signs requests on behalf of the client. (default: `vended-credentials`) | +| view-endpoints-supported | false | For backwards compatibility with older REST servers. Set to `true` if the server supports view endpoints but doesn't send the `endpoints` field in the ConfigResponse. | #### Headers in REST Catalog