CREATE NAMESPACE command and SupportsNamespaces

Author: jaceklaskowski

docs/connector/catalog/SupportsNamespaces.md

@@ -4,7 +4,22 @@
 
 ## Contract (Subset)
 
-### listNamespaces { #listNamespaces }
+### Create Namespace { #createNamespace }
+
+```java
+void createNamespace(
+  String[] namespace,
+  Map<String, String> metadata)
+```
+
+Creates a multi-part namespace in this catalog
+
+Used when:
+
+* `DelegatingCatalogExtension` is requested to [createNamespace](DelegatingCatalogExtension.md#createNamespace)
+* `CREATE NAMESPACE` command is executed
+
+### List Namespaces { #listNamespaces }
 
 ```java
 String[][] listNamespaces()
@@ -17,7 +32,7 @@ Used when:
 * `DelegatingCatalogExtension` is requested to [listNamespaces](DelegatingCatalogExtension.md#listNamespaces)
 * `SHOW NAMESPACES` command is executed
 
-### loadNamespaceMetadata { #loadNamespaceMetadata }
+### Load Namespace Metadata { #loadNamespaceMetadata }
 
 ```java
 Map<String, String> loadNamespaceMetadata(
@@ -33,6 +48,23 @@ Used when:
 * `DESCRIBE NAMESPACE` command is executed
 * `CatalogImpl` is requested to [getNamespace](../../CatalogImpl.md#getNamespace)
 
+### Check If Namespace Exists { #namespaceExists }
+
+```java
+boolean namespaceExists(
+  String[] namespace)
+```
+
+By default, `namespaceExists` tries to [load the namespace metadata](#loadNamespaceMetadata) in this catalog. For a successful load, `namespaceExists` is positive (`true`).
+
+Used when:
+
+* `CatalogManager` is requested to [setCurrentNamespace](CatalogManager.md#setCurrentNamespace)
+* `CatalogImpl` is requested to [databaseExists](../../CatalogImpl.md#databaseExists)
+* `DelegatingCatalogExtension` is requested to [namespaceExists](DelegatingCatalogExtension.md#namespaceExists)
+* `CREATE NAMESPACE` command is executed
+* `DROP NAMESPACE` command is executed
+
 ## Implementations
 
 * [CatalogExtension](CatalogExtension.md)

docs/logical-operators/CreateNamespace.md

@@ -0,0 +1,30 @@
+---
+title: CreateNamespace
+---
+
+# CreateNamespace Unary Logical Operator
+
+`CreateNamespace` is a unary logical operator (`UnaryCommand`) that represents the following high-level operator in logical query plans:
+
+* [CREATE NAMESPACE](../sql/AstBuilder.md#visitCreateNamespace) SQL command
+
+## Creating Instance
+
+`CreateNamespace` takes the following to be created:
+
+* <span id="name"> Name ([LogicalPlan](LogicalPlan.md))
+* <span id="ifNotExists"> `ifNotExists` flag
+* <span id="properties"> Properties (`Map[String, String]`)
+
+`CreateNamespace` is created when:
+
+* `AstBuilder` is requested to [parse CREATE NAMESPACE command](../sql/AstBuilder.md#visitCreateNamespace)
+
+## Resolution Rules
+
+`CreateNamespace` is resolved using the following resolution rules:
+
+Resolution Rule | Operator
+-|-
+ [ResolveSessionCatalog](../logical-analysis-rules/ResolveSessionCatalog.md) logical analysis rule for the [session catalog (`spark_catalog`)](../connector/catalog/CatalogV2Util.md#isSessionCatalog) | `CreateDatabaseCommand` logical command
+ [DataSourceV2Strategy](../execution-planning-strategies/DataSourceV2Strategy.md) execution planning strategy | [CreateNamespaceExec](../physical-operators/CreateNamespaceExec.md) physical command

docs/physical-operators/CreateNamespaceExec.md

@@ -0,0 +1,21 @@
+---
+title: CreateNamespaceExec
+---
+
+# CreateNamespaceExec Physical Command Operator
+
+`CreateNamespaceExec` is a leaf [V2CommandExec](V2CommandExec.md) that represents [CreateNamespace](../logical-operators/CreateNamespace.md) logical operator at execution (for non-[session catalogs](../connector/catalog/CatalogV2Util.md#isSessionCatalog)).
+
+## Executing Command { #run }
+
+??? note "V2CommandExec"
+
+    ```scala
+    run(): Seq[InternalRow]
+    ```
+
+    `run` is part of the [V2CommandExec](V2CommandExec.md#run) abstraction.
+
+`run` requests the given [SupportsNamespaces](../connector/catalog/SupportsNamespaces.md) catalog to [check if the multi-part namespace exists](../connector/catalog/SupportsNamespaces.md#namespaceExists).
+
+Unless the namespace exists, `run` requests the [SupportsNamespaces](../connector/catalog/SupportsNamespaces.md) catalog to [create it](../connector/catalog/SupportsNamespaces.md#createNamespace) (with the `owner` property being the current user).

docs/sql/AstBuilder.md

@@ -109,6 +109,24 @@ Used when:
 * [withSelectQuerySpecification](#withSelectQuerySpecification)
 * [withTransformQuerySpecification](#withTransformQuerySpecification)
 
+### visitCreateNamespace { #visitCreateNamespace }
+
+Creates a [CreateNamespace](../logical-operators/CreateNamespace.md) logical operator
+
+```sql
+CREATE (NAMESPACE | DATABASE | SCHEMA) [IF NOT EXISTS] identifierReference
+  [COMMENT comment]
+  [LOCATION location]
+  [WITH (DBPROPERTIES | PROPERTIES) propertyList]
+
+identifierReference
+    : IDENTIFIER_KW LEFT_PAREN expression RIGHT_PAREN
+    | multipartIdentifier
+    ;
+```
+
+ANTLR labeled alternative: `#createNamespace`
+
 ### visitCreateTable { #visitCreateTable }
 
 Creates a [CreateTableAsSelect](../logical-operators/CreateTableAsSelect.md) (for CTAS queries with `AS` clause) or [CreateTable](../logical-operators/CreateTable.md) logical operator