Document SQL Support for the Iceberg connector

[findinpath]

Description

Document SQL support of the Iceberg connector.

Is this change a fix, improvement, new feature, refactoring, or other?

N/A

Is this a change to the core query engine, a connector, client library, or the SPI interfaces? (be specific)

N/A

How would you describe this change to a non-technical end user or system administrator?

Document SQL support of the Iceberg connector.

Related issues, pull requests, and links

Documentation

( ) No documentation is needed.
(x) Sufficient documentation is included in this PR.
( ) Documentation PR is available with #prnumber.
( ) Documentation issue #issuenumber is filed, and can be handled later.

Release notes

(x) No release notes entries required.
( ) Release notes entries required with the following suggested text:

[mosabua]

I will review again once initial comment is addressed.

[mosabua]

This is correct ..

[mosabua]

Change to

Hive metastore service (HMS)

or just

Hive metastore

[findinpath]

This is about the Iceberg catalog implementation which is backed by HMS. In this case I tend to think that the name is suitable. NO

[mosabua]

Sure .. but in the context of Trino its confusing to use catalog for two different concepts .. not sure how to get around this better

[mosabua]

A couple of changes .. some of the examples seem to just repeat the docs on how a specific SQL statement works but I guess thats fine..

[mosabua]

could also just do

on tables, views, and columns with the COMMENT statement.

but .. also ALTER x ADD COMMENT and such works too right?

[findinpath]

ALTER x ADD COMMENT I'm not aware of this syntax. I haven't seen also any occurrence of "ADD COMMENT" in the codebase.

[mosabua]

Sorry for not being clear .. I meant this stuff for example

ALTER TABLE [ IF EXISTS ] name ADD COLUMN [ IF NOT EXISTS ] column_name data_type
[ NOT NULL ] [ COMMENT comment ]

But also setting comments when using create

CREATE TABLE [ IF NOT EXISTS ]
table_name (
{ column_name data_type [ NOT NULL ]
[ COMMENT comment ]
[ WITH ( property_name = expression [, ...] ) ]
| LIKE existing_table_name
[ { INCLUDING | EXCLUDING } PROPERTIES ]
}
[, ...]
)
[ COMMENT table_comment ]

In that case .. table and column comments..

[mosabua]

We should verify and document that they all work for tables and views.. also what about materialized views?

[findinpath]

I added corresponding mentions for both CREATE TABLE , ALTER TABLE. Thanks for the suggestion.

Setting comments on MV is not supported.

[mosabua]

Not sure if we need all this, but lets leave it since you already have it.

[findinpath]

@mosabua CPTAL at the updated PR?

[mosabua]

Lets ship this. Nice work

[ebyhr]

A trailing slash caused a regression in the past versions. Let's avoid using it in the example.

[findinpath]

trino> CREATE SCHEMA iceberg.tiny WITH (location='s3a://tiny');
Query 20221007_094114_00002_ct5a7 failed: java.lang.IllegalArgumentException: Can not create a Path from an empty string
io.trino.spi.TrinoException: java.lang.IllegalArgumentException: Can not create a Path from an empty string
	at io.trino.plugin.hive.metastore.thrift.ThriftHiveMetastore.createDatabase(ThriftHiveMetastore.java:963)
	at io.trino.plugin.hive.metastore.thrift.BridgingHiveMetastore.createDatabase(BridgingHiveMetastore.java:160)
	at io.trino.plugin.hive.metastore.cache.CachingHiveMetastore.createDatabase(CachingHiveMetastore.java:450)
	at io.trino.plugin.iceberg.catalog.hms.TrinoHiveCatalog.createNamespace(TrinoHiveCatalog.java:184)
	at io.trino.plugin.iceberg.IcebergMetadata.createSchema(IcebergMetadata.java:609)
	at io.trino.plugin.base.classloader.ClassLoaderSafeConnectorMetadata.createSchema(ClassLoaderSafeConnectorMetadata.java:350)
	at io.trino.metadata.MetadataManager.createSchema(MetadataManager.java:592)
...

I've tried on Trino & Hive & MinIO this functionality without a trailing / and stumbled on the previously exposed issue.

[findinpath]

trino> create table iceberg.tiny.test1 (x integer) with (location='s3a://tiny/test1');
CREATE TABLE
trino> create table iceberg.tiny.test2 (x integer) with (location='s3a://tiny/test2/');
CREATE TABLE

On the table however, I see that creating a table is possible with and without trailing slash.
Probably the above mentioned situation is a bug.

[ebyhr]

Generated page has repeated "Schema and table management". By the way, why do we want both sql-schema-table-management & iceberg-schema-table-management?

[findinpath]

We don't need both. Actually having the links on the same line is misleading.
The iceberg-schema-table-management has anyway a link towards sql-schema-table-management so taking out the sql-schema-table-management link from this listing probably ok.

[ebyhr]

nit: Type names are lowercase here, but the following DDL for NOT NULL example uses uppercase. Follow-up PR is fine.

[ebyhr]

Merged, thanks!