Isthmus To/From SQL examples & enhanced APIs

[mbwhite]

Starting from two examples of using Isthmus to go from and to SQL a few new methods make the process a lot simpler and symetrical.

We found that in use we needed helper wrapper clases, but these could be pushed into the main code.

Note to reviewers

I'll leave as draft until I'm sure the build is good and tests are fully working.

I did create a separate examples project; however it does feel a bit unwieldy to have this and the spark one. Maybe some rework to make a general examples project with sub directories per example 'category'... Happy to make that change if you wish.

[nielspardon]

I did create a separate examples project; however it does feel a bit unwieldy to have this and the spark one. Maybe some rework to make a general examples project with sub directories per example 'category'... Happy to make that change if you wish.

I think it's fine having multiple example subprojects that each show how to use each of the 3 modules provided by substrait-java: Core, Isthmus, Spark. It would also show which dependency declarations / Gradle setup one needs to interact with each of the modules. If all of them were in a single examples project then it might be difficult to parse the Gradle setup and understand which dependencies / configuration is needed by which module.

[benbellick]

There were some parts I didn't quite get around to reading, but just dumping some comments I have for now. Thank you for doing this! I think it will be a great help :)

Most of my comments are about code comments / the readme. Feel free to ignore whatever if you think my suggestions are less clear. Thanks!

[mbwhite]

Thanks @benbellick - changes made. I've used the batch accepted feature - so hopefully I've not missed any comment - as I agreed with the updates.

[bestbeforetoday]

This is a really helpful sample that makes it much easier for end users to get to grips with using substrait-java (and Isthmus) programmatically.

There is a very minor code fix required to SubstraitSqlStatementParser, and there is now a merge conflict with a recent code change. I have rebased this change and resolved both of these issues in my pr/625 branch if it is easier to pick that up rather than make the changes yourself.

Additionally there are a couple of minor Javadoc fixes needed, and some small suggestions described with inline comments.

[bestbeforetoday]

The parserConfig parameter is not used. It should replace PARSER_CONFIG below.

[bestbeforetoday]

Javadoc is missing the sqlDialect parameter.

[bestbeforetoday]

Javadoc is missing the sqlDialect parameter.

[bestbeforetoday]

Just a suggestion; your call on whether you want to change this at all...

I am not sure there is any value in collecting the SQL strings into a list and then printing them rather than just printing them directly.

Either way, you might (or might not) find it more readable using streams.

Suggested change

	final List<String> sqlStrings = new ArrayList<>();
	System.out.println("\n");
	// and get each root from the Substrait plan
	for (final Root root : substraitPlan.getRoots()) {
	// Substrait -> Calcite
	final RelNode calciteRelNode = converter.convert(root).project(true);
	// Calcite -> SQL
	final SqlNode sqlNode = relToSql.visitRoot(calciteRelNode).asStatement();
	final String sqlString = sqlNode.toSqlString(sqlDialect).getSql();
	sqlStrings.add(sqlString);
	}
	sqlStrings.forEach(System.out::println);
	System.out.println("\n");
	// Convert each of the Ssubstrait plan roots to SQL
	substraitPlan.getRoots().stream()
	// Substrait -> Calcite Rel
	.map(root -> converter.convert(root).project(true))
	// Calcite Rel -> Calcite SQL
	.map(calciteRelNode -> relToSql.visitRoot(calciteRelNode).asStatement())
	// Calcite SQL -> SQL String
	.map(sqlNode -> sqlNode.toSqlString(sqlDialect).getSql())
	.forEachOrdered(System.out::println);

[bestbeforetoday]

I suggest splitting the command and sample output into separate code blocks so only the command can be more easily copied.

Suggested change

	To run [`FromSql.java`](./src/main/java/io/substrait/examples/FromSql.java), execute the command below from the root of this repository. The example writes a binary plan to `substrait.plan` and outputs the text format of the protobuf to stdout. The output is quite lengthy, so it has been abbreviated here.
	```bash
	./gradlew examples:isthmus-api:run --args "FromSql substrait.plan"
	To run [`FromSql.java`](./src/main/java/io/substrait/examples/FromSql.java), execute the command below from the root of this repository.
	```bash
	./gradlew examples:isthmus-api:run --args "FromSql substrait.plan"
	```
	The example writes a binary plan to `substrait.plan` and outputs the text format of the protobuf to stdout. The output is quite lengthy, so it has been abbreviated here.
	```

[bestbeforetoday]

I suggest splitting the command and sample output into separate code blocks so only the command can be more easily copied.

Suggested change

	To run [`ToSql.java`](./src/main/java/io/substrait/examples/ToSql.java), execute the command below from the root of this repository. The example reads from `substrait.plan` (likely the file created by `FromSql`) and outputs SQL. The text format of the protobuf has been abbreviated.
	```bash
	./gradlew examples:isthmus-api:run --args "ToSql substrait.plan"
	To run [`ToSql.java`](./src/main/java/io/substrait/examples/ToSql.java), execute the command below from the root of this repository.
	```bash
	./gradlew examples:isthmus-api:run --args "ToSql substrait.plan"
	```
	The example reads from `substrait.plan` (likely the file created by `FromSql`) and outputs SQL. The text format of the protobuf has been abbreviated.
	```