docs: DOC-1420: Groovy getColumnSource reference doc

docs/groovy/how-to-guides/extract-table-value.md

@@ -33,7 +33,7 @@ For different data types, use the appropriate `ColumnVectors` method:
 
 ## table.getColumnSource() (row key access)
 
-The [`getColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/Table.html#getColumnSource(java.lang.String)) method returns a [`ColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/ColumnSource.html) that provides access to column data by **row key**, not positional index.
+The [`getColumnSource`](../reference/table-operations/metadata/getColumnSource.md) method returns a [`ColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/ColumnSource.html) that provides access to column data by **row key**, not positional index.
 
 ```groovy order=:log test-set=2
 result = newTable(
@@ -79,6 +79,6 @@ while (iterator.hasNext()) {
 - [`ColumnVectors`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/vectors/ColumnVectors.html)
 - [Iterate over tables](iterate-table-vectors.md)
 - [How do row keys and positional indices behave?](https://deephaven.io/core/docs/reference/community-questions/shifts/)
-- [`getColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/Table.html#getColumnSource(java.lang.String))
+- [`getColumnSource`](../reference/table-operations/metadata/getColumnSource.md)
 - [`columnIterator`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/Table.html#columnIterator(java.lang.String))
 - [`ColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/ColumnSource.html)

docs/groovy/reference/table-operations/metadata/getColumnSource.md

@@ -0,0 +1,85 @@
+---
+title: getColumnSource
+---
+
+The `getColumnSource` method returns a `ColumnSource` that provides access to a column's data by **row key**, not positional index. Several overloads can cast the result to a target type so you don't need an explicit cast when the column's data type is known.
+
+## Syntax
+
+```groovy syntax
+table.getColumnSource(sourceName)
+table.getColumnSource(sourceName, clazz)
+table.getColumnSource(sourceName, clazz, componentType)
+table.getColumnSource(columnDefinition)
+```
+
+## Parameters
+
+<ParamTable>
+<Param name="sourceName" type="String">
+
+The name of the column.
+
+</Param>
+<Param name="clazz" type="Class<? extends T>">
+
+The target data type to cast the `ColumnSource` to.
+
+</Param>
+<Param name="componentType" type="Class<?>">
+
+The target component type, which is useful for array or vector columns. May be `null`.
+
+</Param>
+<Param name="columnDefinition" type="ColumnDefinition<? extends T>">
+
+A `ColumnDefinition` whose data type and component type are used to cast the `ColumnSource`. The column name is taken from `columnDefinition.getName()`.
+
+</Param>
+</ParamTable>
+
+## Returns
+
+A `ColumnSource` for the requested column, parameterized by the target type when `clazz`, `componentType`, or a `columnDefinition` is provided.
+
+> [!IMPORTANT]
+> `ColumnSource` methods like `get(rowKey)` use **row keys**, not positional indices. Row keys are the internal identifiers for rows and may not match positional indices, especially in filtered or modified tables.
+
+## Examples
+
+The following example retrieves a `ColumnSource` by name and reads a value by row key:
+
+```groovy order=:log
+source = newTable(
+    intCol("Integers", 1, 2, 3, 4, 5)
+)
+
+columnSource = source.getColumnSource("Integers")
+println columnSource.getInt(2)
+```
+
+The following example casts the `ColumnSource` to a target type using a `Class` and using a `ColumnDefinition` from the table's definition:
+
+```groovy order=:log
+source = newTable(
+    intCol("Integers", 1, 2, 3, 4, 5)
+)
+
+// Cast to a target type by class
+intSource = source.getColumnSource("Integers", int.class)
+println intSource.getInt(2)
+
+// Cast using a ColumnDefinition from the table's definition
+intDef = source.getDefinition().getColumn("Integers")
+defSource = source.getColumnSource(intDef)
+println defSource.getInt(2)
+```
+
+## Related documentation
+
+- [Extract table values](../../../how-to-guides/extract-table-value.md)
+- [getDefinition](./getDefinition.md)
+- [`ColumnSource`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/ColumnSource.html)
+- [`ColumnDefinition`](https://deephaven.io/core/javadoc/io/deephaven/engine/table/ColumnDefinition.html)
+- [Javadoc](https://deephaven.io/core/javadoc/io/deephaven/engine/table/Table.html#getColumnSource(java.lang.String))
+- [Javadoc (ColumnDefinition overload)](https://deephaven.io/core/javadoc/io/deephaven/engine/table/Table.html#getColumnSource(io.deephaven.engine.table.ColumnDefinition))

docs/groovy/sidebar.json

@@ -1442,6 +1442,10 @@
                     "label": "getAttributes",
                     "path": "reference/table-operations/metadata/getAttributes.md"
                   },
+                  {
+                    "label": "getColumnSource",
+                    "path": "reference/table-operations/metadata/getColumnSource.md"
+                  },
                   {
                     "label": "getDefinition",
                     "path": "reference/table-operations/metadata/getDefinition.md"

docs/groovy/snapshots/94f044bad6a628c59610be96daa4bf94.json

@@ -0,0 +1 @@
+{"file":"reference/table-operations/metadata/getColumnSource.md","objects":{"source":{"type":"Table","data":{"columns":[{"name":"Integers","type":"int"}],"rows":[[{"value":"1"}],[{"value":"2"}],[{"value":"3"}],[{"value":"4"}],[{"value":"5"}]]}},":log":{"type":"Log","data":"3\n"}}}

docs/groovy/snapshots/9e228e5abc906d9112f6f818d78eade0.json

@@ -0,0 +1 @@
+{"file":"reference/table-operations/metadata/getColumnSource.md","objects":{"source":{"type":"Table","data":{"columns":[{"name":"Integers","type":"int"}],"rows":[[{"value":"1"}],[{"value":"2"}],[{"value":"3"}],[{"value":"4"}],[{"value":"5"}]]}},":log":{"type":"Log","data":"3\n3\n"}}}