[GitHub] fhueske commented on a change in pull request #6456: [FLINK-9947] [docs] Document unified table sources/sinks/formats

[GitBox <gi...@apache.org>]

fhueske commented on a change in pull request #6456: [FLINK-9947] [docs] Document unified table sources/sinks/formats
URL: https://github.com/apache/flink/pull/6456#discussion_r207140754
 
 

 ##########
 File path: docs/dev/table/connect.md
 ##########
 @@ -67,14 +67,24 @@ This table is only available for stable releases.
 Overview
 --------
 
-Beginning from Flink 1.6, the declaration of a connection to an external system is separated from the actual implementation. Connections can be specified either
+Beginning from Flink 1.6, the declaration of a connection to an external system is separated from the actual implementation.
+
+Connections can be specified either
 
 - **programmatically** using a `Descriptor` under `org.apache.flink.table.descriptors` for Table & SQL API
 - or **declaratively** via [YAML configuration files](http://yaml.org/) for the SQL Client.
 
-This allows not only for better unification of APIs and SQL Client but also for better extensibility in case of [custom implementations](sourceSinks.html) without changing the declaration.
+This allows not only for better unification of APIs and SQL Client but also for better extensibility in case of [custom implementations](sourceSinks.html) without changing the actual declaration.
+
+Every declaration is similar to a SQL `CREATE TABLE` statement. One can define the name of the table, the final schema of the table, a connector, and a data format upfront for connecting to an external system.
+
+The **connector** describes the external system that should be used as a source and/or target of data. Storage systems such as [Apacha Kafka](http://kafka.apache.org/) or a regular file system can be declared here. The connector might already provide a fixed format with fields and schema.
+
+Some systems support different **data formats**. For example, one can encode the rows of a table in CSV, JSON, or Avro representation before writing them into a file. A database connector might need the table schema here. Whether or not a storage system requires the definition of a format, is documented for every [connector](connect.html#table-connectors). Different systems also require different [types of formats](connect.html#table-formats) (e.g., column-oriented formats vs. row-oriented formats). The documentation states which format types and connectors are compatible.
 
 Review comment:
   `For example, a table that is stored in Kafka or in files can encode its rows with CSV, JSON, or Avro.`

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services