diff --git a/src/Database/Trait/Cursors.php b/src/Database/Trait/Cursors.php index d72359648..32dee914e 100644 --- a/src/Database/Trait/Cursors.php +++ b/src/Database/Trait/Cursors.php @@ -94,7 +94,7 @@ public function resolveCursor(string $collection, string $id, CursorDirection $d } if (! $parsed->distinct) { - [$orderAttributes, $orderTypes] = $this->addTieBreaks($orderAttributes, $orderTypes, $parsed->filters, $joins, $joinedCollections, true, $parsed->selections); + [$orderAttributes, $orderTypes] = $this->addTieBreaks($definition, $orderAttributes, $orderTypes, $parsed->filters, $joins, $joinedCollections, true, $parsed->selections); } $joinedOrders = []; diff --git a/src/Database/Trait/Documents.php b/src/Database/Trait/Documents.php index fba86ed25..282704010 100644 --- a/src/Database/Trait/Documents.php +++ b/src/Database/Trait/Documents.php @@ -4224,7 +4224,7 @@ private function fetch(Collection $collection, array $queries, PermissionType $f } if (! $isAggregation && ! $distinct) { - [$orderAttributes, $orderTypes] = $this->addTieBreaks($orderAttributes, $orderTypes, $filters, $joins, $joinedCollections, ! empty($cursor), $selects); + [$orderAttributes, $orderTypes] = $this->addTieBreaks($collection, $orderAttributes, $orderTypes, $filters, $joins, $joinedCollections, ! empty($cursor), $selects); } if (! empty($cursor)) { @@ -5143,6 +5143,107 @@ private static function aliasAggregates(array $queries): array return $queries; } + /** + * The direction of the sequence tie break that lets an index serve the whole order. + * + * InnoDB ends every secondary index with the primary key in ascending order, so an index whose + * attributes are exactly the order attributes also orders by sequence: ascending when the order + * reads the index forward, descending when it reads it backward. `(x)` serves `x DESC, _id DESC` + * and `(x DESC)` serves `x DESC, _id ASC`; any other pairing filesorts every row in range. With no + * such index the tie break follows the leading direction, which is what an ascending index wants. + * + * The index may also hold attributes that a filter pins to a single value, before, between or after + * the order attributes: with `status = ?` and `type = ?`, `(status, x DESC, type)` reads in + * `x DESC, _id ASC` order just like `(x DESC)`. + * + * @param array $orderAttributes + * @param array $orderTypes + * @param array $filters + */ + private function tieBreakDirection(Collection $collection, array $orderAttributes, array $orderTypes, array $filters): OrderDirection + { + $leading = $orderTypes[0] ?? OrderDirection::Asc; + if ($orderAttributes === []) { + return $leading; + } + + $orderAttributes = \array_values($orderAttributes); + $orderTypes = \array_values($orderTypes); + + // `= ?` with one value and `IS NULL` each pin a column to a single value, so the index rows that match + // are ordered by the columns after it. An `and()` group pins like top-level filters; an `or()` pins nothing. + $pinned = []; + $pending = \array_values($filters); + while ($pending !== []) { + $filter = \array_pop($pending); + if ($filter->getMethod() === Method::And) { + foreach ($filter->getValues() as $nested) { + if ($nested instanceof Query) { + $pending[] = $nested; + } + } + } elseif ($filter->getMethod() === Method::IsNull + || ($filter->getMethod() === Method::Equal && \count($filter->getValues()) === 1)) { + $pinned[$filter->getAttribute()] = true; + } + } + + $sizes = []; + foreach ($collection->attributes() as $attribute) { + $sizes[$attribute->key] = $attribute->size; + } + + foreach ($collection->indexes() as $index) { + if (! \in_array($index->type, [IndexType::Key, IndexType::Unique], true)) { + continue; + } + + // Pinned columns may sit before, between or after the order columns: every matching row holds the + // same value there, so they do not change the order. With them skipped, the index must be exactly + // the order columns, in order, so the primary key that InnoDB appends comes right after the last. + $forward = null; + $matched = 0; + foreach ($index->attributes as $position => $attribute) { + if ($matched < \count($orderAttributes) && $attribute === $orderAttributes[$matched]) { + $requested = $orderTypes[$matched] ?? OrderDirection::Asc; + if (! \in_array($requested, [OrderDirection::Asc, OrderDirection::Desc], true)) { + continue 2; + } + + // A prefix-length order column (`name(64)`) holds only the start of each value, so MySQL + // cannot read the index in value order. A length that covers the whole column is a full-column + // index and still counts. A prefix on a pinned column is fine: every matching row shares it. + $length = $index->lengths[$position] ?? 0; + $size = $sizes[$attribute] ?? null; + if ($length > 0 && ($size === null || $length < $size)) { + continue 2; + } + + $same = $requested === ($index->orders[$position] ?? OrderDirection::Asc); + if ($forward !== null && $forward !== $same) { + continue 2; + } + $forward = $same; + $matched++; + + continue; + } + + if (! isset($pinned[$attribute])) { + continue 2; + } + } + + if ($matched !== \count($orderAttributes)) { + continue; + } + + return $forward ? OrderDirection::Asc : OrderDirection::Desc; + } + + return $leading; + } + /** * A vector index answers exactly one sort key, the distance: a tie break behind it makes the ordering unanswerable * from the index, so tie breaks are only added when a cursor needs a stable page boundary. @@ -5159,7 +5260,7 @@ private static function aliasAggregates(array $queries): array * @param array $selects * @return array{array, array} */ - private function addTieBreaks(array $orderAttributes, array $orderTypes, array $filters, array $joins, array $joinedCollections, bool $paged, array $selects): array + private function addTieBreaks(Collection $collection, array $orderAttributes, array $orderTypes, array $filters, array $joins, array $joinedCollections, bool $paged, array $selects): array { $uniqueOrderBy = \in_array(Document::ID, $orderAttributes, true) || \in_array(Document::SEQUENCE, $orderAttributes, true); @@ -5176,13 +5277,8 @@ private function addTieBreaks(array $orderAttributes, array $orderTypes, array $ } if (! $uniqueOrderBy) { - $leadingAttribute = $orderAttributes[0] ?? null; - $leadingOrderType = $orderTypes[0] ?? OrderDirection::Asc; - + $orderTypes[] = $this->tieBreakDirection($collection, $orderAttributes, $orderTypes, $filters); $orderAttributes[] = Document::SEQUENCE; - $orderTypes[] = \in_array($leadingAttribute, [Document::CREATED_AT, Document::UPDATED_AT], true) - ? $leadingOrderType - : OrderDirection::Asc; } if ($joins === [] || (! $paged && ! $this->showsJoinedRows($selects, $joinedCollections))) { @@ -5242,7 +5338,7 @@ private function nextPageCheck(string $collection, array $queries): Closure if ($distinct) { $this->assertDistinctCursorOrder($selects, $orders); } else { - [$orders] = $this->addTieBreaks($orders, $orderTypes, $filters, $joins, $joinedCollections, true, $selects); + [$orders] = $this->addTieBreaks($collection, $orders, $orderTypes, $filters, $joins, $joinedCollections, true, $selects); } $this->assertCursorHasOrderValues($cursor, $orders); diff --git a/tests/unit/Documents/FindLogicTest.php b/tests/unit/Documents/FindLogicTest.php index d5407424f..05f143891 100644 --- a/tests/unit/Documents/FindLogicTest.php +++ b/tests/unit/Documents/FindLogicTest.php @@ -398,6 +398,456 @@ public function testDateOrderAppendsMatchingSequenceTieBreakLast(): void ]); } + public function testDescendingOrderAppendsDescendingSequenceTieBreak(): void + { + $adapter = $this->mockAdapter(); + $this->setupCollectionLookup('testCol', [ + new Document(['$id' => 'age', 'key' => 'age', 'type' => 'integer', 'size' => 0, 'required' => false, 'array' => false]), + ]); + $adapter->expects($this->once()) + ->method('find') + ->with( + $this->anything(), + $this->anything(), + $this->anything(), + $this->anything(), + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + $this->anything(), + $this->anything(), + $this->anything(), + ) + ->willReturn([]); + + $this->database->find('testCol', [Query::orderDesc('age')]); + } + + public function testDateOrdersFollowTheirIndexDirection(): void + { + $adapter = $this->mockAdapter(); + $this->setupCollectionLookup('testCol', [], [ + new Document(['$id' => 'updated_desc', 'key' => 'updated_desc', 'type' => 'key', 'attributes' => ['$updatedAt'], 'lengths' => [], 'orders' => ['DESC']]), + ]); + + $sent = []; + $adapter->expects($this->exactly(3))->method('find')->willReturnCallback(function (...$arguments) use (&$sent): array { + $sent[] = [$arguments[4], $arguments[5]]; + + return []; + }); + + // The built-in _created_at index is ascending and not in the collection metadata, so a + // date order with no declared index keeps following its own direction, as it always has. + $this->database->find('testCol', [Query::orderDesc('$createdAt')]); + $this->database->find('testCol', [Query::orderAsc('$createdAt')]); + $this->database->find('testCol', [Query::orderDesc('$updatedAt')]); + + $this->assertSame([ + [['$createdAt', '$sequence'], [OrderDirection::Desc, OrderDirection::Desc]], + [['$createdAt', '$sequence'], [OrderDirection::Asc, OrderDirection::Asc]], + [['$updatedAt', '$sequence'], [OrderDirection::Desc, OrderDirection::Asc]], + ], $sent); + } + + public function testDescendingIndexKeepsAscendingSequenceTieBreak(): void + { + $adapter = $this->mockAdapter(); + $this->setupCollectionLookup('testCol', [ + new Document(['$id' => 'age', 'key' => 'age', 'type' => 'integer', 'size' => 0, 'required' => false, 'array' => false]), + ], [ + new Document(['$id' => 'age_desc', 'key' => 'age_desc', 'type' => 'key', 'attributes' => ['age'], 'lengths' => [], 'orders' => ['DESC']]), + ]); + + $sent = []; + $adapter->expects($this->exactly(2))->method('find')->willReturnCallback(function (...$arguments) use (&$sent): array { + $sent[] = [$arguments[4], $arguments[5]]; + + return []; + }); + + $this->database->find('testCol', [Query::orderDesc('age')]); + $this->database->find('testCol', [Query::orderAsc('age')]); + + // InnoDB appends the primary key ascending, so (age DESC) is read forward for + // `age DESC, _id ASC` and backward for `age ASC, _id DESC`. + $this->assertSame([ + [['age', '$sequence'], [OrderDirection::Desc, OrderDirection::Asc]], + [['age', '$sequence'], [OrderDirection::Asc, OrderDirection::Desc]], + ], $sent); + } + + /** + * Compound indexes whose leading columns are pinned by equality filters serve the order the same way an exact + * index does: with `status = ?`, InnoDB reads `(status, age DESC, _id)` in `age DESC, _id ASC` order. + * + * @return array, orders: list, lengths?: list, type?: string}>, list, list, list}> + */ + public static function compoundIndexTieBreakProvider(): array + { + $statusAgeDesc = ['attributes' => ['status', 'age'], 'orders' => ['ASC', 'DESC']]; + $statusAgeAsc = ['attributes' => ['status', 'age'], 'orders' => ['ASC', 'ASC']]; + $statusTypeAgeDesc = ['attributes' => ['status', 'type', 'age'], 'orders' => ['ASC', 'ASC', 'DESC']]; + + return [ + // (status, age DESC): the regression case. The old code sent _id ASC here and was served. + '(status, age DESC), status = ?, age DESC reads forward' => [ + [$statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), status = ?, age ASC reads backward' => [ + [$statusAgeDesc], + [Query::equal('status', ['active']), Query::orderAsc('age')], + ['age', '$sequence'], + [OrderDirection::Asc, OrderDirection::Desc], + ], + + // (status, age): ascending compound index, served by following the leading direction. + '(status, age), status = ?, age DESC reads backward' => [ + [$statusAgeAsc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age), status = ?, age ASC reads forward' => [ + [$statusAgeAsc], + [Query::equal('status', ['active']), Query::orderAsc('age')], + ['age', '$sequence'], + [OrderDirection::Asc, OrderDirection::Asc], + ], + + // Every leading column must be pinned by an equality filter for the index to serve the order. + '(status, type, age DESC), both pinned, age DESC reads forward' => [ + [$statusTypeAgeDesc], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, type, age DESC), only status pinned, falls back to leading direction' => [ + [$statusTypeAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // The leading column is not pinned to a single value, so the index cannot serve the order. + '(status, age DESC), no status filter, falls back to leading direction' => [ + [$statusAgeDesc], + [Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age DESC), status IN (a, b), falls back to leading direction' => [ + [$statusAgeDesc], + [Query::equal('status', ['active', 'archived']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age DESC), status range filter, falls back to leading direction' => [ + [$statusAgeDesc], + [Query::greaterThan('status', 'a'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // An exact index and a pinned compound index that agree. + '(age DESC) and (status, age DESC), status = ?, age DESC reads forward' => [ + [['attributes' => ['age'], 'orders' => ['DESC']], $statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + + // MySQL cannot read a prefix-length index in order, so it must not decide the direction. + '(name(64) DESC) prefix index, name DESC falls back to leading direction' => [ + [['attributes' => ['name'], 'orders' => ['DESC'], 'lengths' => [64]]], + [Query::orderDesc('name')], + ['name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(name(128) DESC) length covers the column, name DESC reads forward' => [ + [['attributes' => ['name'], 'orders' => ['DESC'], 'lengths' => [128]]], + [Query::orderDesc('name')], + ['name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + // Every row matching status = ? shares the indexed prefix, so the index still orders them by age. + '(status(8), age DESC) prefix on a pinned column, age DESC reads forward' => [ + [['attributes' => ['status', 'age'], 'orders' => ['ASC', 'DESC'], 'lengths' => [8, 0]]], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status(8), name(16) DESC) prefix on the order column, falls back to leading direction' => [ + [['attributes' => ['status', 'name'], 'orders' => ['ASC', 'DESC'], 'lengths' => [8, 16]]], + [Query::equal('status', ['active']), Query::orderDesc('name')], + ['name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // Several equality-filtered columns in front of the order column. + '(status, type, name, age DESC), all three pinned, age DESC reads forward' => [ + [['attributes' => ['status', 'type', 'name', 'age'], 'orders' => ['ASC', 'ASC', 'ASC', 'DESC']]], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::equal('name', ['n']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, type, age DESC), filters in a different order than the index, still pinned' => [ + [$statusTypeAgeDesc], + [Query::equal('type', ['a']), Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), extra filters outside the index do not matter' => [ + [$statusAgeDesc], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::greaterThan('name', 'm'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, type, age DESC), only the second column pinned, falls back' => [ + [$statusTypeAgeDesc], + [Query::equal('type', ['a']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, type, age DESC), status = ? and type range, falls back' => [ + [$statusTypeAgeDesc], + [Query::equal('status', ['active']), Query::greaterThan('type', 'a'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, type, age DESC), status = ? and type IN (a, b), falls back' => [ + [$statusTypeAgeDesc], + [Query::equal('status', ['active']), Query::equal('type', ['a', 'b']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // Columns after the order column must be pinned too: in (status, age DESC, type) _id follows type, + // which orders the rows unless type = ? holds it to one value. + '(status, age DESC, type), status = ?, type unpinned after the order column, falls back' => [ + [['attributes' => ['status', 'age', 'type'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age DESC, type), status = ? and type = ?, pinned after the order column, reads forward' => [ + [['attributes' => ['status', 'age', 'type'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC, type), status = ? and type = ?, age ASC reads backward' => [ + [['attributes' => ['status', 'age', 'type'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::orderAsc('age')], + ['age', '$sequence'], + [OrderDirection::Asc, OrderDirection::Desc], + ], + '(status, age DESC, type), status = ? and type IS NULL, reads forward' => [ + [['attributes' => ['status', 'age', 'type'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::isNull('type'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC, type, name), type pinned between two order columns, reads forward' => [ + [['attributes' => ['status', 'age', 'type', 'name'], 'orders' => ['ASC', 'DESC', 'ASC', 'ASC']]], + [Query::equal('status', ['active']), Query::equal('type', ['a']), Query::orderDesc('age'), Query::orderAsc('name')], + ['age', 'name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc, OrderDirection::Asc], + ], + '(status, age DESC, type, name), type unpinned between two order columns, falls back' => [ + [['attributes' => ['status', 'age', 'type', 'name'], 'orders' => ['ASC', 'DESC', 'ASC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderDesc('age'), Query::orderAsc('name')], + ['age', 'name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc, OrderDirection::Desc], + ], + '(age DESC, status), status = ? after the only order column, reads forward' => [ + [['attributes' => ['age', 'status'], 'orders' => ['DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + + // A partly pinned index earlier in the list must not stop the search for a fully pinned one. + '(type, age) unpinned, then (status, age DESC) pinned, the pinned one decides' => [ + [['attributes' => ['type', 'age'], 'orders' => ['ASC', 'ASC']], $statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, type, age) partly pinned, then (status, age DESC) pinned, the pinned one decides' => [ + [['attributes' => ['status', 'type', 'age'], 'orders' => ['ASC', 'ASC', 'ASC']], $statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + + // Cursor pages must use the same tie break as the first page, or rows that tie on age are skipped or repeated. + '(status, age DESC), status = ?, age DESC, cursorAfter' => [ + [$statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age'), Query::cursorAfter(new Document(['$id' => 'page', '$sequence' => 17, '$collection' => 'testCol', 'status' => 'active', 'age' => 30]))], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), status = ?, age DESC, cursorBefore' => [ + [$statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age'), Query::cursorBefore(new Document(['$id' => 'page', '$sequence' => 17, '$collection' => 'testCol', 'status' => 'active', 'age' => 30]))], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + + // Several order attributes: every direction must agree with the index, or every one must oppose it. + '(status, name DESC, age), status = ?, name DESC, age ASC reads forward' => [ + [['attributes' => ['status', 'name', 'age'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderDesc('name'), Query::orderAsc('age')], + ['name', 'age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc, OrderDirection::Asc], + ], + '(status, name DESC, age), status = ?, name ASC, age DESC reads backward' => [ + [['attributes' => ['status', 'name', 'age'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderAsc('name'), Query::orderDesc('age')], + ['name', 'age', '$sequence'], + [OrderDirection::Asc, OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, name DESC, age), status = ?, name DESC, age DESC mixes, falls back to leading direction' => [ + [['attributes' => ['status', 'name', 'age'], 'orders' => ['ASC', 'DESC', 'ASC']]], + [Query::equal('status', ['active']), Query::orderDesc('name'), Query::orderDesc('age')], + ['name', 'age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc, OrderDirection::Desc], + ], + + // Filters that do not pin the leading column to one value. + '(status, age DESC), status != ?, falls back to leading direction' => [ + [$statusAgeDesc], + [Query::notEqual('status', 'archived'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + // IS NULL pins the column to a single value just like = ?; IS NOT NULL does not. + '(status, age DESC), status IS NULL, age DESC reads forward' => [ + [$statusAgeDesc], + [Query::isNull('status'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), status IS NULL, age ASC reads backward' => [ + [$statusAgeDesc], + [Query::isNull('status'), Query::orderAsc('age')], + ['age', '$sequence'], + [OrderDirection::Asc, OrderDirection::Desc], + ], + '(status, type, age DESC), status IS NULL and type = ?, reads forward' => [ + [$statusTypeAgeDesc], + [Query::isNull('status'), Query::equal('type', ['a']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), status IS NOT NULL, falls back to leading direction' => [ + [$statusAgeDesc], + [Query::isNotNull('status'), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + // An and() group pins its equalities like top-level filters, at any depth; an or() group pins nothing. + '(status, age DESC), status = ? nested in and(), reads forward' => [ + [$statusAgeDesc], + [Query::and([Query::equal('status', ['active']), Query::greaterThan('age', 1)]), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, type, age DESC), equalities split across top level and nested and(and()), reads forward' => [ + [$statusTypeAgeDesc], + [Query::equal('status', ['active']), Query::and([Query::greaterThan('age', 1), Query::and([Query::equal('type', ['a']), Query::lessThan('age', 99)])]), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + '(status, age DESC), status = ? inside or(), falls back' => [ + [$statusAgeDesc], + [Query::or([Query::equal('status', ['active']), Query::greaterThan('age', 1)]), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age DESC), and() inside or(), falls back' => [ + [$statusAgeDesc], + [Query::or([Query::and([Query::equal('status', ['active']), Query::greaterThan('age', 1)]), Query::equal('status', ['archived'])]), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // Index types. + 'unique (status, age DESC), status = ?, age DESC reads forward' => [ + [['type' => 'unique'] + $statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + 'fulltext (name) is ignored, name DESC falls back to leading direction' => [ + [['type' => 'fulltext', 'attributes' => ['name'], 'orders' => []]], + [Query::orderDesc('name')], + ['name', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + + // Two indexes that disagree: the first declared wins, and either one serves the order. + '(status, age) before (status, age DESC), first wins' => [ + [$statusAgeAsc, $statusAgeDesc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Desc], + ], + '(status, age DESC) before (status, age), first wins' => [ + [$statusAgeDesc, $statusAgeAsc], + [Query::equal('status', ['active']), Query::orderDesc('age')], + ['age', '$sequence'], + [OrderDirection::Desc, OrderDirection::Asc], + ], + ]; + } + + /** + * @param list, orders: list, lengths?: list, type?: string}> $indexes + * @param list $queries + * @param list $expectedAttributes + * @param list $expectedTypes + */ + #[\PHPUnit\Framework\Attributes\DataProvider('compoundIndexTieBreakProvider')] + public function testCompoundIndexTieBreakDirection(array $indexes, array $queries, array $expectedAttributes, array $expectedTypes): void + { + $adapter = $this->mockAdapter(); + $attribute = static fn (string $key, string $type, int $size): Document => new Document(['$id' => $key, 'key' => $key, 'type' => $type, 'size' => $size, 'required' => false, 'array' => false]); + + $indexDocuments = []; + foreach ($indexes as $position => $index) { + $indexDocuments[] = new Document([ + '$id' => 'index_'.$position, + 'key' => 'index_'.$position, + 'type' => $index['type'] ?? 'key', + 'attributes' => $index['attributes'], + 'lengths' => $index['lengths'] ?? [], + 'orders' => $index['orders'], + ]); + } + + $this->setupCollectionLookup('testCol', [ + $attribute('status', 'string', 32), + $attribute('type', 'string', 32), + $attribute('name', 'string', 128), + $attribute('age', 'integer', 0), + ], $indexDocuments); + + $sent = null; + $adapter->expects($this->once())->method('find')->willReturnCallback(function (...$arguments) use (&$sent): array { + $sent = [$arguments[4], $arguments[5]]; + + return []; + }); + + $this->database->find('testCol', $queries); + + $this->assertSame([$expectedAttributes, $expectedTypes], $sent); + } + public function testFindCursorValidationThrowsOnEmptyCursorAttribute(): void { $attributes = [