You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2021/12/23 13:33:08 UTC
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11985: ARROW-12545: [Python][Docs] Fill in section about Custom Schema and Field Metadata
jorisvandenbossche commented on a change in pull request #11985:
URL: https://github.com/apache/arrow/pull/11985#discussion_r774571276
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
+be added with the use of ``replace_schema_metadata`` or ``with_metadata``.
+
+To customize the metadata of the existing table you can use
+``replace_schema_metadata``:
+
+.. ipython:: python
+
+ table.schema.metadata # empty
+ table = table.replace_schema_metadata({"f0": "First dose"})
+ table.schema.metadata
+
+To customize the metadata of the field from the table schema you can use
+``with_metadata``:
Review comment:
```suggestion
:meth:`Field.with_metadata`:
```
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
+be added with the use of ``replace_schema_metadata`` or ``with_metadata``.
+
+To customize the metadata of the existing table you can use
Review comment:
```suggestion
To customize the schema metadata of the existing table you can use
```
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
+be added with the use of ``replace_schema_metadata`` or ``with_metadata``.
+
+To customize the metadata of the existing table you can use
+``replace_schema_metadata``:
+
+.. ipython:: python
+
+ table.schema.metadata # empty
+ table = table.replace_schema_metadata({"f0": "First dose"})
+ table.schema.metadata
+
+To customize the metadata of the field from the table schema you can use
+``with_metadata``:
+
+.. ipython:: python
+
+ field_f1 = table.schema.field("f1")
+ field_f1.metadata # empty
+ field_f1 = field_f1.with_metadata({"f1": "Second dose"})
+ field_f1.metadata
+
+Both options create a shallow copy of the data and do not in fact change
+Schema which is immutable. To change the metadata in the schema of the table we
Review comment:
```suggestion
Both options create a shallow copy of the data and do not in fact change the
Schema which is immutable. To change the metadata in the schema of the table we
```
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
Review comment:
Maybe we can start here with a very short explanation that Arrow supports custom metadata at the schema and field level (can maybe reuse the wording from https://github.com/apache/arrow/blob/master/docs/source/format/Columnar.rst#custom-application-metadata). Something like:
> Arrow supports both schema-level and field-level custom key-value metadata allowing for systems to insert their own application defined metadata to customize behavior.
And mention this is preserved in IPC serialization or so. And then we can explain that this can be accessed at `Schema.metadata` and `Field.metadata`.
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
+be added with the use of ``replace_schema_metadata`` or ``with_metadata``.
+
+To customize the metadata of the existing table you can use
+``replace_schema_metadata``:
Review comment:
```suggestion
:meth:`Table.replace_schema_metadata`:
```
(then it will link to the API docs)
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,44 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+The metadata used for describing the data in the schema or a field can also
+be added with the use of ``replace_schema_metadata`` or ``with_metadata``.
+
+To customize the metadata of the existing table you can use
+``replace_schema_metadata``:
+
+.. ipython:: python
+
+ table.schema.metadata # empty
+ table = table.replace_schema_metadata({"f0": "First dose"})
+ table.schema.metadata
+
+To customize the metadata of the field from the table schema you can use
+``with_metadata``:
+
+.. ipython:: python
+
+ field_f1 = table.schema.field("f1")
+ field_f1.metadata # empty
+ field_f1 = field_f1.with_metadata({"f1": "Second dose"})
+ field_f1.metadata
+
+Both options create a shallow copy of the data and do not in fact change
+Schema which is immutable. To change the metadata in the schema of the table we
Review comment:
The `To change the metadata in the schema of the table we created a new object`, does this refer to the `replace_schema_metadata` example above?
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org