Update documents for cross-partition scan and import feature

core/src/main/java/com/scalar/db/transaction/consensuscommit/ConsensusCommitConfig.java

@@ -197,8 +197,8 @@ private void validateCrossPartitionScanConfig(DatabaseConfig databaseConfig) {
 
   private void warnCrossPartitionScan(String storageName) {
     logger.warn(
-        "Enabling cross-partition scan for '{}' in production is not recommended "
-            + "because it makes transaction isolation level lower (i.e., snapshot). "
+        "Enabling the cross-partition scan for '{}' with 'SERIALIZABLE' isolation level is not recommended "
+            + "because transactions could be executed with lower isolation level (i.e., 'SNAPSHOT'). "
             + "Use it at your own risk only if the consistency does not matter for your transactions",
         storageName);
   }

docs/api-guide.md

@@ -295,6 +295,25 @@ boolean ifExist = true;
 admin.dropCoordinatorTables(ifExist);
 ```
 
+### Import a table
+
+You can import an existing table to ScalarDB as follows:
+
+```java
+// Import the table "ns.tbl". If the table is already managed by ScalarDB, the target table does not
+// exist, or the table does not meet the requirement of ScalarDB table, an exception will be thrown.
+admin.importTable("ns", "tbl", options);
+```
+
+{% capture notice--warning %}
+**Attention**
+
+You should carefully plan to import a table to ScalarDB in production because it will add transaction metadata columns to your database tables and the ScalarDB metadata tables. There would also be several differences between your database and ScalarDB and limitations. See also the following document.
+
+- [Importing existing tables to ScalarDB using ScalarDB Schema Loader](./schema-loader-import.md)
+
+{{ notice--warning | markdownify }}
+
 ## Transactional API
 
 This section explains how to execute transactional operations by using the Transactional API in ScalarDB.
@@ -621,9 +640,21 @@ You can't specify clustering-key boundaries and orderings in `Scan` by using a s
 
 <div class="notice--info">{{ notice--info | markdownify }}</div>
 
-##### Execute `Scan` without specifying a partition key to retrieve all the records of a table
+##### Execute cross-partition `Scan` without specifying a partition key to retrieve all the records of a table
+
+You can execute a `Scan` operation across all partitions, which we call cross-partition scan, without specifying a partition key by enabling the following property in the ScalarDB configuration.
+
+```properties
+scalar.db.cross_partition_scan.enabled=true
+```
+
+{% capture notice--warning %}
+**Attention**
+
+We do not recommend enabling the cross-partition scan with `SERIALIAZABLE` isolation level for non-JDBC databases because transactions could be executed with lower isolation level (i.e., `SNAPSHOT`). Use it at your own risk only if the consistency does not matter for your transactions.
+{% endcapture %}
 
-You can execute a `Scan` operation without specifying a partition key.
+<div class="notice--warning">{{ notice--warning | markdownify }}</div>
 
 Instead of calling the `partitionKey()` method in the builder, you can call the `all()` method to scan a table without specifying a partition key as follows:
 
@@ -645,11 +676,71 @@ List<Result> results = transaction.scan(scan);
 {% capture notice--info %}
 **Note**
 
-You can't specify clustering-key boundaries and orderings in `Scan` without specifying a partition key.
+You can't specify any filtering conditions and orderings in cross-partition `Scan` except for JDBC databases. See the following section to use cross-partition `Scan` with filtering or ordering for JDBC databases.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
+##### Execute cross-partition `Scan` with filtering and ordering
+
+By enabling the cross-partition scan option with filtering and ordering for JDBC databases as follows, you can execute a cross-partition `Scan` operation with flexible conditions and orderings.
+
+```properties
+scalar.db.cross_partition_scan.enabled=true
+scalar.db.cross_partition_scan.filtering.enabled=true
+scalar.db.cross_partition_scan.ordering.enabled=true
+```
+
+You can call the `where()` and `ordering()` methods after calling the `all()` method to specify arbitrary conditions and orderings as follows:
+
+```java
+// Create a `Scan` operation with arbitrary conditions and orderings.
+Scan scan =
+    Scan.newBuilder()
+        .namespace("ns")
+        .table("tbl")
+        .all()
+        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
+        .projections("c1", "c2", "c3", "c4")
+        .orderings(Scan.Ordering.desc("c3"), Scan.Ordering.asc("c4"))
+        .limit(10)
+        .build();
+
+// Execute the `Scan` operation.
+List<Result> results = transaction.scan(scan);
+```
+
+As an argument of the `where()` method, you can specify a condition, an and-wise condition set, or an or-wise condition set. After calling the `where()` method, you can add more conditions or condition sets using the `and()` method or `or()` method as follows:
+
+```java
+// Create a `Scan` operation with condition sets.
+Scan scan =
+    Scan.newBuilder()
+        .namespace("ns")
+        .table("tbl")
+        .all()
+        .where(
+            ConditionSetBuilder.condition(ConditionBuilder.column("c1").isLessThanInt(10))
+                .or(ConditionBuilder.column("c1").isGreaterThanInt(20))
+                .build())
+        .and(
+            ConditionSetBuilder.condition(ConditionBuilder.column("c2").isLikeText("a%"))
+                .or(ConditionBuilder.column("c2").isLikeText("b%"))
+                .build())
+        .limit(10)
+        .build();
+```
+
+{% capture notice--info %}
+**Note**
+
+In the `where()` condition method chain, the conditions must be an and-wise junction of `ConditionalExpression` or `OrConditionSet` (so-called conjunctive normal form) like the above example or an or-wise junction of `ConditionalExpression` or `AndConditionSet` (so-called disjunctive normal form).
 {% endcapture %}
 
 <div class="notice--info">{{ notice--info | markdownify }}</div>
 
+For more details of available conditions and condition sets, see the `ConditionBuilder` and `ConditionSetBuilder` page in the [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/latest/index.html) of the version of ScalarDB that you're using.
+
 #### `Put` operation
 
 `Put` is an operation to put a record specified by a primary key. The operation behaves as an upsert operation for a record, in which the operation updates the record if the record exists or inserts the record if the record does not exist.

docs/configurations.md

@@ -158,6 +158,24 @@ For details about using multiple storages, see [Multi-Storage Transactions](mult
 
 For details about client configurations, see the ScalarDB Cluster [client configurations (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/latest/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api/#client-configurations).
 
+## Cross-partition scan configurations
+
+By enabling the cross-partition scan option below, `Scan` operation can retrieve all records across partitions. In addition, you can specify arbitrary conditions and orderings in the cross-partition `Scan` operation by enabling `cross_partition_scan.filtering` and `cross_partition_scan.ordering`, respectively. Currently, the cross-partition scan with filtering and ordering is available only for JDBC databases. Note that `scalar.db.cross_partition_scan.enabled` must be `true` to enable them. See [Java API Guide - Scan operation](./api-guide.md#scan-operation) for how to use the cross-partition scan.
+
+{% capture notice--warning %}
+**Attention**
+
+We do not recommend enabling the cross-partition scan with `SERIALIAZABLE` isolation level for non-JDBC databases because transactions could be executed with lower isolation level (i.e., `SNAPSHOT`). Use it at your own risk only if the consistency does not matter for your transactions.
+{% endcapture %}
+
+<div class="notice--warning">{{ notice--warning | markdownify }}</div>
+
+| Name                                               | Description                                   | Default |
+|----------------------------------------------------|-----------------------------------------------|---------|
+| `scalar.db.cross_partition_scan.enabled`           | Enable the cross partition scan.              | `false` |
+| `scalar.db.cross_partition_scan.filtering.enabled` | Enable filtering in the cross partition scan. | `false` |
+| `scalar.db.cross_partition_scan.ordering.enabled`  | Enable ordering in the cross partition scan.  | `false` |
+
 ## Other ScalarDB configurations
 
 The following are additional configurations available for ScalarDB: