jayceslesar commented on code in PR #2139:
URL: https://github.com/apache/iceberg-python/pull/2139#discussion_r2173506656


##########
mkdocs/docs/api.md:
##########
@@ -47,13 +47,11 @@ catalog:
     warehouse: my-warehouse
 ```
 
-and loaded in python by calling `load_catalog(name="hive")` and 
`load_catalog(name="rest")`.
+The different catalog can be loaded in PyIceberg by their name: 
`load_catalog(name="hive")` and `load_catalog(name="rest")`. An overview of the 
configurations options can be found on the [configuration 
page](https://py.iceberg.apache.org/configuration/).

Review Comment:
   ```suggestion
   The different catalogs can be loaded in PyIceberg by their name: 
`load_catalog(name="hive")` and `load_catalog(name="rest")`. An overview of the 
configuration options can be found on the [configuration 
page](https://py.iceberg.apache.org/configuration/).
   ```



##########
mkdocs/docs/api.md:
##########
@@ -24,7 +24,7 @@ hide:
 
 # Python API
 
-PyIceberg is based around catalogs to load tables. First step is to 
instantiate a catalog that loads tables. Let's use the following configuration 
to define a catalog called `prod`:
+(Py)Iceberg is [catalog](https://iceberg.apache.org/terms/#catalog) centric. 
Meaning that reading/writing data goes via a catalog. First step is to 
instantiate a catalog to load a tables. Let's use the following configuration 
in `.pyiceberg.yaml` to define a REST catalog called `prod`:

Review Comment:
   ```suggestion
   (Py)Iceberg is [catalog](https://iceberg.apache.org/terms/#catalog) centric. 
Meaning that reading/writing data goes via a catalog. First step is to 
instantiate a catalog to load a table. Let's use the following configuration in 
`.pyiceberg.yaml` to define a REST catalog called `prod`:
   ```



##########
mkdocs/docs/api.md:
##########
@@ -253,31 +233,22 @@ df = pa.Table.from_pylist(
 )
 ```
 
-Next, create a table based on the schema:
+Next, create a table using the Arrow schema:
 
 ```python
 from pyiceberg.catalog import load_catalog
 
 catalog = load_catalog("default")
 
-from pyiceberg.schema import Schema
-from pyiceberg.types import NestedField, StringType, DoubleType
-
-schema = Schema(
-    NestedField(1, "city", StringType(), required=False),
-    NestedField(2, "lat", DoubleType(), required=False),
-    NestedField(3, "long", DoubleType(), required=False),
-)
-
-tbl = catalog.create_table("default.cities", schema=schema)
+tbl = catalog.create_table("default.cities", schema=df.schema)
 ```
 
-Now write the data to the table:
+Next, write the data to the table. Both `append` and `overwrite` produce the 
same result, since the table is empty on creation:
 
 <!-- prettier-ignore-start -->
 
 !!! note inline end "Fast append"
-    PyIceberg default to the [fast 
append](https://iceberg.apache.org/spec/#snapshots) to minimize the amount of 
data written. This enables quick writes, reducing the possibility of conflicts. 
The downside of the fast append is that it creates more metadata than a normal 
commit. [Compaction is 
planned](https://github.com/apache/iceberg-python/issues/270) and will 
automatically rewrite all the metadata when a threshold is hit, to maintain 
performant reads.
+    PyIceberg default to the [fast 
append](https://iceberg.apache.org/spec/#snapshots) to minimize the amount of 
data written. This enables fast commit operations, reducing the possibility of 
conflicts. The downside of the fast append is that it creates more metadata 
than a merge commit. [Compaction is 
planned](https://github.com/apache/iceberg-python/issues/270) and will 
automatically rewrite all the metadata when a threshold is hit, to maintain 
performant reads.

Review Comment:
   ```suggestion
       PyIceberg defaults to the [fast 
append](https://iceberg.apache.org/spec/#snapshots) to minimize the amount of 
data written. This enables fast commit operations, reducing the possibility of 
conflicts. The downside of the fast append is that it creates more metadata 
than a merge commit. [Compaction is 
planned](https://github.com/apache/iceberg-python/issues/270) and will 
automatically rewrite all the metadata when a threshold is hit, to maintain 
performant reads.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to