docs: document version checkout via lance_dataset_open

README.md

@@ -113,6 +113,20 @@ ds.scan()
 // consume stream...
 ```
 
+### Open at a specific version
+
+`lance_dataset_open` takes a `version` argument — `0` means the latest, any
+other value checks out that specific version id (e.g. one returned by
+`lance_dataset_versions`):
+
+```c
+LanceDataset* ds = lance_dataset_open("data.lance", NULL, 42);
+```
+
+```cpp
+auto ds = lance::Dataset::open("data.lance", {}, /*version=*/42);
+```
+
 ## License
 
 Apache-2.0

include/lance.h

@@ -101,6 +101,11 @@ typedef struct LanceVersions LanceVersions;
 /**
  * Open a Lance dataset.
  *
+ * Pass `version` = 0 to open the latest, or a specific version id (e.g. one
+ * returned by `lance_dataset_versions`) to check out that version:
+ *
+ *     LanceDataset* ds = lance_dataset_open("data.lance", NULL, 42);
+ *
  * @param uri           Dataset path (file://, s3://, memory://, etc.)
  * @param storage_opts  NULL-terminated key-value pairs ["k1","v1",NULL], or NULL
  * @param version       Version to open (0 = latest)

include/lance.hpp

@@ -100,7 +100,9 @@ class Dataset {
     Handle<LanceDataset, lance_dataset_close> handle_;
 
 public:
-    /// Open a dataset at the given URI.
+    /// Open a dataset at the given URI. Pass `version` = 0 (the default) for
+    /// the latest, or a specific version id from `versions()` to check out
+    /// that version, e.g. `lance::Dataset::open("data.lance", {}, /*version=*/42)`.
     static Dataset open(
         const std::string& uri,
         const std::vector<std::pair<std::string, std::string>>& storage_opts = {},