Github user harshach commented on a diff in the pull request:
https://github.com/apache/storm/pull/914#discussion_r46582960
--- Diff: external/sql/README.md ---
@@ -0,0 +1,98 @@
+# Storm SQL
+
+Compile SQL queries to Storm topologies.
+
+## Usage
+
+Run the ``storm sql`` command to compile SQL statements into Trident
topology, and submit it to the Storm cluster
+
+```
+$ bin/storm sql <topo-name> <sql-file>
+```
+
+In which `topo-name` is the name of the topology, and `sql-file` contains
a list of SQL statements to be executed.
+
+## Supported Features
+
+The following features are supported in the current repository:
+
+* Streaming from and to external data sources
+* Filtering tuples
+* Projections
+
+Aggregation, windowing and joining tables are yet to be implemented.
Specifying parallelism hints is not yet supported.
+
+## Specifying External Data Sources
+
+In StormSQL data is represented by external tables. Users can specify data
sources using the `CREATE EXTERNAL TABLE` statement. For example, the following
statement specifies a Kafka spouts and sink:
+
+```
+CREATE EXTERNAL TABLE FOO (ID INT PRIMARY KEY) LOCATION
'kafka://localhost:2181/brokers?topic=test' TBLPROPERTIES
'{"producer":{"bootstrap.servers":"localhost:9092","acks":"1","key.serializer":"storm.kafka.IntSerializer","value.serializer":"storm.kafka.ByteBufferSerializer"}}'
+```
+
+The syntax of `CREATE EXTERNAL TABLE` closely follows the one defined in
[Hive Data Definition
Language](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL).
+
+## Plugging in External Data Sources
+
+Users plug in external data sources through implementing the
`ISqlTridentDataSource` interface and registers them using the mechanisms of
Java's service loader. The external data source will be chosen based on the
scheme of the URI of the tables. Please refer to the implementation of
`storm-sql-kafka` for more details.
+
+It is also important to note that users also need to provide the
dependency of the external data sources in the `extlib` directory. Otherwise
the topology will fail to run because of `ClassNotFoundException`.
--- End diff --
can you highlight this part as a limitation section and file relevant JIRAs
and include them in the README as well.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
