Add comprehensive JDBC Guide

docs/sphinx/requirements.txt

@@ -18,6 +18,7 @@ snowballstemmer==2.2.0
 soupsieve==2.5
 sphinx==8.1.3
 sphinx-basic-ng==1.0.0b2
+sphinx-design==0.6.1
 sphinxcontrib-devhelp==2.0.0
 sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jsmath==1.0.1

docs/sphinx/source/SQL_Reference.md

@@ -26,6 +26,5 @@ reference/Indexes
 :caption: Miscellaneous
 :maxdepth: 2
 
-reference/Direct_Access_Api
 reference/understanding_bitmap
 ```

docs/sphinx/source/conf.py

@@ -30,7 +30,7 @@
 copyright = '2025, Apple Inc.'
 author = 'Apple Inc.'
 
-extensions = ['myst_parser']
+extensions = ['myst_parser', 'sphinx_design']
 
 templates_path = ['_templates']
 exclude_patterns = []
@@ -66,4 +66,5 @@
 """
 
 myst_heading_anchors = 4
+myst_enable_extensions = ["colon_fence"]
 

docs/sphinx/source/index.md

@@ -26,6 +26,7 @@ reliability, and performance in a distributed setting.
 :maxdepth: 1
 Overview and Examples <Overview>
 GettingStarted
+JDBC Guide <jdbc/index>
 Building <Building>
 SchemaEvolution
 Extending

docs/sphinx/source/jdbc/advanced.rst

@@ -0,0 +1,224 @@
+======================
+Advanced JDBC Features
+======================
+
+.. important::
+   The JDBC interface is experimental and not production-ready at this stage. APIs and behaviors are subject to change.
+
+This guide covers FoundationDB Record Layer-specific JDBC features for working with complex data types like STRUCTs and ARRAYs.
+
+.. note::
+   **Driver-Specific Classes**: When creating STRUCT and ARRAY values, use the appropriate builder for your JDBC driver:
+
+   - **Embedded Driver**: ``EmbeddedRelationalStruct`` and ``EmbeddedRelationalArray`` (from ``com.apple.foundationdb.relational.api``)
+   - **Server Driver**: ``JDBCRelationalStruct`` and ``JDBCRelationalArray`` (from ``com.apple.foundationdb.relational.jdbc``)
+
+   Both provide identical APIs, so the code examples in this guide work with either by changing the import and class name.
+
+Working with STRUCT Types
+==========================
+
+The Record Layer extends standard JDBC to support STRUCT types, which represent nested record structures similar to protobuf messages. STRUCTs allow you to model hierarchical data within your relational schema.
+
+Reading STRUCT Values
+---------------------
+
+To read STRUCT values from a query result, unwrap the ``ResultSet`` to ``RelationalResultSet`` which provides direct access to STRUCTs:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::read-struct[]
+   :end-before: // end::read-struct[]
+   :dedent: 8
+
+Accessing Nested STRUCT Fields
+-------------------------------
+
+STRUCTs can contain other STRUCTs, allowing for deeply nested data structures. Here's how to read a STRUCT with a nested STRUCT:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/ComplexTypesEmbedded.java
+   :language: java
+   :start-after: // tag::query-struct[]
+   :end-before: // end::query-struct[]
+   :dedent: 4
+   :lines: 1-26
+
+Creating STRUCT Values
+----------------------
+
+Use the appropriate builder depending on your JDBC driver. Both builders provide identical APIs. Here's an example inserting a STRUCT into a STRUCT column:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::create-struct-simple[]
+   :end-before: // end::create-struct-simple[]
+   :dedent: 8
+
+Creating Nested STRUCTs
+-----------------------
+
+You can create STRUCTs that contain nested STRUCTs and insert them as a single value. Here's an example that creates a customer STRUCT with a nested address STRUCT:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/ComplexTypesEmbedded.java
+   :language: java
+   :start-after: // tag::insert-struct[]
+   :end-before: // end::insert-struct[]
+   :dedent: 4
+   :lines: 1-20
+
+Handling NULL STRUCT Fields
+----------------------------
+
+You can set NULL values for individual fields within a STRUCT:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::create-struct-null[]
+   :end-before: // end::create-struct-null[]
+   :dedent: 8
+
+Working with ARRAY Types
+=========================
+
+The Record Layer supports ARRAY types containing elements of any SQL type, including primitives, STRUCTs, and even nested ARRAYs.
+
+Reading ARRAY Values
+--------------------
+
+Use the ``getArray()`` method to retrieve ARRAY values from a ``ResultSet``:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::read-array-basic[]
+   :end-before: // end::read-array-basic[]
+   :dedent: 8
+
+Using ResultSet to Iterate Arrays
+----------------------------------
+
+You can also retrieve array elements as a ``ResultSet`` for more structured access:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::read-array-resultset[]
+   :end-before: // end::read-array-resultset[]
+   :dedent: 8
+
+Creating ARRAY Values
+---------------------
+
+Use the appropriate builder depending on your JDBC driver. Both builders provide identical APIs:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::create-array-basic[]
+   :end-before: // end::create-array-basic[]
+   :dedent: 8
+
+Working with Different Array Element Types
+-------------------------------------------
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::create-array-types[]
+   :end-before: // end::create-array-types[]
+   :dedent: 8
+
+Handling NULL Arrays
+--------------------
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::array-null[]
+   :end-before: // end::array-null[]
+   :dedent: 8
+
+Complex Nested Types
+====================
+
+Arrays of STRUCTs
+-----------------
+
+ARRAYs can contain STRUCT elements, allowing for collections of complex records:
+
+.. tab-set::
+
+   .. tab-item:: Embedded Driver
+      :sync: embedded
+
+      .. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+         :language: java
+         :start-after: // tag::array-of-structs[]
+         :end-before: // end::array-of-structs[]
+         :dedent: 8
+
+   .. tab-item:: Server Driver
+      :sync: server
+
+      .. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippetsServer.java
+         :language: java
+         :start-after: // tag::array-of-structs[]
+         :end-before: // end::array-of-structs[]
+         :dedent: 8
+
+Reading Arrays of STRUCTs
+-------------------------
+
+When reading arrays that contain STRUCT elements, unwrap the array's ``ResultSet`` to ``RelationalResultSet``:
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/ComplexTypesEmbedded.java
+   :language: java
+   :start-after: // tag::query-struct[]
+   :end-before: // end::query-struct[]
+   :dedent: 4
+   :lines: 28-47
+
+STRUCTs Containing Arrays
+-------------------------
+
+STRUCTs can contain ARRAY fields. You can insert the entire STRUCT including its arrays as a single value:
+
+.. tab-set::
+
+   .. tab-item:: Embedded Driver
+      :sync: embedded
+
+      .. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+         :language: java
+         :start-after: // tag::struct-containing-arrays[]
+         :end-before: // end::struct-containing-arrays[]
+         :dedent: 8
+
+   .. tab-item:: Server Driver
+      :sync: server
+
+      .. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippetsServer.java
+         :language: java
+         :start-after: // tag::struct-containing-arrays[]
+         :end-before: // end::struct-containing-arrays[]
+         :dedent: 8
+
+Inspecting Array Metadata
+==========================
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::array-metadata[]
+   :end-before: // end::array-metadata[]
+   :dedent: 8
+
+Inspecting STRUCT Metadata
+===========================
+
+.. literalinclude:: ../../../../examples/src/main/java/com/apple/foundationdb/relational/jdbc/examples/AdvancedSnippets.java
+   :language: java
+   :start-after: // tag::struct-metadata[]
+   :end-before: // end::struct-metadata[]
+   :dedent: 8
+
+See Also
+========
+
+- :doc:`basic` - Basic JDBC usage patterns
+- :doc:`../SQL_Reference` - Complete SQL syntax reference
+- :doc:`../reference/Databases_Schemas_SchemaTemplates` - Understanding the data model