updated docs

Author: venom1204

man/setkey.Rd

@@ -39,6 +39,20 @@ ordering vector of the dataset's rows according to the provided columns. This or
 is stored as an attribute of the \code{data.table} and the dataset retains the original order
 of rows in memory. See the \href{../doc/datatable-secondary-indices-and-auto-indexing.html}{\code{vignette("datatable-secondary-indices-and-auto-indexing")}} for more details.
 
+\subsection{Key vs. Index Subsetting}{
+When using \code{setkey}:
+\itemize{
+  \item Subsetting can omit \code{on} (e.g., \code{DT[.(value)]})
+  \item Data is physically reordered in RAM
+}
+When using \code{setindex}:
+\itemize{
+  \item Must specify \code{on} (e.g., \code{DT[.(value), on = "col"]})
+  \item Multiple indices can coexist via \code{setindexv(x, list(cols))}
+  \item Original row order is preserved
+}
+}
+
 \code{key} returns the \code{data.table}'s key if it exists; \code{NULL} if none exists.
 
 \code{haskey} returns \code{TRUE}/\code{FALSE} if the \code{data.table} has a key.
@@ -142,6 +156,15 @@ setindex(DT, B)
 indices(DT)           # get indices single vector
 indices(DT, vectors = TRUE) # get indices list
 
+# Keyed subsetting (no 'on' needed)
+setkey(DT, B)
+DT[.("e")]  # Returns row where B = "e"
+
+# Indexed subsetting (requires 'on')
+setindex(DT, B)
+DT[.("e"), on = "B"]  # Works
+# DT[.("e")]           # Would error (missing 'on')
+
 # Setting multiple indices at once
 DT = data.table(A = 5:1, B = letters[5:1], C = 10:6)
 setindexv(DT, list(c("A", "B"), c("B", "C")))

vignettes/datatable-secondary-indices-and-auto-indexing.Rmd

@@ -62,6 +62,49 @@ Secondary indices are similar to `keys` in *data.table*, except for two major di
 
 * There can be more than one secondary index for a data.table (as we will see below).
 
+#### 1.1 Keyed vs. Indexed Subsetting
+
+While both **keys** and **indices** enable fast binary search subsetting, they differ critically in usage:
+
+**Keyed subsetting** (implicit column matching)
+```{r}
+DT <- data.table(a = c(TRUE, FALSE), b = 1:2)
+setkey(DT, a)                # Set key
+DT[.(TRUE)]                  # No 'on' needed - key is used
+```
+
+**Indexed subsetting** (explicit column specification)
+
+```{r}
+DT <- data.table(a = c(TRUE, FALSE), b = 1:2)
+setindex(DT, a)              # Set index only (no reorder)
+DT[.(TRUE), on = "a"]        # Must specify 'on'
+```
+
+Always use `on`with indices to avoid errors. Keys establish permanent implicit matching, while indices require explicit direction for each operation.
+
+#### **Hierarchy of Lookup Operations**
+
+When `on` is specified, `data.table` uses this lookup order:
+
+- Existing keys matching `on` columns
+
+- Pre-built secondary indices matching `on` columns
+
+- Temporary auto-generated index (if none exist)
+
+**Example**: Error When Omitting on with Indices
+
+```{r}
+DT <- data.table(a = c(TRUE, FALSE), b = 1:2)
+setindex(DT, a)
+# DT[.(TRUE)] # Uncommenting this line causes: Error - must specify 'on'
+```
+
+- Use `DT[.(value)]` when the table is keyed by the relevant column(s).
+
+- Use `DT[.(value), on = "col"]` when using secondary indices or when no key is set.
+
 ### b) Set and get secondary indices
 
 #### -- How can we set the column `origin` as a secondary index in the *data.table* `flights`?