From efe3e03e3bef6a7dc8b0d0bf1dd9f4969b364696 Mon Sep 17 00:00:00 2001
From: Brendan Clement <brendan.clement@lancedb.com>
Date: Wed, 14 Oct 2026 10:14:45 -0700
Subject: [PATCH] docs: match the SQL DDL examples to what a deployment accepts

A plain ADD COLUMN, a primary key on a nullable column, bucket sharding without a column, CREATE SCHEMA public and a three-part schema path are all rejected. Show forms that run, say what bucket sharding needs, and note that a new index is built in the background before it can be dropped.
---
 docs/web/sql/ddl/index.mdx     |  4 +++-
 docs/web/sql/ddl/namespace.mdx | 14 ++++++++------
 docs/web/sql/ddl/table.mdx     | 21 ++++++++++++---------
 3 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/docs/web/sql/ddl/index.mdx b/docs/web/sql/ddl/index.mdx
index 0c6c63155..9533d9fe0 100644
--- a/docs/web/sql/ddl/index.mdx
+++ b/docs/web/sql/ddl/index.mdx
@@ -41,7 +41,9 @@ DROP INDEX documents.title_idx
 
 Takes the qualified `table.index` name. Find it with the SDK's
 [`list_indices`](/indexing) if you created the index without
-naming it yourself.
+naming it yourself. A deployment builds the index in the background after
+`CREATE INDEX` returns; until that build finishes, the index is not listed and
+`DROP INDEX` reports it as not found.
 
 ## What to read next {#next}
 
diff --git a/docs/web/sql/ddl/namespace.mdx b/docs/web/sql/ddl/namespace.mdx
index 3ec08469b..34ce673a0 100644
--- a/docs/web/sql/ddl/namespace.mdx
+++ b/docs/web/sql/ddl/namespace.mdx
@@ -14,14 +14,16 @@ standard's name for the same concept.
 ## CREATE SCHEMA {#create}
 
 ```sql
-CREATE SCHEMA public
-CREATE SCHEMA db1.ns1.ns2
+CREATE SCHEMA analytics
+CREATE SCHEMA db1.`ns1$ns2`
 CREATE SCHEMA IF NOT EXISTS `ns1$ns2`
 ```
 
-A dotted path creates the whole chain: `db1.ns1.ns2` creates `ns2` inside
-`ns1` inside `db1`, provided the parents already exist. A name containing the
-namespace path delimiter itself is backtick-quoted, as in `` `ns1$ns2` `` above.
+A nested namespace is one backtick-quoted name with `$` between its
+components: `` db1.`ns1$ns2` `` creates `ns2` inside `ns1` in database `db1`,
+provided `ns1` already exists. The part before the dot is the database, so a
+three-part path such as `db1.ns1.ns2` is rejected. `public` is the database's
+root namespace, which is never created or dropped.
 
 `IF NOT EXISTS` makes the statement a no-op rather than an error when the
 namespace is already there.
@@ -29,7 +31,7 @@ namespace is already there.
 ## DROP SCHEMA {#drop}
 
 ```sql
-DROP SCHEMA db1.public
+DROP SCHEMA db1.analytics
 DROP SCHEMA IF EXISTS `a$b`
 DROP SCHEMA `a$b` RESTRICT
 ```
diff --git a/docs/web/sql/ddl/table.mdx b/docs/web/sql/ddl/table.mdx
index 759bb64b9..2b80bad10 100644
--- a/docs/web/sql/ddl/table.mdx
+++ b/docs/web/sql/ddl/table.mdx
@@ -35,11 +35,10 @@ name.
 
 ### A plain column {#plain-column}
 
-```sql
-ALTER TABLE t ADD COLUMN c INT
-```
-
-Added empty and nullable. Nothing is computed.
+SQL `ADD COLUMN` requires an `AS` binding, so a plain column such as
+`ALTER TABLE t ADD COLUMN c INT` is rejected. Add an empty, nullable column
+with the SDK instead -- see
+[Add nullable columns](/management/table#schema-add-nullable-columns).
 
 ### A computed column {#computed-column}
 
@@ -97,19 +96,23 @@ ALTER TABLE t SET UNENFORCED PRIMARY KEY (id)
 
 Records which column identifies a row. **Unenforced** is not a hedge in the
 naming: uniqueness is not checked on write, and declaring it does not make
-duplicates impossible. It tells the planner what to assume.
+duplicates impossible. It tells the planner what to assume. The column must be
+declared `NOT NULL`.
 
 ```sql
 ALTER TABLE t SET WAL
-ALTER TABLE t SET WAL WITH (sharding = 'bucket', buckets = 4)
+ALTER TABLE t SET WAL WITH (sharding = 'bucket', column = 'id', buckets = 4)
 ALTER TABLE t SET WAL WITH (maintained_indexes = '')
 ALTER TABLE t UNSET WAL
 ```
 
 A write-ahead log makes small frequent writes cheap by batching them out of the
 commit path. `sharding` and `buckets` spread the log so concurrent writers do
-not contend on one place; `maintained_indexes` chooses which indexes are kept
-current against WAL rows. See
+not contend on one place; `bucket` sharding names its `column`, which must be
+the table's unenforced primary key, and inserts into the table then need a
+scalar index on that key. `maintained_indexes` chooses which indexes are kept
+current against WAL rows. A table with a computed column cannot take a
+write-ahead log. See
 [Background jobs](/maintenance/background-jobs#wal) for how the log gets
 folded back into the table.