From 61b1ebb81ec83369fe98697474dcaff2d9f21124 Mon Sep 17 00:00:00 2001
From: bog-walk <82039410+bog-walk@users.noreply.github.com>
Date: Tue, 3 Sep 2024 17:45:09 -0400
Subject: [PATCH] docs: EXPOSED-515 How to identify composite key columns that
 use reference() (#2225)

* docs: EXPOSED-515 How to identify composite key columns that use reference()

The documentation mentions that component columns of a composite key in
`CompositeIdTable` should be marked using `entityId()`. If this is done on columns
that are already `Column<EntityID<?>>`, it will lead to another nested wrap. This
can be avoided by marking the component column using `addIdColumn()` in the table
definition. An example of this using key columns that reference another table
has been included in both topics that explain how to define a `CompositeIdTable`.
---
 .../Writerside/topics/Deep-Dive-into-DAO.md   | 18 ++++++++++++++-
 .../Writerside/topics/Table-Definition.topic  | 22 +++++++++++++++++++
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/documentation-website/Writerside/topics/Deep-Dive-into-DAO.md b/documentation-website/Writerside/topics/Deep-Dive-into-DAO.md
index 688e89c038..a46e843a9c 100644
--- a/documentation-website/Writerside/topics/Deep-Dive-into-DAO.md
+++ b/documentation-website/Writerside/topics/Deep-Dive-into-DAO.md
@@ -81,6 +81,22 @@ class Director(id: EntityID<CompositeID>) : CompositeEntity(id) {
     var genre by Directors.genre
 }
 ```
+<include from="Table-Definition.topic" element-id="add-id-column-tip" />
+```kotlin
+object Guilds : UUIDTable("guilds")
+
+object Directors : CompositeIdTable("directors") {
+    val name = varchar("name", 50).entityId()
+    val guildId = reference("guild_id", Guilds)
+    val genre = enumeration<Genre>("genre")
+    
+    init {
+        addIdColumn(guildId)
+    }
+
+    override val primaryKey = PrimaryKey(name, guildId)
+}
+```
 
 ## Basic CRUD operations
 ### Create
@@ -143,8 +159,8 @@ val directorId = CompositeID {
     it[Directors.guildId] = "..."
 }
 
+// these will both deconstruct in SQL to the 2 component columns
 val director = Director.findById(directorId)
-// this will deconstruct in SQL to both component columns
 val directors = Director.find { Directors.id eq directorId }
 ```
 #### Sort (Order-by)
diff --git a/documentation-website/Writerside/topics/Table-Definition.topic b/documentation-website/Writerside/topics/Table-Definition.topic
index a13da2530b..28a8e59373 100644
--- a/documentation-website/Writerside/topics/Table-Definition.topic
+++ b/documentation-website/Writerside/topics/Table-Definition.topic
@@ -304,6 +304,28 @@
                     override val primaryKey = PrimaryKey(areaCode, latitude, longitude)
                 }
             </code-block>
+            <p id="add-id-column-tip">If any of the key component columns have already been marked by <code>entityId()</code>
+                in another table, they can still be identified using <code>addIdColumn()</code>. This might be useful for
+                key columns that reference another <code>IdTable</code>:</p>
+            <code-block lang="kotlin">
+                object AreaCodes : IdTable&lt;Int&gt;("area_codes") {
+                    override val id = integer("code").entityId()
+                    override val primaryKey = PrimaryKey(id)
+                }
+
+                object Towns : CompositeIdTable("towns") {
+                    val areaCode = reference("area_code", AreaCodes)
+                    val latitude = decimal("latitude", 9, 6).entityId()
+                    val longitude = decimal("longitude", 9, 6).entityId()
+                    val name = varchar("name", 32)
+
+                    init {
+                        addIdColumn(areaCode)
+                    }
+
+                    override val primaryKey = PrimaryKey(areaCode, latitude, longitude)
+                }
+            </code-block>
             <tip>For more information on <code>CompositeIdTable</code> types, see <a
                     href="Deep-Dive-into-DAO.md#table-types">DAO Table Types</a>.
             </tip>