jorisvandenbossche commented on a change in pull request #11985:
URL: https://github.com/apache/arrow/pull/11985#discussion_r780991165
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,52 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+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.
+
+Custom metadata can be accessed at ``Schema.metadata`` for the schema-level
+and ``Field.metadata`` for the field-level.
+
+Note that this metadata is preserved in :ref:`ipc` processes.
+
+To customize the schema metadata of the existing table you can use
Review comment:
```suggestion
To customize the schema metadata of an existing table you can use
```
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,52 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+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.
+
+Custom metadata can be accessed at ``Schema.metadata`` for the schema-level
+and ``Field.metadata`` for the field-level.
Review comment:
```suggestion
Custom metadata can be accessed at :attr:`Schema.metadata` for the
schema-level
and :attr:`Field.metadata` for the field-level.
```
Then it will link to the API docs (although I see that those don't have a
docstring at the moment, so that makes this is not yet a very useful link)
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,52 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+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.
+
+Custom metadata can be accessed at ``Schema.metadata`` for the schema-level
+and ``Field.metadata`` for the field-level.
+
+Note that this metadata is preserved in :ref:`ipc` processes.
+
+To customize the schema metadata of the existing table you can use
+:meth:`Table.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
+:meth:`Field.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 the
+Schema which is immutable. To change the metadata in the schema of the table
+we created a new object when calling :meth:`Table.replace_schema_metadata`.
+
+To change the metadata of the field in the schema we would need to define
+a new schema and cast it to the data available:
+
+.. ipython:: python
+
+ my_schema2 = pa.schema([
+ pa.field('f0', pa.int64(), metadata={"f0": "First dose"}),
+ pa.field('f1', pa.string(), metadata={"f1": "Second dose"}),
Review comment:
```suggestion
pa.field('f0', pa.int64(), metadata={"name": "First dose"}),
pa.field('f1', pa.string(), metadata={"name": "Second dose"}),
```
I was thinking it is maybe good to show an example where the key is not the
same as the name of the field (to not give the suggestion to the reader this
might be needed). But can of course also be anything else as "name".
##########
File path: docs/source/python/data.rst
##########
@@ -431,4 +431,52 @@ around, so if your data is already in table form, then use
Custom Schema and Field Metadata
--------------------------------
-TODO
+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.
+
+Custom metadata can be accessed at ``Schema.metadata`` for the schema-level
+and ``Field.metadata`` for the field-level.
+
+Note that this metadata is preserved in :ref:`ipc` processes.
+
+To customize the schema metadata of the existing table you can use
+:meth:`Table.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
+:meth:`Field.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 the
+Schema which is immutable. To change the metadata in the schema of the table
+we created a new object when calling :meth:`Table.replace_schema_metadata`.
+
+To change the metadata of the field in the schema we would need to define
+a new schema and cast it to the data available:
Review comment:
```suggestion
a new schema and cast the data to this schema:
```
--
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]
