davisusanibar commented on a change in pull request #12634:
URL: https://github.com/apache/arrow/pull/12634#discussion_r827478534
##########
File path: docs/source/java/vector_schema_root.rst
##########
@@ -15,21 +15,80 @@
.. specific language governing permissions and limitations
.. under the License.
-================
+.. default-domain:: java
+.. highlight:: java
+
+============
+Tabular Data
+============
+
+While arrays (aka: :doc:`ValueVector <./vector>`) represent a one-dimensional
sequence of
+homogeneous values, data often comes in the form of two-dimensional sets of
+heterogeneous data (such as database tables, CSV files...). Arrow provides
+several abstractions to handle such data conveniently and efficiently.
+
+Fields
+======
+
+Fields are used to denote the particular columns of a table.
+A field, i.e. an instance of `Field`_, holds together a field name, a data
+type and some optional metadata
+
+.. code-block:: Java
+
+ // Create a column A with utf8 string column and metadata
+ import org.apache.arrow.vector.types.pojo.ArrowType;
+ import org.apache.arrow.vector.types.pojo.Field;
+ import org.apache.arrow.vector.types.pojo.FieldType;
+
+ Map<String, String> metadata = new HashMap<>();
+ metadata.put("A", "Id card");
+ metadata.put("B", "Passport");
+ metadata.put("C", "Visa");
+ Field document = new Field("document", new FieldType(true, new
ArrowType.Utf8(), /*dictionary*/ null, metadata), /*children*/ null);
+
+Schemas
+=======
+
+A `Schema`_ describes the overall structure of a two-dimensional dataset such
+as a table. It holds a sequence of fields together with some optional
+schema-wide metadata (in addition to per-field metadata).
+
+.. code-block:: Java
+
+ // Create a schema describing datasets with two columns:
+ // a int32 column "A" and a utf8-encoded string column "B"
+ import org.apache.arrow.vector.types.pojo.ArrowType;
+ import org.apache.arrow.vector.types.pojo.Field;
+ import org.apache.arrow.vector.types.pojo.FieldType;
+ import org.apache.arrow.vector.types.pojo.Schema;
+
+ Map<String, String> metadata = new HashMap<>();
+ metadata.put("K1", "V1");
+ metadata.put("K2", "V2");
+ Field a = new Field("A", FieldType.nullable(new ArrowType.Int(32, true)),
null);
+ Field b = new Field("B", FieldType.nullable(new ArrowType.Utf8()), null);
+ Schema schema = new Schema(java.util.Arrays.asList(a, b), metadata);
+
+Tables
+======
+
+There is not a object or implementation of Table on java side. More close
definition
+like a table could be VectorSchemaRoot (see the next section).
Review comment:
Deleted and added as a note on VectorSchemRoot
--
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]
