CreateTable, TableService and TableRepository

Author: jaceklaskowski

docs/persistent-storage/TableRepository.md

@@ -1 +1,30 @@
 # TableRepository
+
+## Persist Table Metadata { #createTable }
+
+```java
+TableInfo createTable(
+  CreateTable createTable)
+```
+
+`createTable` creates a `TableInfo` with randomly-generated UUID as the table ID and the other metadata.
+
+`createTable` prints out the following DEBUG message to the logs:
+
+```text
+Creating table: [fullName]
+```
+
+!!! danger "`MANAGED` tables are not supported yet"
+
+`createTable` asserts that `storage_location` is specified for an [EXTERNAL](../server/CreateTable.md#EXTERNAL) table.
+
+`createTable` persists the table's [properties](../server/CreateTable.md#properties) (to `uc_properties` table using `PropertyDAO`).
+
+In the end, `createTable` persists the [table metadata](../server/CreateTable.md).
+
+---
+
+`createTable` is used when:
+
+* `TableService` is requested to [create a table metadata](../server/TableService.md#createTable)

docs/server/CreateTable.md

@@ -1 +1,22 @@
 # CreateTable
+
+`CreateTable` represents a request to create a new table instance (coming from [TableCli](../cli/TableCli.md#createTable)).
+
+`CreateTable` is `POST`ed to `/tables` API endpoint of the [TableService](TableService.md#createTable) (to persist using [TableRepository](../persistent-storage/TableRepository.md#createTable)).
+
+Property | Required | Description
+-|-|-
+ `catalog_name` | ✅ | Name of parent catalog
+ `columns` | ✅ | An array of `ColumnInfo`s of the table's columns
+ `comment` | | User-provided free-form text description
+ `data_source_format` | ✅ | Data source format:<ul><li>`DELTA`<li>`CSV`<li>`JSON`<li>`AVRO`<li>`PARQUET`<li>`ORC`<li>`TEXT`</ul>
+ `name` | ✅ | Name of table, relative to parent schema.
+ `properties` | ✅ | Name of table, relative to parent schema.
+ `schema_name` | ✅ | Name of parent schema relative to its parent catalog
+ `storage_location` | | Storage root URL<br>⛔️ Required for `EXTERNAL` tables
+ `table_type` | ✅ | One of the following:<ul><li>`MANAGED` ([not supported by the Localhost Reference Server](../persistent-storage/TableRepository.md#createTable))<li>`EXTERNAL`</ul>
+
+??? note "OpenAPI Generator"
+    `CreateTable` was auto-generated using [OpenAPI Generator]({{ openapi.home }}) based on Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
+    [sbt-openapi-generator]({{ openapi.github }}/sbt-openapi-generator) 7.5.0 is used in the `client` sbt module of the `unitycatalog` project.

docs/server/TableService.md

@@ -4,14 +4,23 @@
 
 Method | URL | Handler | Params
 -|-|-|-
- GET | `/tables` | [listTables](#listTables) | <ul><li>catalog_name</li><li>schema_name</li><li>max_results</li><li>page_token</li><li>omit_properties</li><li>omit_columns</ul>
+ GET | `/tables` | [listTables](#listTables) | <ul><li>catalog_name<li>schema_name<li>max_results<li>page_token<li>omit_properties<li>omit_columns</ul>
  POST | `/tables` | [createTable](#createTable) | JSON-ified [CreateTable](CreateTable.md)
- GET | `/tables/{full_name}` | [getTable](#getTable) | <ul><li>fullName</li></ul>
- DELETE | `/tables/{full_name}` | [deleteTable](#deleteTable) | <ul><li>fullName</li></ul>
+ GET | `/tables/{full_name}` | [getTable](#getTable) | <ul><li>fullName</ul>
+ DELETE | `/tables/{full_name}` | [deleteTable](#deleteTable) | <ul><li>fullName</ul>
 
 ```console
 $ http http://localhost:8081/api/2.1/unity-catalog/tables catalog_name==unity schema_name==default | jq '.tables[].name'
 "numbers"
 "marksheet_uniform"
 "marksheet"
 ```
+
+## Creating Table Metadata { #createTable }
+
+```java
+HttpResponse createTable(
+  CreateTable createTable)
+```
+
+`createTable` requests the system-wide [TableRepository](#TABLE_REPOSITORY) instance to [persist](../persistent-storage/TableRepository.md#createTable) the given [table metadata](CreateTable.md).