feat: implement distributing partitioned queries over multiple shards

Signed-off-by: Robin Appelman <robin@icewind.nl>

2 files changed, 52 insertions, 0 deletions

diff --git a/lib/public/DB/QueryBuilder/IQueryBuilder.php b/lib/public/DB/QueryBuilder/IQueryBuilder.php
index e14514ac254..df93a0b1ed5 100644
--- a/lib/public/DB/QueryBuilder/IQueryBuilder.php
+++ b/lib/public/DB/QueryBuilder/IQueryBuilder.php
@@ -1010,6 +1010,15 @@ interface IQueryBuilder {
 	public function getTableName($table);
 
 	/**
+	 * Returns the table name with database prefix as needed by the implementation
+	 *
+	 * @param string $table
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function prefixTableName(string $table): string;
+
+	/**
 	 * Returns the column name quoted and with table alias prefix as needed by the implementation
 	 *
 	 * @param string $column
@@ -1020,6 +1029,24 @@ interface IQueryBuilder {
 	public function getColumnName($column, $tableAlias = '');
 
 	/**
+	 * Provide a hint for the shard key for queries where this can't be detected otherwise
+	 *
+	 * @param string $column
+	 * @param mixed $value
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function hintShardKey(string $column, mixed $value);
+
+	/**
+	 * Set the query to run across all shards if sharding is enabled.
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function runAcrossAllShards();
+
+	/**
 	 * Get a list of column names that are expected in the query output
 	 *
 	 * @return array
diff --git a/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php b/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php
new file mode 100644
index 00000000000..fa00fb68719
--- /dev/null
+++ b/lib/public/DB/QueryBuilder/Sharded/IShardMapper.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Robin Appelman <robin@icewind.nl>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\DB\QueryBuilder\Sharded;
+
+/**
+ * Implementation of logic of mapping shard keys to shards.
+ * @since 30.0.0
+ */
+interface IShardMapper {
+	/**
+	 * Get the shard number for a given shard key and total shard count
+	 *
+	 * @param int $key
+	 * @param int $count
+	 * @return int
+	 * @since 30.0.0
+	 */
+	public function getShardForKey(int $key, int $count): int;
+}