diff --git a/.gitattributes b/.gitattributes index 64c458128..8c487eef2 100644 --- a/.gitattributes +++ b/.gitattributes @@ -18,12 +18,8 @@ psalm-baseline.xml export-ignore # Keep generated files from displaying in diffs by default # https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github -/src/Builder/Aggregation.php linguist-generated=true -/src/Builder/Aggregation/*.php linguist-generated=true -/src/Builder/Expression.php linguist-generated=true +/src/Builder/Accumulator/*.php linguist-generated=true /src/Builder/Expression/*.php linguist-generated=true -/src/Builder/Query.php linguist-generated=true /src/Builder/Query/*.php linguist-generated=true -/src/Builder/Stage.php linguist-generated=true +/src/Builder/Projection/*.php linguist-generated=true /src/Builder/Stage/*.php linguist-generated=true -/src/Builder/Stage/Stage.php linguist-generated=false diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml index 053d5776f..9306bfb27 100644 --- a/.github/workflows/benchmark.yml +++ b/.github/workflows/benchmark.yml @@ -5,7 +5,6 @@ on: branches: - "v*.*" - "master" - - "feature/*" paths-ignore: - "docs/**" push: @@ -15,6 +14,7 @@ on: - "feature/*" paths-ignore: - "docs/**" + - "generator/**" env: PHP_VERSION: "8.2" diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8698e7459..7ef1471d8 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -27,8 +27,8 @@ jobs: os: - "ubuntu-20.04" php-version: - - "7.4" - - "8.0" + #- "7.4" + #- "8.0" - "8.1" - "8.2" mongodb-version: @@ -39,27 +39,27 @@ jobs: - "server" include: - os: "ubuntu-20.04" - php-version: "8.0" + php-version: "8.1" mongodb-version: "6.0" driver-version: "mongodb/mongo-php-driver@master" topology: "replica_set" - os: "ubuntu-20.04" - php-version: "8.0" + php-version: "8.1" mongodb-version: "6.0" driver-version: "mongodb/mongo-php-driver@master" topology: "sharded_cluster" - os: "ubuntu-20.04" - php-version: "8.0" + php-version: "8.1" mongodb-version: "5.0" driver-version: "mongodb/mongo-php-driver@master" topology: "server" - os: "ubuntu-20.04" - php-version: "8.0" + php-version: "8.1" mongodb-version: "4.4" driver-version: "mongodb/mongo-php-driver@master" topology: "replica_set" - os: "ubuntu-20.04" - php-version: "8.0" + php-version: "8.1" mongodb-version: "4.4" driver-version: "mongodb/mongo-php-driver@master" topology: "sharded_cluster" diff --git a/.idea/jsonSchemas.xml b/.idea/jsonSchemas.xml new file mode 100644 index 000000000..dcae88975 --- /dev/null +++ b/.idea/jsonSchemas.xml @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + diff --git a/examples/aggregation-builder.php b/examples/aggregation-builder.php index 5f7505db5..015db3fcc 100644 --- a/examples/aggregation-builder.php +++ b/examples/aggregation-builder.php @@ -7,15 +7,17 @@ namespace MongoDB\Examples\AggregationBuilder; -use MongoDB\Builder\Aggregation; +use MongoDB\Builder\Accumulator; use MongoDB\Builder\BuilderEncoder; use MongoDB\Builder\Expression; use MongoDB\Builder\Pipeline; use MongoDB\Builder\Stage; use MongoDB\Client; +use function array_is_list; use function assert; use function getenv; +use function is_array; use function is_object; use function MongoDB\BSON\fromPHP; use function MongoDB\BSON\toRelaxedExtendedJSON; @@ -45,28 +47,18 @@ function toJSON(object $document): string $pipeline = new Pipeline( Stage::group( _id: null, - totalCount: Aggregation::sum(1), - evenCount: Aggregation::sum( - Aggregation::mod( - Expression::fieldPath('randomValue'), - 2, - ), + totalCount: Accumulator::sum(1), + evenCount: Accumulator::sum( + Expression::mod(Expression::numberFieldPath('randomValue'), 2), ), - oddCount: Aggregation::sum( - Aggregation::subtract( + oddCount: Accumulator::sum( + Expression::subtract( 1, - Aggregation::mod( - Expression::fieldPath('randomValue'), - 2, - ), + Expression::mod(Expression::numberFieldPath('randomValue'), 2), ), ), - maxValue: Aggregation::max( - Expression::fieldPath('randomValue'), - ), - minValue: Aggregation::min( - Expression::fieldPath('randomValue'), - ), + maxValue: Accumulator::max(Expression::numberFieldPath('randomValue')), + minValue: Accumulator::min(Expression::numberfieldPath('randomValue')), ), ); @@ -74,6 +66,8 @@ function toJSON(object $document): string $encoder = new BuilderEncoder(); $pipeline = $encoder->encode($pipeline); +assert(is_array($pipeline) && array_is_list($pipeline)); + $cursor = $collection->aggregate($pipeline); foreach ($cursor as $document) { diff --git a/generator/composer.json b/generator/composer.json index 7974a887e..6b8bdaf1f 100644 --- a/generator/composer.json +++ b/generator/composer.json @@ -18,6 +18,7 @@ "mongodb/mongodb": "@dev", "nette/php-generator": "^4", "symfony/console": "^6.3", + "symfony/finder": "^6.3", "symfony/yaml": "^6.3" }, "license": "Apache-2.0", diff --git a/generator/config/accumulator/accumulator.yaml b/generator/config/accumulator/accumulator.yaml new file mode 100644 index 000000000..7921c8c45 --- /dev/null +++ b/generator/config/accumulator/accumulator.yaml @@ -0,0 +1,55 @@ +# $schema: ../schema.json +name: $accumulator + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/' +type: + - accumulator +encode: object +description: | + Defines a custom accumulator function. + New in version 4.4. +arguments: + - + name: init + type: + - string + description: | + Function used to initialize the state. The init function receives its arguments from the initArgs array expression. You can specify the function definition as either BSON type Code or String. + - + name: initArgs + type: + - resolvesToArray + optional: true + description: | + Arguments passed to the init function. + - + name: accumulate + type: + - string + description: | + Function used to accumulate documents. The accumulate function receives its arguments from the current state and accumulateArgs array expression. The result of the accumulate function becomes the new state. You can specify the function definition as either BSON type Code or String. + - + name: accumulateArgs + type: + - resolvesToArray + description: | + Arguments passed to the accumulate function. You can use accumulateArgs to specify what field value(s) to pass to the accumulate function. + - + name: merge + type: + - string + description: | + Function used to merge two internal states. merge must be either a String or Code BSON type. merge returns the combined result of the two merged states. For information on when the merge function is called, see Merge Two States with $merge. + - + name: finalize + type: + - string + optional: true + description: | + Function used to update the result of the accumulation. + - + name: lang + type: + - string + description: | + The language used in the $accumulator code. diff --git a/generator/config/accumulator/addToSet.yaml b/generator/config/accumulator/addToSet.yaml new file mode 100644 index 000000000..a0de8b622 --- /dev/null +++ b/generator/config/accumulator/addToSet.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $addToSet + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/addToSet/' +type: + - accumulator + - window +encode: single +description: | + Returns an array of unique expression values for each group. Order of the array elements is undefined. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/avg.yaml b/generator/config/accumulator/avg.yaml new file mode 100644 index 000000000..0172a251b --- /dev/null +++ b/generator/config/accumulator/avg.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $avg + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/' +type: + - accumulator + - window +encode: single +description: | + Returns an average of numerical values. Ignores non-numeric values. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/accumulator/bottom.yaml b/generator/config/accumulator/bottom.yaml new file mode 100644 index 000000000..3b9156b4b --- /dev/null +++ b/generator/config/accumulator/bottom.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $bottom + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottom/' +type: + - accumulator + - window +encode: object +description: | + Returns the bottom element within a group according to the specified sort order. + New in version 5.2: Available in the $group and $setWindowFields stages. +arguments: + - + name: sortBy + type: + - object # SortSpec + description: | + Specifies the order of results, with syntax similar to $sort. + - + name: output + type: + - expression + description: | + Represents the output for each element in the group and can be any expression. diff --git a/generator/config/accumulator/bottomN.yaml b/generator/config/accumulator/bottomN.yaml new file mode 100644 index 000000000..094a8ca0c --- /dev/null +++ b/generator/config/accumulator/bottomN.yaml @@ -0,0 +1,31 @@ +# $schema: ../schema.json +name: $bottomN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottomN/' +type: + - accumulator + - window +encode: object +description: | + Returns an aggregation of the bottom n elements within a group, according to the specified sort order. If the group contains fewer than n elements, $bottomN returns all elements in the group. + New in version 5.2. + Available in the $group and $setWindowFields stages. +arguments: + - + name: 'n' + type: + - resolvesToInt + description: | + Limits the number of results per group and has to be a positive integral expression that is either a constant or depends on the _id value for $group. + - + name: sortBy + type: + - object # SortSpec + description: | + Specifies the order of results, with syntax similar to $sort. + - + name: output + type: + - expression + description: | + Represents the output for each element in the group and can be any expression. diff --git a/generator/config/accumulator/count.yaml b/generator/config/accumulator/count.yaml new file mode 100644 index 000000000..0e39b25db --- /dev/null +++ b/generator/config/accumulator/count.yaml @@ -0,0 +1,12 @@ +# $schema: ../schema.json +name: $count + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/count-accumulator/' +type: + - accumulator + - window +encode: object +description: | + Returns the number of documents in the group or window. + Distinct from the $count pipeline stage. + New in version 5.0. diff --git a/generator/config/accumulator/covariancePop.yaml b/generator/config/accumulator/covariancePop.yaml new file mode 100644 index 000000000..dca54879a --- /dev/null +++ b/generator/config/accumulator/covariancePop.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $covariancePop + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/covariancePop/' +type: + - window +encode: array +description: | + Returns the population covariance of two numeric expressions. + New in version 5.0. +arguments: + - + name: expression1 + type: + - resolvesToNumber + - + name: expression2 + type: + - resolvesToNumber diff --git a/generator/config/accumulator/covarianceSamp.yaml b/generator/config/accumulator/covarianceSamp.yaml new file mode 100644 index 000000000..713776a40 --- /dev/null +++ b/generator/config/accumulator/covarianceSamp.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $covarianceSamp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/covarianceSamp/' +type: + - window +encode: array +description: | + Returns the sample covariance of two numeric expressions. + New in version 5.0. +arguments: + - + name: expression1 + type: + - resolvesToNumber + - + name: expression2 + type: + - resolvesToNumber diff --git a/generator/config/accumulator/denseRank.yaml b/generator/config/accumulator/denseRank.yaml new file mode 100644 index 000000000..78c5120c5 --- /dev/null +++ b/generator/config/accumulator/denseRank.yaml @@ -0,0 +1,10 @@ +# $schema: ../schema.json +name: $denseRank + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/denseRank/' +type: + - window +encode: object +description: | + Returns the document position (known as the rank) relative to other documents in the $setWindowFields stage partition. There are no gaps in the ranks. Ties receive the same rank. + New in version 5.0. diff --git a/generator/config/accumulator/derivative.yaml b/generator/config/accumulator/derivative.yaml new file mode 100644 index 000000000..fade1685d --- /dev/null +++ b/generator/config/accumulator/derivative.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $derivative + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/derivative/' +type: + - window +encode: object +description: | + Returns the average rate of change within the specified window. + New in version 5.0. +arguments: + - + name: input + type: + - resolvesToNumber + - resolvesToDate + - + name: unit + type: + - string + optional: true + description: | + A string that specifies the time unit. Use one of these strings: "week", "day","hour", "minute", "second", "millisecond". + If the sortBy field is not a date, you must omit a unit. If you specify a unit, you must specify a date in the sortBy field. diff --git a/generator/config/accumulator/documentNumber.yaml b/generator/config/accumulator/documentNumber.yaml new file mode 100644 index 000000000..372c22d33 --- /dev/null +++ b/generator/config/accumulator/documentNumber.yaml @@ -0,0 +1,10 @@ +# $schema: ../schema.json +name: $documentNumber + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/documentNumber/' +type: + - window +encode: object +description: | + Returns the position of a document (known as the document number) in the $setWindowFields stage partition. Ties result in different adjacent document numbers. + New in version 5.0. diff --git a/generator/config/accumulator/expMovingAvg.yaml b/generator/config/accumulator/expMovingAvg.yaml new file mode 100644 index 000000000..f6fc68011 --- /dev/null +++ b/generator/config/accumulator/expMovingAvg.yaml @@ -0,0 +1,31 @@ +# $schema: ../schema.json +name: $expMovingAvg +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/expMovingAvg/' +type: + - window +encode: object +description: | + Returns the exponential moving average for the numeric expression. + New in version 5.0. +arguments: + - + name: input + type: + - resolvesToNumber + - + name: 'N' + type: + - int + optional: true + description: | + An integer that specifies the number of historical documents that have a significant mathematical weight in the exponential moving average calculation, with the most recent documents contributing the most weight. + You must specify either N or alpha. You cannot specify both. + The N value is used in this formula to calculate the current result based on the expression value from the current document being read and the previous result of the calculation: + - + name: alpha + type: + - double + optional: true + description: | + A double that specifies the exponential decay value to use in the exponential moving average calculation. A higher alpha value assigns a lower mathematical significance to previous results from the calculation. + You must specify either N or alpha. You cannot specify both. diff --git a/generator/config/accumulator/first.yaml b/generator/config/accumulator/first.yaml new file mode 100644 index 000000000..43d2d8d9c --- /dev/null +++ b/generator/config/accumulator/first.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $first + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/first/' +type: + - accumulator + - window +encode: single +description: | + Returns the result of an expression for the first document in a group or window. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/firstN.yaml b/generator/config/accumulator/firstN.yaml new file mode 100644 index 000000000..5136a3d84 --- /dev/null +++ b/generator/config/accumulator/firstN.yaml @@ -0,0 +1,23 @@ +# $schema: ../schema.json +name: $firstN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/firstN/' +type: + - accumulator + - window +encode: object +description: | + Returns a specified number of elements from the beginning of an array. Distinct from the $firstN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $firstN returns. diff --git a/generator/config/accumulator/last.yaml b/generator/config/accumulator/last.yaml new file mode 100644 index 000000000..1d8a75d36 --- /dev/null +++ b/generator/config/accumulator/last.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $last + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/last/' +type: + - accumulator + - window +encode: single +description: | + Returns the result of an expression for the last document in a group or window. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/lastN.yaml b/generator/config/accumulator/lastN.yaml new file mode 100644 index 000000000..5f44a852d --- /dev/null +++ b/generator/config/accumulator/lastN.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $lastN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lastN/' +type: + - window +encode: object +description: | + Returns a specified number of elements from the end of an array. Distinct from the $lastN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $firstN returns. diff --git a/generator/config/accumulator/max.yaml b/generator/config/accumulator/max.yaml new file mode 100644 index 000000000..efb6ceb76 --- /dev/null +++ b/generator/config/accumulator/max.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $max + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/max/' +type: + - accumulator + - window +encode: single +description: | + Returns the maximum value that results from applying an expression to each document. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/maxN.yaml b/generator/config/accumulator/maxN.yaml new file mode 100644 index 000000000..8598d4429 --- /dev/null +++ b/generator/config/accumulator/maxN.yaml @@ -0,0 +1,23 @@ +# $schema: ../schema.json +name: $maxN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxN/' +type: + - accumulator + - window +encode: object +description: | + Returns the n largest values in an array. Distinct from the $maxN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return the maximal n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. diff --git a/generator/config/accumulator/median.yaml b/generator/config/accumulator/median.yaml new file mode 100644 index 000000000..a4e637954 --- /dev/null +++ b/generator/config/accumulator/median.yaml @@ -0,0 +1,28 @@ +# $schema: ../schema.json +name: $median + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/median/' +type: + - accumulator + - window +encode: object +description: | + Returns an approximation of the median, the 50th percentile, as a scalar value. + New in version 7.0. + This operator is available as an accumulator in these stages: + $group + $setWindowFields + It is also available as an aggregation expression. +arguments: + - + name: input + type: + - resolvesToNumber + description: | + $median calculates the 50th percentile value of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $median calculation ignores it. + - + name: method + type: + - string # AccumulatorPercentile + description: | + The method that mongod uses to calculate the 50th percentile value. The method must be 'approximate'. diff --git a/generator/config/accumulator/mergeObjects.yaml b/generator/config/accumulator/mergeObjects.yaml new file mode 100644 index 000000000..19e705fe2 --- /dev/null +++ b/generator/config/accumulator/mergeObjects.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $mergeObjects + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/mergeObjects/' +type: + - accumulator +encode: single +description: | + Combines multiple documents into a single document. +arguments: + - + name: document + type: + - resolvesToObject + variadic: array + description: | + Any valid expression that resolves to a document. diff --git a/generator/config/accumulator/min.yaml b/generator/config/accumulator/min.yaml new file mode 100644 index 000000000..9bd60b893 --- /dev/null +++ b/generator/config/accumulator/min.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $min + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/min/' +type: + - accumulator + - window +encode: single +description: | + Returns the minimum value that results from applying an expression to each document. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/minN.yaml b/generator/config/accumulator/minN.yaml new file mode 100644 index 000000000..df7f990ef --- /dev/null +++ b/generator/config/accumulator/minN.yaml @@ -0,0 +1,23 @@ +# $schema: ../schema.json +name: $minN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/minN/' +type: + - accumulator + - window +encode: object +description: | + Returns the n smallest values in an array. Distinct from the $minN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return the maximal n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. diff --git a/generator/config/accumulator/percentile.yaml b/generator/config/accumulator/percentile.yaml new file mode 100644 index 000000000..31db8e2e0 --- /dev/null +++ b/generator/config/accumulator/percentile.yaml @@ -0,0 +1,38 @@ +# $schema: ../schema.json +name: $percentile + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/percentile/' +type: + - accumulator + - window +encode: object +description: | + Returns an array of scalar values that correspond to specified percentile values. + New in version 7.0. + + This operator is available as an accumulator in these stages: + $group + + $setWindowFields + + It is also available as an aggregation expression. +arguments: + - + name: input + type: + - resolvesToNumber + description: | + $percentile calculates the percentile values of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $percentile calculation ignores it. + - + name: p + type: + - resolvesToArray # of resolvesToNumber + description: | + $percentile calculates a percentile value for each element in p. The elements represent percentages and must evaluate to numeric values in the range 0.0 to 1.0, inclusive. + $percentile returns results in the same order as the elements in p. + - + name: method + type: + - string # AccumulatorPercentile + description: | + The method that mongod uses to calculate the percentile value. The method must be 'approximate'. diff --git a/generator/config/accumulator/push.yaml b/generator/config/accumulator/push.yaml new file mode 100644 index 000000000..cc6e23ef9 --- /dev/null +++ b/generator/config/accumulator/push.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $push + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/push/' +type: + - accumulator + - window +encode: single +description: | + Returns an array of values that result from applying an expression to each document. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/accumulator/shift.yaml b/generator/config/accumulator/shift.yaml new file mode 100644 index 000000000..f9754cec0 --- /dev/null +++ b/generator/config/accumulator/shift.yaml @@ -0,0 +1,35 @@ +# $schema: ../schema.json +name: $shift + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/shift/' +type: + - window +encode: object +description: | + Returns the value from an expression applied to a document in a specified position relative to the current document in the $setWindowFields stage partition. + New in version 5.0. +arguments: + - + name: output + type: + - expression + description: | + Specifies an expression to evaluate and return in the output. + - + name: by + type: + - int + description: | + Specifies an integer with a numeric document position relative to the current document in the output. + For example: + 1 specifies the document position after the current document. + -1 specifies the document position before the current document. + -2 specifies the document position that is two positions before the current document. + - + name: default + type: + - expression + description: | + Specifies an optional default expression to evaluate if the document position is outside of the implicit $setWindowFields stage window. The implicit window contains all the documents in the partition. + The default expression must evaluate to a constant value. + If you do not specify a default expression, $shift returns null for documents whose positions are outside of the implicit $setWindowFields stage window. diff --git a/generator/config/accumulator/stdDevPop.yaml b/generator/config/accumulator/stdDevPop.yaml new file mode 100644 index 000000000..c48e2dae8 --- /dev/null +++ b/generator/config/accumulator/stdDevPop.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $stdDevPop + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevPop/' +type: + - accumulator +encode: single +description: | + Calculates the population standard deviation of the input values. Use if the values encompass the entire population of data you want to represent and do not wish to generalize about a larger population. $stdDevPop ignores non-numeric values. + If the values represent only a sample of a population of data from which to generalize about the population, use $stdDevSamp instead. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/accumulator/stdDevSamp.yaml b/generator/config/accumulator/stdDevSamp.yaml new file mode 100644 index 000000000..1394417d2 --- /dev/null +++ b/generator/config/accumulator/stdDevSamp.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $stdDevSamp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevSamp/' +type: + - accumulator +encode: single +description: | + Calculates the sample standard deviation of the input values. Use if the values encompass a sample of a population of data from which to generalize about the population. $stdDevSamp ignores non-numeric values. + If the values represent the entire population of data or you do not wish to generalize about a larger population, use $stdDevPop instead. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/accumulator/sum.yaml b/generator/config/accumulator/sum.yaml new file mode 100644 index 000000000..46f6505af --- /dev/null +++ b/generator/config/accumulator/sum.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $sum + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum/' +type: + - accumulator + - window +encode: single +description: | + Returns a sum of numerical values. Ignores non-numeric values. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/accumulator/top.yaml b/generator/config/accumulator/top.yaml new file mode 100644 index 000000000..ff3a677b6 --- /dev/null +++ b/generator/config/accumulator/top.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $top + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/top/' +type: + - accumulator +encode: object +description: | + Returns the top element within a group according to the specified sort order. + New in version 5.2. + + Available in the $group and $setWindowFields stages. +arguments: + - + name: sortBy + type: + - object # SortSpec + description: | + Specifies the order of results, with syntax similar to $sort. + - + name: output + type: + - expression + description: | + Represents the output for each element in the group and can be any expression. diff --git a/generator/config/accumulator/topN.yaml b/generator/config/accumulator/topN.yaml new file mode 100644 index 000000000..bdf683d2c --- /dev/null +++ b/generator/config/accumulator/topN.yaml @@ -0,0 +1,31 @@ +# $schema: ../schema.json +name: $topN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/topN/' +type: + - accumulator +encode: object +description: | + Returns an aggregation of the top n fields within a group, according to the specified sort order. + New in version 5.2. + + Available in the $group and $setWindowFields stages. +arguments: + - + name: 'n' + type: + - resolvesToInt + description: | + limits the number of results per group and has to be a positive integral expression that is either a constant or depends on the _id value for $group. + - + name: sortBy + type: + - object # SortSpec + description: | + Specifies the order of results, with syntax similar to $sort. + - + name: output + type: + - expression + description: | + Represents the output for each element in the group and can be any expression. diff --git a/generator/config/definitions.php b/generator/config/definitions.php new file mode 100644 index 000000000..e0b5e66c9 --- /dev/null +++ b/generator/config/definitions.php @@ -0,0 +1,63 @@ + __DIR__ . '/stage', + 'namespace' => 'MongoDB\\Builder\\Stage', + 'classNameSuffix' => 'Stage', + 'generators' => [ + OperatorClassGenerator::class, + OperatorFactoryGenerator::class, + ], + ], + + // Aggregation Pipeline Accumulator and Window Operators + [ + 'configFiles' => __DIR__ . '/accumulator', + 'namespace' => 'MongoDB\\Builder\\Accumulator', + 'classNameSuffix' => 'Accumulator', + 'generators' => [ + OperatorClassGenerator::class, + OperatorFactoryGenerator::class, + ], + ], + + // Aggregation Pipeline Expression + [ + 'configFiles' => __DIR__ . '/expression', + 'namespace' => 'MongoDB\\Builder\\Expression', + 'classNameSuffix' => 'Operator', + 'generators' => [ + OperatorClassGenerator::class, + OperatorFactoryGenerator::class, + ], + ], + + // Query Operators + [ + 'configFiles' => __DIR__ . '/query', + 'namespace' => 'MongoDB\\Builder\\Query', + 'classNameSuffix' => 'Operator', + 'generators' => [ + OperatorClassGenerator::class, + OperatorFactoryGenerator::class, + ], + ], + + // Projection Operators + [ + 'configFiles' => __DIR__ . '/projection', + 'namespace' => 'MongoDB\\Builder\\Projection', + 'classNameSuffix' => 'Operator', + 'generators' => [ + OperatorClassGenerator::class, + OperatorFactoryGenerator::class, + ], + ], +]; diff --git a/generator/config/expression/abs.yaml b/generator/config/expression/abs.yaml new file mode 100644 index 000000000..d06f8a841 --- /dev/null +++ b/generator/config/expression/abs.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $abs + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/abs/' +type: + - resolvesToNumber +encode: single +description: | + Returns the absolute value of a number. +arguments: + - + name: value + type: + - resolvesToNumber diff --git a/generator/config/expression/acos.yaml b/generator/config/expression/acos.yaml new file mode 100644 index 000000000..07d0ea2d3 --- /dev/null +++ b/generator/config/expression/acos.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $acos +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/acos/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse cosine (arc cosine) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $acos takes any valid expression that resolves to a number between -1 and 1, e.g. -1 <= value <= 1. + $acos returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $acos returns values as a double. $acos can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/acosh.yaml b/generator/config/expression/acosh.yaml new file mode 100644 index 000000000..7a717ea04 --- /dev/null +++ b/generator/config/expression/acosh.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $acosh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/acosh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse hyperbolic cosine (hyperbolic arc cosine) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $acosh takes any valid expression that resolves to a number between 1 and +Infinity, e.g. 1 <= value <= +Infinity. + $acosh returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $acosh returns values as a double. $acosh can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/add.yaml b/generator/config/expression/add.yaml new file mode 100644 index 000000000..379c0c285 --- /dev/null +++ b/generator/config/expression/add.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $add + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/add/' +type: + - resolvesToNumber + - resolvesToDate +encode: array +description: | + Adds numbers to return the sum, or adds numbers and a date to return a new date. If adding numbers and a date, treats the numbers as milliseconds. Accepts any number of argument expressions, but at most, one expression can resolve to a date. +arguments: + - + name: expression + type: + - resolvesToNumber + - resolvesToDate + variadic: array + description: | + The arguments can be any valid expression as long as they resolve to either all numbers or to numbers and a date. diff --git a/generator/config/expression/allElementsTrue.yaml b/generator/config/expression/allElementsTrue.yaml new file mode 100644 index 000000000..4bc67e53f --- /dev/null +++ b/generator/config/expression/allElementsTrue.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $allElementsTrue + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/allElementsTrue/' +type: + - resolvesToBool +encode: array +description: | + Returns true if no element of a set evaluates to false, otherwise, returns false. Accepts a single argument expression. +arguments: + - + name: expression + type: + - resolvesToArray + variadic: array diff --git a/generator/config/expression/and.yaml b/generator/config/expression/and.yaml new file mode 100644 index 000000000..3f0b2bd4a --- /dev/null +++ b/generator/config/expression/and.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $and + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/and/' +type: + - resolvesToBool +encode: single +description: | + Returns true only when all its expressions evaluate to true. Accepts any number of argument expressions. +arguments: + - + name: expression + type: + - expression + - resolvesToBool + - resolvesToNumber + - resolvesToString + - resolvesToNull + variadic: array diff --git a/generator/config/expression/anyElementTrue.yaml b/generator/config/expression/anyElementTrue.yaml new file mode 100644 index 000000000..76ddb82c4 --- /dev/null +++ b/generator/config/expression/anyElementTrue.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $anyElementTrue + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/anyElementTrue/' +type: + - resolvesToBool +encode: array +description: | + Returns true if any elements of a set evaluate to true; otherwise, returns false. Accepts a single argument expression. +arguments: + - + name: expression + type: + - resolvesToArray diff --git a/generator/config/expression/arrayElemAt.yaml b/generator/config/expression/arrayElemAt.yaml new file mode 100644 index 000000000..44358453f --- /dev/null +++ b/generator/config/expression/arrayElemAt.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $arrayElemAt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/arrayElemAt/' +type: + - resolvesToAny +encode: array +description: | + Returns the element at the specified array index. +arguments: + - + name: array + type: + - resolvesToArray + - + name: idx + type: + - resolvesToInt diff --git a/generator/config/expression/arrayToObject.yaml b/generator/config/expression/arrayToObject.yaml new file mode 100644 index 000000000..78e5055c8 --- /dev/null +++ b/generator/config/expression/arrayToObject.yaml @@ -0,0 +1,13 @@ +# $schema: ../schema.json +name: $arrayToObject +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/arrayToObject/' +type: + - resolvesToObject +encode: array +description: | + Converts an array of key value pairs to a document. +arguments: + - + name: array + type: + - resolvesToArray diff --git a/generator/config/expression/asin.yaml b/generator/config/expression/asin.yaml new file mode 100644 index 000000000..8cfe7754a --- /dev/null +++ b/generator/config/expression/asin.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $asin + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/asin/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse sin (arc sine) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $asin takes any valid expression that resolves to a number between -1 and 1, e.g. -1 <= value <= 1. + $asin returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $asin returns values as a double. $asin can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/asinh.yaml b/generator/config/expression/asinh.yaml new file mode 100644 index 000000000..1e8479fc9 --- /dev/null +++ b/generator/config/expression/asinh.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $asinh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/asinh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse hyperbolic sine (hyperbolic arc sine) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $asinh takes any valid expression that resolves to a number. + $asinh returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $asinh returns values as a double. $asinh can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/atan.yaml b/generator/config/expression/atan.yaml new file mode 100644 index 000000000..2f6bd586e --- /dev/null +++ b/generator/config/expression/atan.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $atan + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/atan/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse tangent (arc tangent) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $atan takes any valid expression that resolves to a number. + $atan returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $atan returns values as a double. $atan can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/atan2.yaml b/generator/config/expression/atan2.yaml new file mode 100644 index 000000000..f4312f8de --- /dev/null +++ b/generator/config/expression/atan2.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $atan2 +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/atan2/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: array +description: | + Returns the inverse tangent (arc tangent) of y / x in radians, where y and x are the first and second values passed to the expression respectively. +arguments: + - + name: 'y' + type: + - resolvesToNumber + description: | + $atan2 takes any valid expression that resolves to a number. + $atan2 returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $atan returns values as a double. $atan2 can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. + - + name: x + type: + - resolvesToNumber diff --git a/generator/config/expression/atanh.yaml b/generator/config/expression/atanh.yaml new file mode 100644 index 000000000..0d982abfa --- /dev/null +++ b/generator/config/expression/atanh.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $atanh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $atanh takes any valid expression that resolves to a number between -1 and 1, e.g. -1 <= value <= 1. + $atanh returns values in radians. Use $radiansToDegrees operator to convert the output value from radians to degrees. + By default $atanh returns values as a double. $atanh can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/avg.yaml b/generator/config/expression/avg.yaml new file mode 100644 index 000000000..6056fca79 --- /dev/null +++ b/generator/config/expression/avg.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $avg + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/' +type: + - resolvesToNumber +encode: single +description: | + Returns an average of numerical values. Ignores non-numeric values. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber + variadic: array diff --git a/generator/config/expression/binarySize.yaml b/generator/config/expression/binarySize.yaml new file mode 100644 index 000000000..f988a4e21 --- /dev/null +++ b/generator/config/expression/binarySize.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $binarySize + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/binarySize/' +type: + - resolvesToInt +encode: single +description: | + Returns the size of a given string or binary data value's content in bytes. +arguments: + - + name: expression + type: + - resolvesToString + - resolvesToBinData + - resolvesToNull diff --git a/generator/config/expression/bitAnd.yaml b/generator/config/expression/bitAnd.yaml new file mode 100644 index 000000000..060e98dfe --- /dev/null +++ b/generator/config/expression/bitAnd.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $bitAnd +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitAnd/' +type: + - resolvesToInt + - resolvesToLong +encode: single +description: | + Returns the result of a bitwise and operation on an array of int or long values. + New in version 6.3. +arguments: + - + name: expression + type: + - resolvesToInt + - resolvesToLong + variadic: array diff --git a/generator/config/expression/bitNot.yaml b/generator/config/expression/bitNot.yaml new file mode 100644 index 000000000..6c915f781 --- /dev/null +++ b/generator/config/expression/bitNot.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $bitNot + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitNot/' +type: + - resolvesToInt + - resolvesToLong +encode: single +description: | + Returns the result of a bitwise not operation on a single argument or an array that contains a single int or long value. + New in version 6.3. +arguments: + - + name: expression + type: + - resolvesToInt + - resolvesToLong diff --git a/generator/config/expression/bitOr.yaml b/generator/config/expression/bitOr.yaml new file mode 100644 index 000000000..83e054056 --- /dev/null +++ b/generator/config/expression/bitOr.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $bitOr + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitOr/' +type: + - resolvesToInt + - resolvesToLong +encode: single +description: | + Returns the result of a bitwise or operation on an array of int or long values. + New in version 6.3. +arguments: + - + name: expression + type: + - resolvesToInt + - resolvesToLong + variadic: array diff --git a/generator/config/expression/bitXor.yaml b/generator/config/expression/bitXor.yaml new file mode 100644 index 000000000..4edf940ca --- /dev/null +++ b/generator/config/expression/bitXor.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $bitXor + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitXor/' +type: + - resolvesToInt + - resolvesToLong +encode: single +description: | + Returns the result of a bitwise xor (exclusive or) operation on an array of int and long values. + New in version 6.3. +arguments: + - + name: expression + type: + - resolvesToInt + - resolvesToLong + variadic: array diff --git a/generator/config/expression/bsonSize.yaml b/generator/config/expression/bsonSize.yaml new file mode 100644 index 000000000..9f3caf3c8 --- /dev/null +++ b/generator/config/expression/bsonSize.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $bsonSize + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonSize/' +type: + - resolvesToInt +encode: single +description: | + Returns the size in bytes of a given document (i.e. bsontype Object) when encoded as BSON. +arguments: + - + name: object + type: + - resolvesToObject + - resolvesToNull diff --git a/generator/config/expression/ceil.yaml b/generator/config/expression/ceil.yaml new file mode 100644 index 000000000..fcad982d7 --- /dev/null +++ b/generator/config/expression/ceil.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $ceil + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/ceil/' +type: + - resolvesToInt +encode: single +description: | + Returns the smallest integer greater than or equal to the specified number. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + If the argument resolves to a value of null or refers to a field that is missing, $ceil returns null. If the argument resolves to NaN, $ceil returns NaN. diff --git a/generator/config/expression/cmp.yaml b/generator/config/expression/cmp.yaml new file mode 100644 index 000000000..8a55cfc94 --- /dev/null +++ b/generator/config/expression/cmp.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $cmp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/cmp/' +type: + - resolvesToInt +encode: array +description: | + Returns 0 if the two values are equivalent, 1 if the first value is greater than the second, and -1 if the first value is less than the second. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/concat.yaml b/generator/config/expression/concat.yaml new file mode 100644 index 000000000..550426ea1 --- /dev/null +++ b/generator/config/expression/concat.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $concat + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/concat/' +type: + - resolvesToString +encode: single +description: | + Concatenates any number of strings. +arguments: + - + name: expression + type: + - resolvesToString + variadic: array diff --git a/generator/config/expression/concatArrays.yaml b/generator/config/expression/concatArrays.yaml new file mode 100644 index 000000000..5f2a7ed13 --- /dev/null +++ b/generator/config/expression/concatArrays.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $concatArrays + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/concatArrays/' +type: + - resolvesToArray +encode: single +description: | + Concatenates arrays to return the concatenated array. +arguments: + - + name: array + type: + - resolvesToArray + variadic: array diff --git a/generator/config/expression/cond.yaml b/generator/config/expression/cond.yaml new file mode 100644 index 000000000..386705fcb --- /dev/null +++ b/generator/config/expression/cond.yaml @@ -0,0 +1,21 @@ +# $schema: ../schema.json +name: $cond +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond/' +type: + - resolvesToAny +encode: object +description: | + A ternary operator that evaluates one expression, and depending on the result, returns the value of one of the other two expressions. Accepts either three expressions in an ordered list or three named parameters. +arguments: + - + name: if + type: + - resolvesToBool + - + name: then + type: + - expression + - + name: else + type: + - expression diff --git a/generator/config/expression/convert.yaml b/generator/config/expression/convert.yaml new file mode 100644 index 000000000..5fe67388b --- /dev/null +++ b/generator/config/expression/convert.yaml @@ -0,0 +1,36 @@ +# $schema: ../schema.json +name: $convert + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert/' +type: + - resolvesToAny +encode: object +description: | + Converts a value to a specified type. + New in version 4.0. +arguments: + - + name: input + type: + - expression + - + name: to + type: + - resolvesToString + - resolvesToInt + - + name: onError + type: + - expression + optional: true + description: | + The value to return on encountering an error during conversion, including unsupported type conversions. The arguments can be any valid expression. + If unspecified, the operation throws an error upon encountering an error and stops. + - + name: onNull + type: + - expression + optional: true + description: | + The value to return if the input is null or missing. The arguments can be any valid expression. + If unspecified, $convert returns null if the input is null or missing. diff --git a/generator/config/expression/cos.yaml b/generator/config/expression/cos.yaml new file mode 100644 index 000000000..e7c474f07 --- /dev/null +++ b/generator/config/expression/cos.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $cos + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/cos/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the cosine of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $cos takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + By default $cos returns values as a double. $cos can also return values as a 128-bit decimal as long as the resolves to a 128-bit decimal value. diff --git a/generator/config/expression/cosh.yaml b/generator/config/expression/cosh.yaml new file mode 100644 index 000000000..3b5ea7dc0 --- /dev/null +++ b/generator/config/expression/cosh.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $cosh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/cosh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the hyperbolic cosine of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $cosh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + By default $cosh returns values as a double. $cosh can also return values as a 128-bit decimal if the resolves to a 128-bit decimal value. diff --git a/generator/config/expression/dateAdd.yaml b/generator/config/expression/dateAdd.yaml new file mode 100644 index 000000000..4c77e8353 --- /dev/null +++ b/generator/config/expression/dateAdd.yaml @@ -0,0 +1,36 @@ +# $schema: ../schema.json +name: $dateAdd + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateAdd/' +type: + - resolvesToDate +encode: object +description: | + Adds a number of time units to a date object. +arguments: + - + name: startDate + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The beginning date, in UTC, for the addition operation. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: unit + type: + - resolvesToString + description: | + The unit used to measure the amount of time added to the startDate. + - + name: amount + type: + - resolvesToInt + - resolvesToLong + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/dateDiff.yaml b/generator/config/expression/dateDiff.yaml new file mode 100644 index 000000000..c05da6c5b --- /dev/null +++ b/generator/config/expression/dateDiff.yaml @@ -0,0 +1,46 @@ +# $schema: ../schema.json +name: $dateDiff + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateDiff/' +type: + - resolvesToInt +encode: object +description: | + Returns the difference between two dates. +arguments: + - + name: startDate + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The start of the time period. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: endDate + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The end of the time period. The endDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: unit + type: + - resolvesToString + description: | + The time measurement unit between the startDate and endDate + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + - + name: startOfWeek + type: + - resolvesToString + optional: true + description: | + Used when the unit is equal to week. Defaults to Sunday. The startOfWeek parameter is an expression that resolves to a case insensitive string diff --git a/generator/config/expression/dateFromParts.yaml b/generator/config/expression/dateFromParts.yaml new file mode 100644 index 000000000..efd9e7ca8 --- /dev/null +++ b/generator/config/expression/dateFromParts.yaml @@ -0,0 +1,85 @@ +# $schema: ../schema.json +name: $dateFromParts + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromParts/' +type: + - resolvesToDate +encode: object +description: | + Constructs a BSON Date object given the date's constituent parts. +arguments: + - + name: year + type: + - resolvesToNumber + description: | + Calendar year. Can be any expression that evaluates to a number. + - + name: isoWeekYear + type: + - resolvesToNumber + description: | + ISO Week Date Year. Can be any expression that evaluates to a number. + - + name: month + type: + - resolvesToNumber + optional: true + description: | + Month. Defaults to 1. + - + name: isoWeek + type: + - resolvesToNumber + optional: true + description: | + Week of year. Defaults to 1. + - + name: day + type: + - resolvesToNumber + optional: true + description: | + Day of month. Defaults to 1. + - + name: isoDayOfWeek + type: + - resolvesToNumber + optional: true + description: | + Day of week (Monday 1 - Sunday 7). Defaults to 1. + - + name: hour + type: + - resolvesToNumber + optional: true + description: | + Hour. Defaults to 0. + - + name: minute + type: + - resolvesToNumber + optional: true + description: | + Minute. Defaults to 0. + - + name: second + type: + - resolvesToNumber + optional: true + description: | + Second. Defaults to 0. + - + name: millisecond + type: + - resolvesToNumber + optional: true + description: | + Millisecond. Defaults to 0. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/dateFromString.yaml b/generator/config/expression/dateFromString.yaml new file mode 100644 index 000000000..77e9d0ab7 --- /dev/null +++ b/generator/config/expression/dateFromString.yaml @@ -0,0 +1,47 @@ +# $schema: ../schema.json +name: $dateFromString + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromString/' +type: + - resolvesToDate +encode: object +description: | + Converts a date/time string to a date object. +arguments: + - + name: dateString + type: + - resolvesToString + description: | + The date/time string to convert to a date object. + - + name: format + type: + - resolvesToString + optional: true + description: | + The date format specification of the dateString. The format can be any expression that evaluates to a string literal, containing 0 or more format specifiers. + If unspecified, $dateFromString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format but accepts a variety of formats and attempts to parse the dateString if possible. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The time zone to use to format the date. + - + name: onError + type: + - expression + optional: true + description: | + If $dateFromString encounters an error while parsing the given dateString, it outputs the result value of the provided onError expression. This result value can be of any type. + If you do not specify onError, $dateFromString throws an error if it cannot parse dateString. + - + name: onNull + type: + - expression + optional: true + description: | + If the dateString provided to $dateFromString is null or missing, it outputs the result value of the provided onNull expression. This result value can be of any type. + If you do not specify onNull and dateString is null or missing, then $dateFromString outputs null. diff --git a/generator/config/expression/dateSubtract.yaml b/generator/config/expression/dateSubtract.yaml new file mode 100644 index 000000000..2e0366c72 --- /dev/null +++ b/generator/config/expression/dateSubtract.yaml @@ -0,0 +1,36 @@ +# $schema: ../schema.json +name: $dateSubtract + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateSubtract/' +type: + - resolvesToDate +encode: object +description: | + Subtracts a number of time units from a date object. +arguments: + - + name: startDate + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The beginning date, in UTC, for the addition operation. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: unit + type: + - resolvesToString + description: | + The unit used to measure the amount of time added to the startDate. + - + name: amount + type: + - resolvesToInt + - resolvesToLong + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/dateToParts.yaml b/generator/config/expression/dateToParts.yaml new file mode 100644 index 000000000..0e5eaac43 --- /dev/null +++ b/generator/config/expression/dateToParts.yaml @@ -0,0 +1,32 @@ +# $schema: ../schema.json +name: $dateToParts + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToParts/' +type: + - resolvesToObject +encode: object +description: | + Returns a document containing the constituent parts of a date. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The input date for which to return parts. date can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + - + name: iso8601 + type: + - bool + optional: true + description: | + If set to true, modifies the output document to use ISO week date fields. Defaults to false. diff --git a/generator/config/expression/dateToString.yaml b/generator/config/expression/dateToString.yaml new file mode 100644 index 000000000..b4027f907 --- /dev/null +++ b/generator/config/expression/dateToString.yaml @@ -0,0 +1,41 @@ +# $schema: ../schema.json +name: $dateToString + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToString/' +type: + - resolvesToString +encode: object +description: | + Returns the date as a formatted string. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to convert to string. Must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: format + type: + - resolvesToString + optional: true + description: | + The date format specification of the dateString. The format can be any expression that evaluates to a string literal, containing 0 or more format specifiers. + If unspecified, $dateFromString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format but accepts a variety of formats and attempts to parse the dateString if possible. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The time zone to use to format the date. + - + name: onNull + type: + - expression + optional: true + description: | + The value to return if the date is null or missing. + If unspecified, $dateToString returns null if the date is null or missing. diff --git a/generator/config/expression/dateTrunc.yaml b/generator/config/expression/dateTrunc.yaml new file mode 100644 index 000000000..10174586c --- /dev/null +++ b/generator/config/expression/dateTrunc.yaml @@ -0,0 +1,48 @@ +# $schema: ../schema.json +name: $dateTrunc + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateTrunc/' +type: + - resolvesToDate +encode: object +description: | + Truncates a date. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to truncate, specified in UTC. The date can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: unit + type: + - resolvesToString + description: | + The unit of time, specified as an expression that must resolve to one of these strings: year, quarter, week, month, day, hour, minute, second. + Together, binSize and unit specify the time period used in the $dateTrunc calculation. + - + name: binSize + type: + - resolvesToNumber + optional: true + description: | + The numeric time value, specified as an expression that must resolve to a positive non-zero number. Defaults to 1. + Together, binSize and unit specify the time period used in the $dateTrunc calculation. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + - + name: startOfWeek + type: + - string + optional: true + description: | + The start of the week. Used when + unit is week. Defaults to Sunday. diff --git a/generator/config/expression/dayOfMonth.yaml b/generator/config/expression/dayOfMonth.yaml new file mode 100644 index 000000000..81794f60f --- /dev/null +++ b/generator/config/expression/dayOfMonth.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $dayOfMonth + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfMonth/' +type: + - resolvesToInt +encode: object +description: | + Returns the day of the month for a date as a number between 1 and 31. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/dayOfWeek.yaml b/generator/config/expression/dayOfWeek.yaml new file mode 100644 index 000000000..f1fee7bc5 --- /dev/null +++ b/generator/config/expression/dayOfWeek.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $dayOfWeek + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfWeek/' +type: + - resolvesToInt +encode: object +description: | + Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/dayOfYear.yaml b/generator/config/expression/dayOfYear.yaml new file mode 100644 index 000000000..1fc74223b --- /dev/null +++ b/generator/config/expression/dayOfYear.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $dayOfYear + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfYear/' +type: + - resolvesToInt +encode: object +description: | + Returns the day of the year for a date as a number between 1 and 366 (leap year). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/degreesToRadians.yaml b/generator/config/expression/degreesToRadians.yaml new file mode 100644 index 000000000..58fec8fd3 --- /dev/null +++ b/generator/config/expression/degreesToRadians.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $degreesToRadians + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/degreesToRadians/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Converts a value from degrees to radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $degreesToRadians takes any valid expression that resolves to a number. + By default $degreesToRadians returns values as a double. $degreesToRadians can also return values as a 128-bit decimal as long as the resolves to a 128-bit decimal value. diff --git a/generator/config/expression/divide.yaml b/generator/config/expression/divide.yaml new file mode 100644 index 000000000..98845acfd --- /dev/null +++ b/generator/config/expression/divide.yaml @@ -0,0 +1,20 @@ +# $schema: ../schema.json +name: $divide + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/divide/' +type: + - resolvesToDouble +encode: array +description: | + Returns the result of dividing the first number by the second. Accepts two argument expressions. +arguments: + - + name: dividend + type: + - resolvesToNumber + description: | + The first argument is the dividend, and the second argument is the divisor; i.e. the first argument is divided by the second argument. + - + name: divisor + type: + - resolvesToNumber diff --git a/generator/config/expression/eq.yaml b/generator/config/expression/eq.yaml new file mode 100644 index 000000000..6545240dd --- /dev/null +++ b/generator/config/expression/eq.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $eq + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/eq/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the values are equivalent. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/exp.yaml b/generator/config/expression/exp.yaml new file mode 100644 index 000000000..e807dc8b4 --- /dev/null +++ b/generator/config/expression/exp.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $exp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/exp/' +type: + - resolvesToDouble +encode: single +description: | + Raises e to the specified exponent. +arguments: + - + name: exponent + type: + - resolvesToNumber diff --git a/generator/config/expression/filter.yaml b/generator/config/expression/filter.yaml new file mode 100644 index 000000000..626304b91 --- /dev/null +++ b/generator/config/expression/filter.yaml @@ -0,0 +1,35 @@ +# $schema: ../schema.json +name: $filter + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter/' +type: + - resolvesToArray +encode: object +description: | + Selects a subset of the array to return an array with only the elements that match the filter condition. +arguments: + - + name: input + type: + - resolvesToArray + - + name: cond + type: + - resolvesToBool + description: | + An expression that resolves to a boolean value used to determine if an element should be included in the output array. The expression references each element of the input array individually with the variable name specified in as. + - + name: as + type: + - string + optional: true + description: | + A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this. + - + name: limit + type: + - resolvesToInt + optional: true + description: | + A number expression that restricts the number of matching array elements that $filter returns. You cannot specify a limit less than 1. The matching array elements are returned in the order they appear in the input array. + If the specified limit is greater than the number of matching array elements, $filter returns all matching array elements. If the limit is null, $filter returns all matching array elements. diff --git a/generator/config/expression/floor.yaml b/generator/config/expression/floor.yaml new file mode 100644 index 000000000..13827fc13 --- /dev/null +++ b/generator/config/expression/floor.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $floor + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/floor/' +type: + - resolvesToInt +encode: single +description: | + Returns the largest integer less than or equal to the specified number. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/expression/function.yaml b/generator/config/expression/function.yaml new file mode 100644 index 000000000..6c2ac41e3 --- /dev/null +++ b/generator/config/expression/function.yaml @@ -0,0 +1,27 @@ +# $schema: ../schema.json +name: $function + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/function/' +type: + - resolvesToAny +encode: object +description: | + Defines a custom function. + New in version 4.4. +arguments: + - + name: body + type: + - string + description: | + The function definition. You can specify the function definition as either BSON type Code or String. + - + name: args + type: + - array + description: | + Arguments passed to the function body. If the body function does not take an argument, you can specify an empty array [ ]. + - + name: lang + type: + - string diff --git a/generator/config/expression/getField.yaml b/generator/config/expression/getField.yaml new file mode 100644 index 000000000..87b6865fb --- /dev/null +++ b/generator/config/expression/getField.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $getField +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/getField/' +type: + - resolvesToAny +encode: object +description: | + Returns the value of a specified field from a document. You can use $getField to retrieve the value of fields with names that contain periods (.) or start with dollar signs ($). + New in version 5.0. +arguments: + - + name: field + type: + - string + description: | + Field in the input object for which you want to return a value. field can be any valid expression that resolves to a string constant. + If field begins with a dollar sign ($), place the field name inside of a $literal expression to return its value. + - + name: input + type: + - expression + optional: true + description: | + Default: $$CURRENT + A valid expression that contains the field for which you want to return a value. input must resolve to an object, missing, null, or undefined. If omitted, defaults to the document currently being processed in the pipeline ($$CURRENT). diff --git a/generator/config/expression/gt.yaml b/generator/config/expression/gt.yaml new file mode 100644 index 000000000..6e6937c9d --- /dev/null +++ b/generator/config/expression/gt.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $gt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/gt/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the first value is greater than the second. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/gte.yaml b/generator/config/expression/gte.yaml new file mode 100644 index 000000000..af4545d3b --- /dev/null +++ b/generator/config/expression/gte.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $gte + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/gte/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the first value is greater than or equal to the second. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/hour.yaml b/generator/config/expression/hour.yaml new file mode 100644 index 000000000..cfdceff6c --- /dev/null +++ b/generator/config/expression/hour.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $hour + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/hour/' +type: + - resolvesToInt +encode: object +description: | + Returns the hour for a date as a number between 0 and 23. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/ifNull.yaml b/generator/config/expression/ifNull.yaml new file mode 100644 index 000000000..3cbbb72ae --- /dev/null +++ b/generator/config/expression/ifNull.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $ifNull +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/ifNull/' +type: + - resolvesToAny +encode: single +description: | + Returns either the non-null result of the first expression or the result of the second expression if the first expression results in a null result. Null result encompasses instances of undefined values or missing fields. Accepts two expressions as arguments. The result of the second expression can be null. +arguments: + - + name: expression + type: + - expression + variadic: array diff --git a/generator/config/expression/in.yaml b/generator/config/expression/in.yaml new file mode 100644 index 000000000..b4429d140 --- /dev/null +++ b/generator/config/expression/in.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $in + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/in/' +type: + - resolvesToBool +encode: array +description: | + Returns a boolean indicating whether a specified value is in an array. +arguments: + - + name: expression + type: + - expression + description: | + Any valid expression expression. + - + name: array + type: + - resolvesToArray + description: | + Any valid expression that resolves to an array. diff --git a/generator/config/expression/indexOfArray.yaml b/generator/config/expression/indexOfArray.yaml new file mode 100644 index 000000000..34b308c64 --- /dev/null +++ b/generator/config/expression/indexOfArray.yaml @@ -0,0 +1,38 @@ +# $schema: ../schema.json +name: $indexOfArray + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfArray/' +type: + - resolvesToInt +encode: array +description: | + Searches an array for an occurrence of a specified value and returns the array index of the first occurrence. Array indexes start at zero. +arguments: + - + name: array + type: + - resolvesToString + description: | + Can be any valid expression as long as it resolves to an array. + If the array expression resolves to a value of null or refers to a field that is missing, $indexOfArray returns null. + If the array expression does not resolve to an array or null nor refers to a missing field, $indexOfArray returns an error. + - + name: search + type: + - expression + - + name: start + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + If unspecified, the starting index position for the search is the beginning of the string. + - + name: end + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + If unspecified, the ending index position for the search is the end of the string. diff --git a/generator/config/expression/indexOfBytes.yaml b/generator/config/expression/indexOfBytes.yaml new file mode 100644 index 000000000..0c4efc782 --- /dev/null +++ b/generator/config/expression/indexOfBytes.yaml @@ -0,0 +1,40 @@ +# $schema: ../schema.json +name: $indexOfBytes + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfBytes/' +type: + - resolvesToInt +encode: array +description: | + Searches a string for an occurrence of a substring and returns the UTF-8 byte index of the first occurrence. If the substring is not found, returns -1. +arguments: + - + name: string + type: + - resolvesToString + description: | + Can be any valid expression as long as it resolves to a string. + If the string expression resolves to a value of null or refers to a field that is missing, $indexOfBytes returns null. + If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfBytes returns an error. + - + name: substring + type: + - resolvesToString + description: | + Can be any valid expression as long as it resolves to a string. + - + name: start + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + If unspecified, the starting index position for the search is the beginning of the string. + - + name: end + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + If unspecified, the ending index position for the search is the end of the string. diff --git a/generator/config/expression/indexOfCP.yaml b/generator/config/expression/indexOfCP.yaml new file mode 100644 index 000000000..b5499d9ad --- /dev/null +++ b/generator/config/expression/indexOfCP.yaml @@ -0,0 +1,40 @@ +# $schema: ../schema.json +name: $indexOfCP + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfCP/' +type: + - resolvesToInt +encode: array +description: | + Searches a string for an occurrence of a substring and returns the UTF-8 code point index of the first occurrence. If the substring is not found, returns -1 +arguments: + - + name: string + type: + - resolvesToString + description: | + Can be any valid expression as long as it resolves to a string. + If the string expression resolves to a value of null or refers to a field that is missing, $indexOfCP returns null. + If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfCP returns an error. + - + name: substring + type: + - resolvesToString + description: | + Can be any valid expression as long as it resolves to a string. + - + name: start + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + If unspecified, the starting index position for the search is the beginning of the string. + - + name: end + type: + - resolvesToInt + optional: true + description: | + An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + If unspecified, the ending index position for the search is the end of the string. diff --git a/generator/config/expression/integral.yaml b/generator/config/expression/integral.yaml new file mode 100644 index 000000000..95ef62c77 --- /dev/null +++ b/generator/config/expression/integral.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $integral + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/integral/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: object +description: | + Returns the approximation of the area under a curve. + New in version 5.0. +arguments: + - + name: input + type: + - resolvesToNumber + - resolvesToDate + - + name: unit + type: + - resolvesToString + optional: true + description: | + A string that specifies the time unit. Use one of these strings: "week", "day","hour", "minute", "second", "millisecond". + If the sortBy field is not a date, you must omit a unit. If you specify a unit, you must specify a date in the sortBy field. diff --git a/generator/config/expression/isArray.yaml b/generator/config/expression/isArray.yaml new file mode 100644 index 000000000..b49bc3858 --- /dev/null +++ b/generator/config/expression/isArray.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $isArray + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/isArray/' +type: + - resolvesToBool +encode: array +description: | + Determines if the operand is an array. Returns a boolean. +arguments: + - + name: expression + type: + - expression + variadic: array diff --git a/generator/config/expression/isNumber.yaml b/generator/config/expression/isNumber.yaml new file mode 100644 index 000000000..85e753de3 --- /dev/null +++ b/generator/config/expression/isNumber.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $isNumber + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/isNumber/' +type: + - resolvesToBool +encode: single +description: | + Returns boolean true if the specified expression resolves to an integer, decimal, double, or long. + Returns boolean false if the expression resolves to any other BSON type, null, or a missing field. + New in version 4.4. +arguments: + - + name: expression + type: + - expression + variadic: array diff --git a/generator/config/expression/isoDayOfWeek.yaml b/generator/config/expression/isoDayOfWeek.yaml new file mode 100644 index 000000000..1c3ac2ea3 --- /dev/null +++ b/generator/config/expression/isoDayOfWeek.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $isoDayOfWeek + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoDayOfWeek/' +type: + - resolvesToInt +encode: object +description: | + Returns the weekday number in ISO 8601 format, ranging from 1 (for Monday) to 7 (for Sunday). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/isoWeek.yaml b/generator/config/expression/isoWeek.yaml new file mode 100644 index 000000000..ba470beaf --- /dev/null +++ b/generator/config/expression/isoWeek.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $isoWeek + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoWeek/' +type: + - resolvesToInt +encode: object +description: | + Returns the week number in ISO 8601 format, ranging from 1 to 53. Week numbers start at 1 with the week (Monday through Sunday) that contains the year's first Thursday. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/isoWeekYear.yaml b/generator/config/expression/isoWeekYear.yaml new file mode 100644 index 000000000..5e3315301 --- /dev/null +++ b/generator/config/expression/isoWeekYear.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $isoWeekYear + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoWeekYear/' +type: + - resolvesToInt +encode: object +description: | + Returns the year number in ISO 8601 format. The year starts with the Monday of week 1 (ISO 8601) and ends with the Sunday of the last week (ISO 8601). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/let.yaml b/generator/config/expression/let.yaml new file mode 100644 index 000000000..d61e62449 --- /dev/null +++ b/generator/config/expression/let.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $let + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/let/' +type: + - resolvesToAny +encode: object +description: | + Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters. + Accepts any number of argument expressions. +arguments: + - + name: vars + type: + - object # of expression + description: | + Assignment block for the variables accessible in the in expression. To assign a variable, specify a string for the variable name and assign a valid expression for the value. + The variable assignments have no meaning outside the in expression, not even within the vars block itself. + - + name: in + type: + - expression + description: | + The expression to evaluate. diff --git a/generator/config/expression/linearFill.yaml b/generator/config/expression/linearFill.yaml new file mode 100644 index 000000000..b03907131 --- /dev/null +++ b/generator/config/expression/linearFill.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $linearFill + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/linearFill/' +type: + - resolvesToNumber +encode: single +description: | + Fills null and missing fields in a window using linear interpolation based on surrounding field values. + Available in the $setWindowFields stage. + New in version 5.3. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/expression/literal.yaml b/generator/config/expression/literal.yaml new file mode 100644 index 000000000..63abca279 --- /dev/null +++ b/generator/config/expression/literal.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $literal + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/literal/' +type: + - resolvesToAny +encode: single +description: | + Return a value without parsing. Use for values that the aggregation pipeline may interpret as an expression. For example, use a $literal expression to a string that starts with a dollar sign ($) to avoid parsing as a field path. +arguments: + - + name: value + type: + - any + description: | + If the value is an expression, $literal does not evaluate the expression but instead returns the unparsed expression. diff --git a/generator/config/expression/ln.yaml b/generator/config/expression/ln.yaml new file mode 100644 index 000000000..4b7bc3776 --- /dev/null +++ b/generator/config/expression/ln.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $ln + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/ln/' +type: + - resolvesToDouble +encode: single +description: | + Calculates the natural log of a number. + $ln is equivalent to $log: [ , Math.E ] expression, where Math.E is a JavaScript representation for Euler's number e. +arguments: + - + name: number + type: + - resolvesToNumber + description: | + Any valid expression as long as it resolves to a non-negative number. For more information on expressions, see Expressions. diff --git a/generator/config/expression/locf.yaml b/generator/config/expression/locf.yaml new file mode 100644 index 000000000..fb12c92cf --- /dev/null +++ b/generator/config/expression/locf.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $locf +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/locf/' +type: + - resolvesToAny +encode: single +description: | + Last observation carried forward. Sets values for null and missing fields in a window to the last non-null value for the field. + Available in the $setWindowFields stage. + New in version 5.2. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/log.yaml b/generator/config/expression/log.yaml new file mode 100644 index 000000000..f166e2bf2 --- /dev/null +++ b/generator/config/expression/log.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $log + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/log/' +type: + - resolvesToDouble +encode: array +description: | + Calculates the log of a number in the specified base. +arguments: + - + name: number + type: + - resolvesToNumber + description: | + Any valid expression as long as it resolves to a non-negative number. + - + name: base + type: + - resolvesToNumber + description: | + Any valid expression as long as it resolves to a positive number greater than 1. diff --git a/generator/config/expression/log10.yaml b/generator/config/expression/log10.yaml new file mode 100644 index 000000000..415cddda5 --- /dev/null +++ b/generator/config/expression/log10.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $log10 + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/log10/' +type: + - resolvesToDouble +encode: single +description: | + Calculates the log base 10 of a number. +arguments: + - + name: number + type: + - resolvesToNumber + description: | + Any valid expression as long as it resolves to a non-negative number. diff --git a/generator/config/expression/lt.yaml b/generator/config/expression/lt.yaml new file mode 100644 index 000000000..6011884e2 --- /dev/null +++ b/generator/config/expression/lt.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $lt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lt/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the first value is less than the second. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/lte.yaml b/generator/config/expression/lte.yaml new file mode 100644 index 000000000..ce9917283 --- /dev/null +++ b/generator/config/expression/lte.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $lte + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lte/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the first value is less than or equal to the second. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/ltrim.yaml b/generator/config/expression/ltrim.yaml new file mode 100644 index 000000000..58d762119 --- /dev/null +++ b/generator/config/expression/ltrim.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $ltrim + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/ltrim/' +type: + - resolvesToString +encode: object +description: | + Removes whitespace or the specified characters from the beginning of a string. + New in version 4.0. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string to trim. The argument can be any valid expression that resolves to a string. + - + name: chars + type: + - resolvesToString + optional: true + description: | + The character(s) to trim from the beginning of the input. + The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + If unspecified, $ltrim removes whitespace characters, including the null character. diff --git a/generator/config/expression/map.yaml b/generator/config/expression/map.yaml new file mode 100644 index 000000000..d180fe95b --- /dev/null +++ b/generator/config/expression/map.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $map + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/map/' +type: + - resolvesToArray +encode: object +description: | + Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to an array. + - + name: as + type: + - resolvesToString + optional: true + description: | + A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this. + - + name: in + type: + - expression + description: | + An expression that is applied to each element of the input array. The expression references each element individually with the variable name specified in as. diff --git a/generator/config/expression/max.yaml b/generator/config/expression/max.yaml new file mode 100644 index 000000000..fd3d40084 --- /dev/null +++ b/generator/config/expression/max.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $max + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/max/' +type: + - resolvesToAny +encode: single +description: | + Returns the maximum value that results from applying an expression to each document. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression + variadic: array diff --git a/generator/config/expression/maxN.yaml b/generator/config/expression/maxN.yaml new file mode 100644 index 000000000..73a45a59e --- /dev/null +++ b/generator/config/expression/maxN.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $maxN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxN-array-element/' +type: + - resolvesToArray +encode: object +description: | + Returns the n largest values in an array. Distinct from the $maxN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return the maximal n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. diff --git a/generator/config/expression/median.yaml b/generator/config/expression/median.yaml new file mode 100644 index 000000000..6ff4c5cc7 --- /dev/null +++ b/generator/config/expression/median.yaml @@ -0,0 +1,27 @@ +# $schema: ../schema.json +name: $median + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/median/' +type: + - resolvesToDouble +encode: object +description: | + Returns an approximation of the median, the 50th percentile, as a scalar value. + New in version 7.0. + This operator is available as an accumulator in these stages: + $group + $setWindowFields + It is also available as an aggregation expression. +arguments: + - + name: input + type: + - resolvesToNumber + description: | + $median calculates the 50th percentile value of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $median calculation ignores it. + - + name: method + type: + - string # AccumulatorPercentile + description: | + The method that mongod uses to calculate the 50th percentile value. The method must be 'approximate'. diff --git a/generator/config/expression/meta.yaml b/generator/config/expression/meta.yaml new file mode 100644 index 000000000..89bd6d988 --- /dev/null +++ b/generator/config/expression/meta.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $meta + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta/' +type: + - resolvesToAny +encode: single +description: | + Access available per-document metadata related to the aggregation operation. +arguments: + - + name: keyword + type: + - string diff --git a/generator/config/expression/millisecond.yaml b/generator/config/expression/millisecond.yaml new file mode 100644 index 000000000..1f082f467 --- /dev/null +++ b/generator/config/expression/millisecond.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $millisecond + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/millisecond/' +type: + - resolvesToInt +encode: object +description: | + Returns the milliseconds of a date as a number between 0 and 999. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/min.yaml b/generator/config/expression/min.yaml new file mode 100644 index 000000000..ace59d66e --- /dev/null +++ b/generator/config/expression/min.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $min + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/min/' +type: + - resolvesToAny +encode: single +description: | + Returns the minimum value that results from applying an expression to each document. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - expression + variadic: array diff --git a/generator/config/expression/minN.yaml b/generator/config/expression/minN.yaml new file mode 100644 index 000000000..51cccbb80 --- /dev/null +++ b/generator/config/expression/minN.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $minN + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/minN-array-element/' +type: + - resolvesToArray +encode: object +description: | + Returns the n smallest values in an array. Distinct from the $minN accumulator. +arguments: + - + name: input + type: + - resolvesToArray + description: | + An expression that resolves to the array from which to return the maximal n elements. + - + name: 'n' + type: + - resolvesToInt + description: | + An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. diff --git a/generator/config/expression/minute.yaml b/generator/config/expression/minute.yaml new file mode 100644 index 000000000..a208546fc --- /dev/null +++ b/generator/config/expression/minute.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $minute + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/minute/' +type: + - resolvesToInt +encode: object +description: | + Returns the minute for a date as a number between 0 and 59. +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/mod.yaml b/generator/config/expression/mod.yaml new file mode 100644 index 000000000..55273efb4 --- /dev/null +++ b/generator/config/expression/mod.yaml @@ -0,0 +1,20 @@ +# $schema: ../schema.json +name: $mod + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/mod/' +type: + - resolvesToInt +encode: array +description: | + Returns the remainder of the first number divided by the second. Accepts two argument expressions. +arguments: + - + name: dividend + type: + - resolvesToNumber + description: | + The first argument is the dividend, and the second argument is the divisor; i.e. first argument is divided by the second argument. + - + name: divisor + type: + - resolvesToNumber diff --git a/generator/config/expression/month.yaml b/generator/config/expression/month.yaml new file mode 100644 index 000000000..d00e1138c --- /dev/null +++ b/generator/config/expression/month.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $month + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/month/' +type: + - resolvesToInt +encode: object +description: | + Returns the month for a date as a number between 1 (January) and 12 (December). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/multiply.yaml b/generator/config/expression/multiply.yaml new file mode 100644 index 000000000..8741bda32 --- /dev/null +++ b/generator/config/expression/multiply.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $multiply + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/multiply/' +type: + - resolvesToDecimal +encode: single +description: | + Multiplies numbers to return the product. Accepts any number of argument expressions. +arguments: + - + name: expression + type: + - resolvesToNumber + variadic: array + description: | + The arguments can be any valid expression as long as they resolve to numbers. + Starting in MongoDB 6.1 you can optimize the $multiply operation. To improve performance, group references at the end of the argument list. diff --git a/generator/config/expression/ne.yaml b/generator/config/expression/ne.yaml new file mode 100644 index 000000000..b90e4cf45 --- /dev/null +++ b/generator/config/expression/ne.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $ne + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/ne/' +type: + - resolvesToBool +encode: array +description: | + Returns true if the values are not equivalent. +arguments: + - + name: expression1 + type: + - expression + - + name: expression2 + type: + - expression diff --git a/generator/config/expression/not.yaml b/generator/config/expression/not.yaml new file mode 100644 index 000000000..523c63f83 --- /dev/null +++ b/generator/config/expression/not.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $not + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/not/' +type: + - resolvesToBool +encode: single +description: | + Returns the boolean value that is the opposite of its argument expression. Accepts a single argument expression. +arguments: + - + name: expression + type: + - expression + - resolvesToBool diff --git a/generator/config/expression/objectToArray.yaml b/generator/config/expression/objectToArray.yaml new file mode 100644 index 000000000..780c8f441 --- /dev/null +++ b/generator/config/expression/objectToArray.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $objectToArray + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/objectToArray/' +type: + - resolvesToArray +encode: single +description: | + Converts a document to an array of documents representing key-value pairs. +arguments: + - + name: object + type: + - resolvesToObject + description: | + Any valid expression as long as it resolves to a document object. $objectToArray applies to the top-level fields of its argument. If the argument is a document that itself contains embedded document fields, the $objectToArray does not recursively apply to the embedded document fields. diff --git a/generator/config/expression/or.yaml b/generator/config/expression/or.yaml new file mode 100644 index 000000000..808e64d83 --- /dev/null +++ b/generator/config/expression/or.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $or + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/or/' +type: + - resolvesToBool +encode: single +description: | + Returns true when any of its expressions evaluates to true. Accepts any number of argument expressions. +arguments: + - + name: expression + type: + - expression + - resolvesToBool + variadic: array diff --git a/generator/config/expression/percentile.yaml b/generator/config/expression/percentile.yaml new file mode 100644 index 000000000..74e53c0ba --- /dev/null +++ b/generator/config/expression/percentile.yaml @@ -0,0 +1,37 @@ +# $schema: ../schema.json +name: $percentile + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/percentile/' +type: + - resolvesToArray # of scalar +encode: object +description: | + Returns an array of scalar values that correspond to specified percentile values. + New in version 7.0. + + This operator is available as an accumulator in these stages: + $group + + $setWindowFields + + It is also available as an aggregation expression. +arguments: + - + name: input + type: + - resolvesToNumber + description: | + $percentile calculates the percentile values of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $percentile calculation ignores it. + - + name: p + type: + - resolvesToArray # of resolvesToNumber + description: | + $percentile calculates a percentile value for each element in p. The elements represent percentages and must evaluate to numeric values in the range 0.0 to 1.0, inclusive. + $percentile returns results in the same order as the elements in p. + - + name: method + type: + - string # AccumulatorPercentile + description: | + The method that mongod uses to calculate the percentile value. The method must be 'approximate'. diff --git a/generator/config/expression/pow.yaml b/generator/config/expression/pow.yaml new file mode 100644 index 000000000..cda3ea0a6 --- /dev/null +++ b/generator/config/expression/pow.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $pow + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/pow/' +type: + - resolvesToNumber +encode: array +description: | + Raises a number to the specified exponent. +arguments: + - + name: number + type: + - resolvesToNumber + - + name: exponent + type: + - resolvesToNumber diff --git a/generator/config/expression/radiansToDegrees.yaml b/generator/config/expression/radiansToDegrees.yaml new file mode 100644 index 000000000..dd5a829f7 --- /dev/null +++ b/generator/config/expression/radiansToDegrees.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $radiansToDegrees + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/radiansToDegrees/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Converts a value from radians to degrees. +arguments: + - + name: expression + type: + - resolvesToNumber diff --git a/generator/config/expression/rand.yaml b/generator/config/expression/rand.yaml new file mode 100644 index 000000000..42716ca40 --- /dev/null +++ b/generator/config/expression/rand.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $rand + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/rand/' +type: + - resolvesToDouble +encode: object +description: | + Returns a random float between 0 and 1 diff --git a/generator/config/expression/range.yaml b/generator/config/expression/range.yaml new file mode 100644 index 000000000..e0c5221dc --- /dev/null +++ b/generator/config/expression/range.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $range + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/range/' +type: + - resolvesToArray # of int +encode: array +description: | + Outputs an array containing a sequence of integers according to user-defined inputs. +arguments: + - + name: start + type: + - resolvesToInt + description: | + An integer that specifies the start of the sequence. Can be any valid expression that resolves to an integer. + - + name: end + type: + - resolvesToInt + description: | + An integer that specifies the exclusive upper limit of the sequence. Can be any valid expression that resolves to an integer. + - + name: step + type: + - resolvesToInt + optional: true + description: | + An integer that specifies the increment value. Can be any valid expression that resolves to a non-zero integer. Defaults to 1. diff --git a/generator/config/expression/rank.yaml b/generator/config/expression/rank.yaml new file mode 100644 index 000000000..ef3a8d5f7 --- /dev/null +++ b/generator/config/expression/rank.yaml @@ -0,0 +1,10 @@ +# $schema: ../schema.json +name: $rank + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/rank/' +type: + - resolvesToInt +encode: object +description: | + Returns the document position (known as the rank) relative to other documents in the $setWindowFields stage partition. + New in version 5.0. diff --git a/generator/config/expression/reduce.yaml b/generator/config/expression/reduce.yaml new file mode 100644 index 000000000..f642fe62b --- /dev/null +++ b/generator/config/expression/reduce.yaml @@ -0,0 +1,33 @@ +# $schema: ../schema.json +name: $reduce + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/reduce/' +type: + - resolvesToAny +encode: object +description: | + Applies an expression to each element in an array and combines them into a single value. +arguments: + - + name: input + type: + - resolvesToArray + description: | + Can be any valid expression that resolves to an array. + If the argument resolves to a value of null or refers to a missing field, $reduce returns null. + If the argument does not resolve to an array or null nor refers to a missing field, $reduce returns an error. + - + name: initialValue + type: + - expression + description: | + The initial cumulative value set before in is applied to the first element of the input array. + - + name: in + type: + - expression + description: | + A valid expression that $reduce applies to each element in the input array in left-to-right order. Wrap the input value with $reverseArray to yield the equivalent of applying the combining expression from right-to-left. + During evaluation of the in expression, two variables will be available: + - value is the variable that represents the cumulative value of the expression. + - this is the variable that refers to the element being processed. diff --git a/generator/config/expression/regexFind.yaml b/generator/config/expression/regexFind.yaml new file mode 100644 index 000000000..74b1eadd4 --- /dev/null +++ b/generator/config/expression/regexFind.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $regexFind + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexFind/' +type: + - resolvesToObject +encode: object +description: | + Applies a regular expression (regex) to a string and returns information on the first matched substring. + New in version 4.2. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + - + name: regex + type: + - resolvesToString + - regex + description: | + The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + - + name: options + type: + - string + optional: true diff --git a/generator/config/expression/regexFindAll.yaml b/generator/config/expression/regexFindAll.yaml new file mode 100644 index 000000000..9196e1555 --- /dev/null +++ b/generator/config/expression/regexFindAll.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $regexFindAll + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexFindAll/' +type: + - resolvesToArray # of object +encode: object +description: | + Applies a regular expression (regex) to a string and returns information on the all matched substrings. + New in version 4.2. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + - + name: regex + type: + - resolvesToString + - regex + description: | + The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + - + name: options + type: + - string + optional: true diff --git a/generator/config/expression/regexMatch.yaml b/generator/config/expression/regexMatch.yaml new file mode 100644 index 000000000..6eea7d867 --- /dev/null +++ b/generator/config/expression/regexMatch.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $regexMatch + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexMatch/' +type: + - resolvesToBool +encode: object +description: | + Applies a regular expression (regex) to a string and returns a boolean that indicates if a match is found or not. + New in version 4.2. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + - + name: regex + type: + - resolvesToString + - regex + description: | + The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + - + name: options + type: + - string + optional: true diff --git a/generator/config/expression/replaceAll.yaml b/generator/config/expression/replaceAll.yaml new file mode 100644 index 000000000..c435fc4f2 --- /dev/null +++ b/generator/config/expression/replaceAll.yaml @@ -0,0 +1,33 @@ +# $schema: ../schema.json +name: $replaceAll + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceAll/' +type: + - resolvesToString +encode: object +description: | + Replaces all instances of a search string in an input string with a replacement string. + $replaceAll is both case-sensitive and diacritic-sensitive, and ignores any collation present on a collection. + New in version 4.4. +arguments: + - + name: input + type: + - resolvesToString + - resolvesToNull + description: | + The string on which you wish to apply the find. Can be any valid expression that resolves to a string or a null. If input refers to a field that is missing, $replaceAll returns null. + - + name: find + type: + - resolvesToString + - resolvesToNull + description: | + The string to search for within the given input. Can be any valid expression that resolves to a string or a null. If find refers to a field that is missing, $replaceAll returns null. + - + name: replacement + type: + - resolvesToString + - resolvesToNull + description: | + The string to use to replace all matched instances of find in input. Can be any valid expression that resolves to a string or a null. diff --git a/generator/config/expression/replaceOne.yaml b/generator/config/expression/replaceOne.yaml new file mode 100644 index 000000000..d2a081bdc --- /dev/null +++ b/generator/config/expression/replaceOne.yaml @@ -0,0 +1,32 @@ +# $schema: ../schema.json +name: $replaceOne + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceOne/' +type: + - resolvesToString +encode: object +description: | + Replaces the first instance of a matched string in a given input. + New in version 4.4. +arguments: + - + name: input + type: + - resolvesToString + - resolvesToNull + description: | + The string on which you wish to apply the find. Can be any valid expression that resolves to a string or a null. If input refers to a field that is missing, $replaceAll returns null. + - + name: find + type: + - resolvesToString + - resolvesToNull + description: | + The string to search for within the given input. Can be any valid expression that resolves to a string or a null. If find refers to a field that is missing, $replaceAll returns null. + - + name: replacement + type: + - resolvesToString + - resolvesToNull + description: | + The string to use to replace all matched instances of find in input. Can be any valid expression that resolves to a string or a null. diff --git a/generator/config/expression/reverseArray.yaml b/generator/config/expression/reverseArray.yaml new file mode 100644 index 000000000..1ee528c55 --- /dev/null +++ b/generator/config/expression/reverseArray.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $reverseArray + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/reverseArray/' +type: + - resolvesToArray +encode: single +description: | + Returns an array with the elements in reverse order. +arguments: + - + name: expression + type: + - resolvesToArray + description: | + The argument can be any valid expression as long as it resolves to an array. diff --git a/generator/config/expression/round.yaml b/generator/config/expression/round.yaml new file mode 100644 index 000000000..c7e9a0519 --- /dev/null +++ b/generator/config/expression/round.yaml @@ -0,0 +1,30 @@ +# $schema: ../schema.json +name: $round + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/round/' +type: + - resolvesToInt + - resolvesToDouble + - resolvesToDecimal + - resolvesToLong +encode: array +description: | + Rounds a number to to a whole integer or to a specified decimal place. +arguments: + - + name: number + type: + - resolvesToInt + - resolvesToDouble + - resolvesToDecimal + - resolvesToLong + description: | + Can be any valid expression that resolves to a number. Specifically, the expression must resolve to an integer, double, decimal, or long. + $round returns an error if the expression resolves to a non-numeric data type. + - + name: place + type: + - resolvesToInt + optional: true + description: | + Can be any valid expression that resolves to an integer between -20 and 100, exclusive. diff --git a/generator/config/expression/rtrim.yaml b/generator/config/expression/rtrim.yaml new file mode 100644 index 000000000..e72147da7 --- /dev/null +++ b/generator/config/expression/rtrim.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $rtrim + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/rtrim/' +type: + - resolvesToString +encode: object +description: | + Removes whitespace characters, including null, or the specified characters from the end of a string. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string to trim. The argument can be any valid expression that resolves to a string. + - + name: chars + type: + - resolvesToString + optional: true + description: | + The character(s) to trim from the beginning of the input. + The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + If unspecified, $ltrim removes whitespace characters, including the null character. diff --git a/generator/config/expression/sampleRate.yaml b/generator/config/expression/sampleRate.yaml new file mode 100644 index 000000000..8a6e1cf13 --- /dev/null +++ b/generator/config/expression/sampleRate.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $sampleRate + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sampleRate/' +type: + - resolvesToAny +encode: single +description: | + Randomly select documents at a given rate. Although the exact number of documents selected varies on each run, the quantity chosen approximates the sample rate expressed as a percentage of the total number of documents. +arguments: + - + name: rate + type: + - resolvesToDouble + description: | + The selection process uses a uniform random distribution. The sample rate is a floating point number between 0 and 1, inclusive, which represents the probability that a given document will be selected as it passes through the pipeline. + For example, a sample rate of 0.33 selects roughly one document in three. diff --git a/generator/config/expression/second.yaml b/generator/config/expression/second.yaml new file mode 100644 index 000000000..b96d22eed --- /dev/null +++ b/generator/config/expression/second.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $second + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/second/' +type: + - resolvesToInt +encode: object +description: | + Returns the seconds for a date as a number between 0 and 60 (leap seconds). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/setDifference.yaml b/generator/config/expression/setDifference.yaml new file mode 100644 index 000000000..2cfa018e1 --- /dev/null +++ b/generator/config/expression/setDifference.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $setDifference + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setDifference/' +type: + - resolvesToArray +encode: array +description: | + Returns a set with elements that appear in the first set but not in the second set; i.e. performs a relative complement of the second set relative to the first. Accepts exactly two argument expressions. +arguments: + - + name: expression1 + type: + - resolvesToArray + description: | + The arguments can be any valid expression as long as they each resolve to an array. + - + name: expression2 + type: + - resolvesToArray + description: | + The arguments can be any valid expression as long as they each resolve to an array. diff --git a/generator/config/expression/setEquals.yaml b/generator/config/expression/setEquals.yaml new file mode 100644 index 000000000..320b8f693 --- /dev/null +++ b/generator/config/expression/setEquals.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $setEquals + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setEquals/' +type: + - resolvesToBool +encode: single +description: | + Returns true if the input sets have the same distinct elements. Accepts two or more argument expressions. +arguments: + - + name: expression + type: + - resolvesToArray + variadic: array diff --git a/generator/config/expression/setField.yaml b/generator/config/expression/setField.yaml new file mode 100644 index 000000000..1992acaf0 --- /dev/null +++ b/generator/config/expression/setField.yaml @@ -0,0 +1,30 @@ +# $schema: ../schema.json +name: $setField + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setField/' +type: + - resolvesToObject +encode: object +description: | + Adds, updates, or removes a specified field in a document. You can use $setField to add, update, or remove fields with names that contain periods (.) or start with dollar signs ($). + New in version 5.0. +arguments: + - + name: field + type: + - resolvesToString + description: | + Field in the input object that you want to add, update, or remove. field can be any valid expression that resolves to a string constant. + - + name: input + type: + - resolvesToObject + description: | + Document that contains the field that you want to add or update. input must resolve to an object, missing, null, or undefined. + - + name: value + type: + - expression + description: | + The value that you want to assign to field. value can be any valid expression. + Set to $$REMOVE to remove field from the input document. diff --git a/generator/config/expression/setIntersection.yaml b/generator/config/expression/setIntersection.yaml new file mode 100644 index 000000000..ad8167354 --- /dev/null +++ b/generator/config/expression/setIntersection.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $setIntersection + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setIntersection/' +type: + - resolvesToArray +encode: single +description: | + Returns a set with elements that appear in all of the input sets. Accepts any number of argument expressions. +arguments: + - + name: expression + type: + - resolvesToArray + variadic: array diff --git a/generator/config/expression/setIsSubset.yaml b/generator/config/expression/setIsSubset.yaml new file mode 100644 index 000000000..3d5f3537c --- /dev/null +++ b/generator/config/expression/setIsSubset.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $setIsSubset + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setIsSubset/' +type: + - resolvesToBool +encode: array +description: | + Returns true if all elements of the first set appear in the second set, including when the first set equals the second set; i.e. not a strict subset. Accepts exactly two argument expressions. +arguments: + - + name: expression1 + type: + - resolvesToArray + - + name: expression2 + type: + - resolvesToArray diff --git a/generator/config/expression/setUnion.yaml b/generator/config/expression/setUnion.yaml new file mode 100644 index 000000000..9f058f3ea --- /dev/null +++ b/generator/config/expression/setUnion.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $setUnion + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setUnion/' +type: + - resolvesToArray +encode: single +description: | + Returns a set with elements that appear in any of the input sets. +arguments: + - + name: expression + type: + - resolvesToArray + variadic: array diff --git a/generator/config/expression/sin.yaml b/generator/config/expression/sin.yaml new file mode 100644 index 000000000..646b9657c --- /dev/null +++ b/generator/config/expression/sin.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $sin + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sin/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the sine of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $sin takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + By default $sin returns values as a double. $sin can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/sinh.yaml b/generator/config/expression/sinh.yaml new file mode 100644 index 000000000..ef267070b --- /dev/null +++ b/generator/config/expression/sinh.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $sinh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sinh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the hyperbolic sine of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $sinh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + By default $sinh returns values as a double. $sinh can also return values as a 128-bit decimal if the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/size.yaml b/generator/config/expression/size.yaml new file mode 100644 index 000000000..2dfd1b99a --- /dev/null +++ b/generator/config/expression/size.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $size + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/size/' +type: + - resolvesToInt +encode: single +description: | + Returns the number of elements in the array. Accepts a single expression as argument. +arguments: + - + name: expression + type: + - resolvesToArray + description: | + The argument for $size can be any expression as long as it resolves to an array. diff --git a/generator/config/expression/slice.yaml b/generator/config/expression/slice.yaml new file mode 100644 index 000000000..dbf298e8f --- /dev/null +++ b/generator/config/expression/slice.yaml @@ -0,0 +1,34 @@ +# $schema: ../schema.json +name: $slice + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/slice/' +type: + - resolvesToArray + - projection +encode: array +description: | + Returns a subset of an array. +arguments: + - + name: expression + type: + - resolvesToArray + description: | + Any valid expression as long as it resolves to an array. + - + name: position + type: + - resolvesToInt + optional: true + description: | + Any valid expression as long as it resolves to an integer. + If positive, $slice determines the starting position from the start of the array. If position is greater than the number of elements, the $slice returns an empty array. + If negative, $slice determines the starting position from the end of the array. If the absolute value of the is greater than the number of elements, the starting position is the start of the array. + - + name: "n" + type: + - resolvesToInt + description: | + Any valid expression as long as it resolves to an integer. If position is specified, n must resolve to a positive integer. + If positive, $slice returns up to the first n elements in the array. If the position is specified, $slice returns the first n elements starting from the position. + If negative, $slice returns up to the last n elements in the array. n cannot resolve to a negative number if is specified. diff --git a/generator/config/expression/sortArray.yaml b/generator/config/expression/sortArray.yaml new file mode 100644 index 000000000..4b0f1bfec --- /dev/null +++ b/generator/config/expression/sortArray.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $sortArray + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortArray/' +type: + - resolvesToArray +encode: object +description: | + Sorts the elements of an array. +arguments: + - + name: input + type: + - resolvesToArray + description: | + The array to be sorted. + The result is null if the expression: is missing, evaluates to null, or evaluates to undefined + If the expression evaluates to any other non-array value, the document returns an error. + - + name: sortBy + type: + - object # SortSpec + description: | + The document specifies a sort ordering. diff --git a/generator/config/expression/split.yaml b/generator/config/expression/split.yaml new file mode 100644 index 000000000..20e59ea47 --- /dev/null +++ b/generator/config/expression/split.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $split + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/split/' +type: + - resolvesToArray # of string +encode: array +description: | + Splits a string into substrings based on a delimiter. Returns an array of substrings. If the delimiter is not found within the string, returns an array containing the original string. +arguments: + - + name: string + type: + - resolvesToString + description: | + The string to be split. string expression can be any valid expression as long as it resolves to a string. + - + name: delimiter + type: + - resolvesToString + description: | + The delimiter to use when splitting the string expression. delimiter can be any valid expression as long as it resolves to a string. diff --git a/generator/config/expression/sqrt.yaml b/generator/config/expression/sqrt.yaml new file mode 100644 index 000000000..794a87df3 --- /dev/null +++ b/generator/config/expression/sqrt.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $sqrt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sqrt/' +type: + - resolvesToDouble +encode: single +description: | + Calculates the square root. +arguments: + - + name: number + type: + - resolvesToNumber + description: | + The argument can be any valid expression as long as it resolves to a non-negative number. diff --git a/generator/config/expression/stdDevPop.yaml b/generator/config/expression/stdDevPop.yaml new file mode 100644 index 000000000..74f58d786 --- /dev/null +++ b/generator/config/expression/stdDevPop.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $stdDevPop + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevPop/' +type: + - resolvesToDouble +encode: single +description: | + Calculates the population standard deviation of the input values. Use if the values encompass the entire population of data you want to represent and do not wish to generalize about a larger population. $stdDevPop ignores non-numeric values. + If the values represent only a sample of a population of data from which to generalize about the population, use $stdDevSamp instead. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber + variadic: array diff --git a/generator/config/expression/stdDevSamp.yaml b/generator/config/expression/stdDevSamp.yaml new file mode 100644 index 000000000..98041b56a --- /dev/null +++ b/generator/config/expression/stdDevSamp.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $stdDevSamp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevSamp/' +type: + - resolvesToDouble +encode: single +description: | + Calculates the sample standard deviation of the input values. Use if the values encompass a sample of a population of data from which to generalize about the population. $stdDevSamp ignores non-numeric values. + If the values represent the entire population of data or you do not wish to generalize about a larger population, use $stdDevPop instead. +arguments: + - + name: expression + type: + - resolvesToNumber + variadic: array diff --git a/generator/config/expression/strLenBytes.yaml b/generator/config/expression/strLenBytes.yaml new file mode 100644 index 000000000..002d5236d --- /dev/null +++ b/generator/config/expression/strLenBytes.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $strLenBytes + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/strLenBytes/' +type: + - resolvesToInt +encode: single +description: | + Returns the number of UTF-8 encoded bytes in a string. +arguments: + - + name: expression + type: + - resolvesToString diff --git a/generator/config/expression/strLenCP.yaml b/generator/config/expression/strLenCP.yaml new file mode 100644 index 000000000..692403702 --- /dev/null +++ b/generator/config/expression/strLenCP.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $strLenCP + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/strLenCP/' +type: + - resolvesToInt +encode: single +description: | + Returns the number of UTF-8 code points in a string. +arguments: + - + name: expression + type: + - resolvesToString diff --git a/generator/config/expression/strcasecmp.yaml b/generator/config/expression/strcasecmp.yaml new file mode 100644 index 000000000..b5c83d80c --- /dev/null +++ b/generator/config/expression/strcasecmp.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $strcasecmp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/strcasecmp/' +type: + - resolvesToInt +encode: array +description: | + Performs case-insensitive string comparison and returns: 0 if two strings are equivalent, 1 if the first string is greater than the second, and -1 if the first string is less than the second. +arguments: + - + name: expression1 + type: + - resolvesToString + - + name: expression2 + type: + - resolvesToString diff --git a/generator/config/expression/substr.yaml b/generator/config/expression/substr.yaml new file mode 100644 index 000000000..b6602102a --- /dev/null +++ b/generator/config/expression/substr.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $substr + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr/' +type: + - resolvesToString +encode: array +description: | + Deprecated. Use $substrBytes or $substrCP. +arguments: + - + name: string + type: + - resolvesToString + - + name: start + type: + - resolvesToInt + description: | + If start is a negative number, $substr returns an empty string "". + - + name: length + type: + - resolvesToInt + description: | + If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. diff --git a/generator/config/expression/substrBytes.yaml b/generator/config/expression/substrBytes.yaml new file mode 100644 index 000000000..3f8a9e60c --- /dev/null +++ b/generator/config/expression/substrBytes.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $substrBytes + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/substrBytes/' +type: + - resolvesToString +encode: array +description: | + Returns the substring of a string. Starts with the character at the specified UTF-8 byte index (zero-based) in the string and continues for the specified number of bytes. +arguments: + - + name: string + type: + - resolvesToString + - + name: start + type: + - resolvesToInt + description: | + If start is a negative number, $substr returns an empty string "". + - + name: length + type: + - resolvesToInt + description: | + If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. diff --git a/generator/config/expression/substrCP.yaml b/generator/config/expression/substrCP.yaml new file mode 100644 index 000000000..dcd286245 --- /dev/null +++ b/generator/config/expression/substrCP.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $substrCP + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/substrCP/' +type: + - resolvesToString +encode: array +description: | + Returns the substring of a string. Starts with the character at the specified UTF-8 code point (CP) index (zero-based) in the string and continues for the number of code points specified. +arguments: + - + name: string + type: + - resolvesToString + - + name: start + type: + - resolvesToInt + description: | + If start is a negative number, $substr returns an empty string "". + - + name: length + type: + - resolvesToInt + description: | + If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. diff --git a/generator/config/expression/subtract.yaml b/generator/config/expression/subtract.yaml new file mode 100644 index 000000000..18344c18a --- /dev/null +++ b/generator/config/expression/subtract.yaml @@ -0,0 +1,21 @@ +# $schema: ../schema.json +name: $subtract + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/subtract/' +type: + - resolvesToNumber + - resolvesToDate +encode: array +description: | + Returns the result of subtracting the second value from the first. If the two values are numbers, return the difference. If the two values are dates, return the difference in milliseconds. If the two values are a date and a number in milliseconds, return the resulting date. Accepts two argument expressions. If the two values are a date and a number, specify the date argument first as it is not meaningful to subtract a date from a number. +arguments: + - + name: expression1 + type: + - resolvesToNumber + - resolvesToDate + - + name: expression2 + type: + - resolvesToNumber + - resolvesToDate diff --git a/generator/config/expression/sum.yaml b/generator/config/expression/sum.yaml new file mode 100644 index 000000000..e990b005b --- /dev/null +++ b/generator/config/expression/sum.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $sum + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum/' +type: + - resolvesToNumber +encode: single +description: | + Returns a sum of numerical values. Ignores non-numeric values. + Changed in version 5.0: Available in the $setWindowFields stage. +arguments: + - + name: expression + type: + - resolvesToNumber + variadic: array diff --git a/generator/config/expression/switch.yaml b/generator/config/expression/switch.yaml new file mode 100644 index 000000000..2ade8d502 --- /dev/null +++ b/generator/config/expression/switch.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $switch +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/switch/' +type: + - resolvesToAny +encode: object +description: | + Evaluates a series of case expressions. When it finds an expression which evaluates to true, $switch executes a specified expression and breaks out of the control flow. +arguments: + - + name: branches + type: + - array # of object{case:resolvesToBool, then:expression} + description: | + An array of control branch documents. Each branch is a document with the following fields: + - case Can be any valid expression that resolves to a boolean. If the result is not a boolean, it is coerced to a boolean value. More information about how MongoDB evaluates expressions as either true or false can be found here. + - then Can be any valid expression. + The branches array must contain at least one branch document. + - + name: default + type: + - expression + optional: true + description: | + The path to take if no branch case expression evaluates to true. + Although optional, if default is unspecified and no branch case evaluates to true, $switch returns an error. diff --git a/generator/config/expression/tan.yaml b/generator/config/expression/tan.yaml new file mode 100644 index 000000000..f7a7cc915 --- /dev/null +++ b/generator/config/expression/tan.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $tan + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/tan/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the tangent of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $tan takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + By default $tan returns values as a double. $tan can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/tanh.yaml b/generator/config/expression/tanh.yaml new file mode 100644 index 000000000..d760780cc --- /dev/null +++ b/generator/config/expression/tanh.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $tanh + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/tanh/' +type: + - resolvesToDouble + - resolvesToDecimal +encode: single +description: | + Returns the hyperbolic tangent of a value that is measured in radians. +arguments: + - + name: expression + type: + - resolvesToNumber + description: | + $tanh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + By default $tanh returns values as a double. $tanh can also return values as a 128-bit decimal if the expression resolves to a 128-bit decimal value. diff --git a/generator/config/expression/toBool.yaml b/generator/config/expression/toBool.yaml new file mode 100644 index 000000000..ab24420cc --- /dev/null +++ b/generator/config/expression/toBool.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toBool + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toBool/' +type: + - resolvesToBool +encode: single +description: | + Converts value to a boolean. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toDate.yaml b/generator/config/expression/toDate.yaml new file mode 100644 index 000000000..69e843678 --- /dev/null +++ b/generator/config/expression/toDate.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toDate + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDate/' +type: + - resolvesToDate +encode: single +description: | + Converts value to a Date. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toDecimal.yaml b/generator/config/expression/toDecimal.yaml new file mode 100644 index 000000000..7d20bc06d --- /dev/null +++ b/generator/config/expression/toDecimal.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toDecimal + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDecimal/' +type: + - resolvesToDecimal +encode: single +description: | + Converts value to a Decimal128. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toDouble.yaml b/generator/config/expression/toDouble.yaml new file mode 100644 index 000000000..5987b51cc --- /dev/null +++ b/generator/config/expression/toDouble.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toDouble + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDouble/' +type: + - resolvesToDouble +encode: single +description: | + Converts value to a double. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toInt.yaml b/generator/config/expression/toInt.yaml new file mode 100644 index 000000000..6fdc8a180 --- /dev/null +++ b/generator/config/expression/toInt.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toInt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toInt/' +type: + - resolvesToInt +encode: single +description: | + Converts value to an integer. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toLong.yaml b/generator/config/expression/toLong.yaml new file mode 100644 index 000000000..5c2dae0d5 --- /dev/null +++ b/generator/config/expression/toLong.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toLong + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toLong/' +type: + - resolvesToLong +encode: single +description: | + Converts value to a long. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toLower.yaml b/generator/config/expression/toLower.yaml new file mode 100644 index 000000000..22bbd48e8 --- /dev/null +++ b/generator/config/expression/toLower.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $toLower + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toLower/' +type: + - resolvesToString +encode: single +description: | + Converts a string to lowercase. Accepts a single argument expression. +arguments: + - + name: expression + type: + - resolvesToString diff --git a/generator/config/expression/toObjectId.yaml b/generator/config/expression/toObjectId.yaml new file mode 100644 index 000000000..905d63a8c --- /dev/null +++ b/generator/config/expression/toObjectId.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toObjectId + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toObjectId/' +type: + - resolvesToObjectId +encode: single +description: | + Converts value to an ObjectId. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toString.yaml b/generator/config/expression/toString.yaml new file mode 100644 index 000000000..85bf97c0e --- /dev/null +++ b/generator/config/expression/toString.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $toString + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toString/' +type: + - resolvesToString +encode: single +description: | + Converts value to a string. + New in version 4.0. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/toUpper.yaml b/generator/config/expression/toUpper.yaml new file mode 100644 index 000000000..85b67adce --- /dev/null +++ b/generator/config/expression/toUpper.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $toUpper + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/toUpper/' +type: + - resolvesToString +encode: single +description: | + Converts a string to uppercase. Accepts a single argument expression. +arguments: + - + name: expression + type: + - resolvesToString diff --git a/generator/config/expression/trim.yaml b/generator/config/expression/trim.yaml new file mode 100644 index 000000000..4e0c5ce36 --- /dev/null +++ b/generator/config/expression/trim.yaml @@ -0,0 +1,26 @@ +# $schema: ../schema.json +name: $trim + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/trim/' +type: + - resolvesToString +encode: object +description: | + Removes whitespace or the specified characters from the beginning and end of a string. + New in version 4.0. +arguments: + - + name: input + type: + - resolvesToString + description: | + The string to trim. The argument can be any valid expression that resolves to a string. + - + name: chars + type: + - resolvesToString + optional: true + description: | + The character(s) to trim from the beginning of the input. + The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + If unspecified, $ltrim removes whitespace characters, including the null character. diff --git a/generator/config/expression/trunc.yaml b/generator/config/expression/trunc.yaml new file mode 100644 index 000000000..1ea271e43 --- /dev/null +++ b/generator/config/expression/trunc.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $trunc + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/trunc/' +type: + - resolvesToString +encode: array +description: | + Truncates a number to a whole integer or to a specified decimal place. +arguments: + - + name: number + type: + - resolvesToNumber + description: | + Can be any valid expression that resolves to a number. Specifically, the expression must resolve to an integer, double, decimal, or long. + $trunc returns an error if the expression resolves to a non-numeric data type. + - + name: place + type: + - resolvesToInt + optional: true + description: | + Can be any valid expression that resolves to an integer between -20 and 100, exclusive. e.g. -20 < place < 100. Defaults to 0. diff --git a/generator/config/expression/tsIncrement.yaml b/generator/config/expression/tsIncrement.yaml new file mode 100644 index 000000000..ba131c9c6 --- /dev/null +++ b/generator/config/expression/tsIncrement.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $tsIncrement + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsIncrement/' +type: + - resolvesToLong +encode: single +description: | + Returns the incrementing ordinal from a timestamp as a long. + New in version 5.1. +arguments: + - + name: expression + type: + - resolvesToTimestamp diff --git a/generator/config/expression/tsSecond.yaml b/generator/config/expression/tsSecond.yaml new file mode 100644 index 000000000..ab9af0718 --- /dev/null +++ b/generator/config/expression/tsSecond.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $tsSecond + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsSecond/' +type: + - resolvesToLong +encode: single +description: | + Returns the seconds from a timestamp as a long. + New in version 5.1. +arguments: + - + name: expression + type: + - resolvesToTimestamp diff --git a/generator/config/expression/type.yaml b/generator/config/expression/type.yaml new file mode 100644 index 000000000..05d1b0c3f --- /dev/null +++ b/generator/config/expression/type.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $type + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/type/' +type: + - resolvesToString +encode: single +description: | + Return the BSON data type of the field. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/expression/unsetField.yaml b/generator/config/expression/unsetField.yaml new file mode 100644 index 000000000..a621292c4 --- /dev/null +++ b/generator/config/expression/unsetField.yaml @@ -0,0 +1,23 @@ +# $schema: ../schema.json +name: $unsetField + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unsetField/' +type: + - resolvesToObject +encode: object +description: | + You can use $unsetField to remove fields with names that contain periods (.) or that start with dollar signs ($). + $unsetField is an alias for $setField using $$REMOVE to remove fields. +arguments: + - + name: field + type: + - resolvesToString + description: | + Field in the input object that you want to add, update, or remove. field can be any valid expression that resolves to a string constant. + - + name: input + type: + - resolvesToObject + description: | + Document that contains the field that you want to add or update. input must resolve to an object, missing, null, or undefined. diff --git a/generator/config/expression/week.yaml b/generator/config/expression/week.yaml new file mode 100644 index 000000000..04bcb5ec1 --- /dev/null +++ b/generator/config/expression/week.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $week + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/week/' +type: + - resolvesToInt +encode: object +description: | + Returns the week number for a date as a number between 0 (the partial week that precedes the first Sunday of the year) and 53 (leap year). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/year.yaml b/generator/config/expression/year.yaml new file mode 100644 index 000000000..97a714de5 --- /dev/null +++ b/generator/config/expression/year.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $year + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/year/' +type: + - resolvesToInt +encode: object +description: | + Returns the year for a date as a number (e.g. 2014). +arguments: + - + name: date + type: + - resolvesToDate + - resolvesToTimestamp + - resolvesToObjectId + description: | + The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + - + name: timezone + type: + - resolvesToString + optional: true + description: | + The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. diff --git a/generator/config/expression/zip.yaml b/generator/config/expression/zip.yaml new file mode 100644 index 000000000..85f0b9c69 --- /dev/null +++ b/generator/config/expression/zip.yaml @@ -0,0 +1,33 @@ +# $schema: ../schema.json +name: $zip + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/zip/' +type: + - resolvesToArray # of array +encode: object +description: | + Merge two arrays together. +arguments: + - + name: inputs + type: + - resolvesToArray # of array + description: | + An array of expressions that resolve to arrays. The elements of these input arrays combine to form the arrays of the output array. + If any of the inputs arrays resolves to a value of null or refers to a missing field, $zip returns null. + If any of the inputs arrays does not resolve to an array or null nor refers to a missing field, $zip returns an error. + - + name: useLongestLength + type: + - bool + description: | + A boolean which specifies whether the length of the longest array determines the number of arrays in the output array. + The default value is false: the shortest array length determines the number of arrays in the output array. + - + name: defaults + type: + - array + description: | + An array of default element values to use if the input arrays have different lengths. You must specify useLongestLength: true along with this field, or else $zip will return an error. + If useLongestLength: true but defaults is empty or not specified, $zip uses null as the default value. + If specifying a non-empty defaults, you must specify a default for each input array or else $zip will return an error. diff --git a/generator/config/expressions.php b/generator/config/expressions.php index 5e8a6b5d3..95483b94b 100644 --- a/generator/config/expressions.php +++ b/generator/config/expressions.php @@ -5,115 +5,157 @@ namespace MongoDB\Builder\Expression; use MongoDB\BSON; +use MongoDB\Builder\Pipeline; +use MongoDB\Builder\Type; +use MongoDB\CodeGenerator\Definition\PhpObject; use MongoDB\Model\BSONArray; use stdClass; -/** @param class-string $resolvesTo */ -function typeFieldPath(string $resolvesTo): array -{ - return [ - 'class' => true, - 'extends' => FieldPath::class, - 'implements' => [$resolvesTo], - 'types' => ['string'], +use function ucfirst; + +$bsonTypes = [ + // BSON types + // @see https://www.mongodb.com/docs/manual/reference/bson-types/ + // Ignore deprecated types and min/max keys which are not actual types + 'double' => ['int', BSON\Int64::class, 'float'], + 'string' => ['string'], + 'object' => ['array', stdClass::class, BSON\Document::class, BSON\Serializable::class], + 'array' => ['array', BSONArray::class, BSON\PackedArray::class], + 'binData' => ['string', BSON\Binary::class], + 'objectId' => [BSON\ObjectId::class], + 'bool' => ['bool'], + 'date' => [BSON\UTCDateTime::class], + 'null' => ['null'], + 'regex' => [BSON\Regex::class], + 'javascript' => ['string', BSON\Javascript::class], + 'int' => ['int'], + 'timestamp' => ['int', BSON\Timestamp::class], + 'long' => ['int', BSON\Int64::class], + 'decimal' => ['int', BSON\Int64::class, 'float', BSON\Decimal128::class], +]; + +// "any" accepts all the BSON types. No generic "object" or "mixed" +$bsonTypes['any'] = ['bool', 'int', 'float', 'string', 'array', 'null', stdClass::class, BSON\Type::class]; + +// "number" accepts all the numeric types +$bsonTypes['number'] = ['int', 'float', BSON\Int64::class, BSON\Decimal128::class]; + +$expressions = []; +$resolvesToInterfaces = []; +foreach ($bsonTypes as $name => $acceptedTypes) { + $expressions[$name] = ['acceptedTypes' => $acceptedTypes]; + + $resolvesTo = 'resolvesTo' . ucfirst($name); + $resolvesToInterface = __NAMESPACE__ . '\\' . ucfirst($resolvesTo); + $expressions[$resolvesTo] = [ + 'generate' => PhpObject::PhpInterface, + 'implements' => [Type\ExpressionInterface::class], + 'returnType' => $resolvesToInterface, + 'acceptedTypes' => $acceptedTypes, + ]; + + $fieldPathName = $name . 'FieldPath'; + if ($name === 'any') { + $fieldPathName = 'fieldPath'; + } else { + $resolvesToInterfaces[] = $resolvesToInterface; + } + + $expressions[$fieldPathName] = [ + 'generate' => PhpObject::PhpClass, + 'implements' => [Type\FieldPathInterface::class, $resolvesToInterface], + 'acceptedTypes' => ['string'], ]; } -return [ - 'null' => ['scalar' => true, 'types' => ['null']], - 'int' => ['scalar' => true, 'types' => ['int', BSON\Int64::class]], - 'double' => ['scalar' => true, 'types' => ['int', BSON\Int64::class, 'float']], - 'decimal' => ['scalar' => true, 'types' => ['int', BSON\Int64::class, 'float', BSON\Decimal128::class]], - 'number' => ['scalar' => true, 'types' => ['int', BSON\Int64::class, 'float', BSON\Decimal128::class]], - 'string' => ['scalar' => true, 'types' => ['string']], - 'boolean' => ['scalar' => true, 'types' => ['bool']], - 'object' => ['scalar' => true, 'types' => ['array', 'object', BSON\Document::class, BSON\Serializable::class]], +$expressions['resolvesToLong']['implements'] = [ResolvesToInt::class]; +$expressions['resolvesToInt']['implements'] = [ResolvesToNumber::class]; +$expressions['resolvesToDecimal']['implements'] = [ResolvesToDouble::class]; +$expressions['resolvesToDouble']['implements'] = [ResolvesToNumber::class]; +$expressions['resolvesToAny']['implements'] = $resolvesToInterfaces; + +return $expressions + [ + 'expression' => [ + 'returnType' => Type\ExpressionInterface::class, + 'acceptedTypes' => [Type\ExpressionInterface::class, ...$bsonTypes['any']], + ], + 'fieldQuery' => [ + 'returnType' => Type\FieldQueryInterface::class, + 'acceptedTypes' => [Type\FieldQueryInterface::class, ...$bsonTypes['any']], + ], + 'query' => [ + 'returnType' => Type\QueryInterface::class, + 'acceptedTypes' => [Type\QueryInterface::class, ...$bsonTypes['object']], + ], + 'projection' => [ + 'returnType' => Type\ProjectionInterface::class, + 'acceptedTypes' => [Type\ProjectionInterface::class, ...$bsonTypes['object']], + ], + 'accumulator' => [ + 'returnType' => Type\AccumulatorInterface::class, + 'acceptedTypes' => [Type\AccumulatorInterface::class, ...$bsonTypes['object']], + ], + 'window' => [ + 'returnType' => Type\WindowInterface::class, + 'acceptedTypes' => [Type\WindowInterface::class, ...$bsonTypes['object']], + ], + 'stage' => [ + 'returnType' => Type\StageInterface::class, + 'acceptedTypes' => [Type\StageInterface::class, ...$bsonTypes['object']], + ], + 'pipeline' => [ + 'acceptedTypes' => [Pipeline::class, ...$bsonTypes['array']], + ], + 'variable' => [ + 'generate' => PhpObject::PhpClass, + 'implements' => [ResolvesToAny::class], + 'acceptedTypes' => ['string'], + ], + 'geometry' => [ + 'returnType' => Type\GeometryInterface::class, + 'acceptedTypes' => [Type\GeometryInterface::class, ...$bsonTypes['object']], + ], + + // @todo add enum values + 'Granularity' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], + 'FullDocument' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], + 'FullDocumentBeforeChange' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], + 'AccumulatorPercentile' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], + 'WhenMatched' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], + 'WhenNotMatched' => [ + 'acceptedTypes' => [...$bsonTypes['string']], + ], - // Use Interface suffix to avoid confusion with MongoDB\Builder\Expression factory class - ExpressionInterface::class => [ - 'types' => ['mixed'], - ], - // @todo must not start with $ - // Allows ORMs to translate field names - FieldName::class => [ - 'class' => true, - 'types' => ['string'], - ], - // @todo if replaced by a string, it must start with $ - FieldPath::class => [ - 'class' => true, - 'implements' => [ExpressionInterface::class], - 'types' => ['string'], - ], - // @todo if replaced by a string, it must start with $$ - Variable::class => [ - 'class' => true, - 'implements' => [ExpressionInterface::class], - 'types' => ['string'], - ], - Literal::class => [ - 'class' => true, - 'implements' => [ExpressionInterface::class], - 'types' => ['mixed'], - ], - // @todo check for use-case - ExpressionObject::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['array', stdClass::class, BSON\Document::class, BSON\Serializable::class], - ], - // @todo check for use-case - Operator::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['array', stdClass::class, BSON\Document::class, BSON\Serializable::class], - ], - ResolvesToArray::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['list', BSONArray::class, BSON\PackedArray::class], - ], - ArrayFieldPath::class => typeFieldPath(ResolvesToArray::class), - ResolvesToBool::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['bool'], - ], - BoolFieldPath::class => typeFieldPath(ResolvesToBool::class), - ResolvesToDate::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['DateTimeInterface', 'UTCDateTime'], - ], - DateFieldPath::class => typeFieldPath(ResolvesToDate::class), - ResolvesToObject::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['array', 'object', BSON\Document::class, BSON\Serializable::class], - ], - ObjectFieldPath::class => typeFieldPath(ResolvesToObject::class), - ResolvesToNull::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['null'], - ], - NullFieldPath::class => typeFieldPath(ResolvesToNull::class), - ResolvesToNumber::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['int', 'float', BSON\Int64::class, BSON\Decimal128::class], - ], - NumberFieldPath::class => typeFieldPath(ResolvesToNumber::class), - ResolvesToDecimal::class => [ - 'implements' => [ResolvesToNumber::class], - 'types' => ['int', 'float', BSON\Int64::class, BSON\Decimal128::class], - ], - DecimalFieldPath::class => typeFieldPath(ResolvesToDecimal::class), - ResolvesToFloat::class => [ - 'implements' => [ResolvesToNumber::class], - 'types' => ['int', 'float', BSON\Int64::class], - ], - FloatFieldPath::class => typeFieldPath(ResolvesToFloat::class), - ResolvesToInt::class => [ - 'implements' => [ResolvesToNumber::class], - 'types' => ['int', BSON\Int64::class], - ], - IntFieldPath::class => typeFieldPath(ResolvesToInt::class), - ResolvesToString::class => [ - 'implements' => [ExpressionInterface::class], - 'types' => ['string'], - ], - StringFieldPath::class => typeFieldPath(ResolvesToString::class), + // @todo create specific model classes factories + 'OutCollection' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'CollStats' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'Range' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'FillOut' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'SortSpec' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'Window' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], + 'GeoPoint' => [ + 'acceptedTypes' => [...$bsonTypes['object']], + ], ]; diff --git a/generator/config/operators.php b/generator/config/operators.php deleted file mode 100644 index e9d1583e2..000000000 --- a/generator/config/operators.php +++ /dev/null @@ -1,41 +0,0 @@ - __DIR__ . '/stages.yaml', - 'namespace' => 'MongoDB\\Builder\\Stage', - 'classNameSuffix' => 'Stage', - 'generators' => [ - OperatorClassGenerator::class, - OperatorFactoryGenerator::class, - ], - ], - - // Aggregation Pipeline Operators - [ - 'configFile' => __DIR__ . '/pipeline-operators.yaml', - 'namespace' => 'MongoDB\\Builder\\Aggregation', - 'classNameSuffix' => 'Aggregation', - 'generators' => [ - OperatorClassGenerator::class, - OperatorFactoryGenerator::class, - ], - ], - - // Query Operators - [ - 'configFile' => __DIR__ . '/query-operators.yaml', - 'namespace' => 'MongoDB\\Builder\\Query', - 'classNameSuffix' => 'Query', - 'generators' => [ - OperatorClassGenerator::class, - OperatorFactoryGenerator::class, - ], - ], -]; diff --git a/generator/config/pipeline-operators.yaml b/generator/config/pipeline-operators.yaml deleted file mode 100644 index 9e2af1fc8..000000000 --- a/generator/config/pipeline-operators.yaml +++ /dev/null @@ -1,92 +0,0 @@ -- name: and - type: resolvesToBool - args: - - name: expressions - type: expression - isVariadic: true - variadicMin: 1 -- name: eq - encode: array - type: resolvesToBool - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: gt - encode: array - type: resolvesToBool - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: gte - encode: array - type: resolvesToBool - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: lt - encode: array - type: resolvesToBool - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: ne - encode: array - type: resolvesToBool - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: filter - encode: object - type: resolvesToArray - args: - - name: input - type: resolvesToArray - - name: cond - type: resolvesToBool - - name: as - type: resolvesToString - isOptional: true - - name: limit - type: resolvesToInt - isOptional: true -- name: sum - type: resolvesToInt - args: - - name: expression - type: expression -- name: min - type: expression - args: - - name: expression - type: expression -- name: max - type: expression - args: - - name: expression - type: expression -- name: subtract - type: expression - encode: array - args: - - name: expression1 - type: expression - - name: expression2 - type: expression -- name: mod - type: expression - encode: array - args: - - name: expression1 - type: expression - - name: expression2 - type: expression diff --git a/generator/config/projection/elemMatch.yaml b/generator/config/projection/elemMatch.yaml new file mode 100644 index 000000000..65554819d --- /dev/null +++ b/generator/config/projection/elemMatch.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $elemMatch + +link: 'https://www.mongodb.com/docs/manual/reference/operator/projection/elemMatch/' +type: + - projection +encode: object +description: | + Projects the first element in an array that matches the specified $elemMatch condition. +arguments: + - + name: query + type: + - query diff --git a/generator/config/projection/filter.yaml b/generator/config/projection/filter.yaml new file mode 100644 index 000000000..68a5c467a --- /dev/null +++ b/generator/config/projection/filter.yaml @@ -0,0 +1,35 @@ +# $schema: ../schema.json +name: $filter + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter/' +type: + - projection +encode: object +description: | + Selects a subset of the array to return an array with only the elements that match the filter condition. +arguments: + - + name: input + type: + - resolvesToArray + - + name: cond + type: + - resolvesToBool + description: | + An expression that resolves to a boolean value used to determine if an element should be included in the output array. The expression references each element of the input array individually with the variable name specified in as. + - + name: as + type: + - string + optional: true + description: | + A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this. + - + name: limit + type: + - resolvesToInt + optional: true + description: | + A number expression that restricts the number of matching array elements that $filter returns. You cannot specify a limit less than 1. The matching array elements are returned in the order they appear in the input array. + If the specified limit is greater than the number of matching array elements, $filter returns all matching array elements. If the limit is null, $filter returns all matching array elements. diff --git a/generator/config/projection/slice.yaml b/generator/config/projection/slice.yaml new file mode 100644 index 000000000..63d12db26 --- /dev/null +++ b/generator/config/projection/slice.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $slice + +link: 'https://www.mongodb.com/docs/manual/reference/operator/projection/slice/' +type: + - projection +encode: array +description: | + Limits the number of elements projected from an array. Supports skip and limit slices. +arguments: + - + name: limit + type: + - int + - + name: skip + type: + - int diff --git a/generator/config/query-operators.yaml b/generator/config/query-operators.yaml deleted file mode 100644 index 433038f3f..000000000 --- a/generator/config/query-operators.yaml +++ /dev/null @@ -1,32 +0,0 @@ -- name: and - type: resolvesToBool - args: - - name: query - type: resolvesToBool - isVariadic: true -- name: or - type: resolvesToBool - args: - - name: query - type: expression - isVariadic: true -- name: expr - type: expression - args: - - name: expression - type: expression -- name: gt - type: resolvesToBool - args: - - name: value - type: expression -- name: lt - type: resolvesToBool - args: - - name: value - type: expression -- name: gte - type: resolvesToBool - args: - - name: value - type: expression diff --git a/generator/config/query/all.yaml b/generator/config/query/all.yaml new file mode 100644 index 000000000..2a97cbdf4 --- /dev/null +++ b/generator/config/query/all.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $all + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/all/' +type: + - fieldQuery +encode: single +description: | + Matches arrays that contain all elements specified in the query. +arguments: + - + name: value + type: + - any + variadic: array diff --git a/generator/config/query/and.yaml b/generator/config/query/and.yaml new file mode 100644 index 000000000..b7b36c505 --- /dev/null +++ b/generator/config/query/and.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $and + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/and/' +type: + - query +encode: single +description: | + Joins query clauses with a logical AND returns all documents that match the conditions of both clauses. +arguments: + - + name: expression + type: + - query + variadic: array diff --git a/generator/config/query/bitsAllClear.yaml b/generator/config/query/bitsAllClear.yaml new file mode 100644 index 000000000..cfb76db9b --- /dev/null +++ b/generator/config/query/bitsAllClear.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $bitsAllClear + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/bitsAllClear/' +type: + - fieldQuery +encode: single +description: | + Matches numeric or binary values in which a set of bit positions all have a value of 0. +arguments: + - + name: bitmask + type: + - int + - binData + - array # of int diff --git a/generator/config/query/bitsAllSet.yaml b/generator/config/query/bitsAllSet.yaml new file mode 100644 index 000000000..34794a272 --- /dev/null +++ b/generator/config/query/bitsAllSet.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $bitsAllSet + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/bitsAllSet/' +type: + - fieldQuery +encode: single +description: | + Matches numeric or binary values in which a set of bit positions all have a value of 1. +arguments: + - + name: bitmask + type: + - int + - binData + - array # of int diff --git a/generator/config/query/bitsAnyClear.yaml b/generator/config/query/bitsAnyClear.yaml new file mode 100644 index 000000000..adb920025 --- /dev/null +++ b/generator/config/query/bitsAnyClear.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $bitsAnyClear + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/bitsAnyClear/' +type: + - fieldQuery +encode: single +description: | + Matches numeric or binary values in which any bit from a set of bit positions has a value of 0. +arguments: + - + name: bitmask + type: + - int + - binData + - array # of int diff --git a/generator/config/query/bitsAnySet.yaml b/generator/config/query/bitsAnySet.yaml new file mode 100644 index 000000000..d72a5a0b5 --- /dev/null +++ b/generator/config/query/bitsAnySet.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $bitsAnySet + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/bitsAnySet/' +type: + - fieldQuery +encode: single +description: | + Matches numeric or binary values in which any bit from a set of bit positions has a value of 1. +arguments: + - + name: bitmask + type: + - int + - binData + - array # of int diff --git a/generator/config/query/box.yaml b/generator/config/query/box.yaml new file mode 100644 index 000000000..f637c55bf --- /dev/null +++ b/generator/config/query/box.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $box + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/box/' +type: + - geometry +encode: single +description: | + Specifies a rectangular box using legacy coordinate pairs for $geoWithin queries. The 2d index supports $box. +arguments: + - + name: value + type: + - array diff --git a/generator/config/query/center.yaml b/generator/config/query/center.yaml new file mode 100644 index 000000000..5062fd928 --- /dev/null +++ b/generator/config/query/center.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $center + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/center/' +type: + - geometry +encode: single +description: | + Specifies a circle using legacy coordinate pairs to $geoWithin queries when using planar geometry. The 2d index supports $center. +arguments: + - + name: value + type: + - array diff --git a/generator/config/query/centerSphere.yaml b/generator/config/query/centerSphere.yaml new file mode 100644 index 000000000..2a79f6517 --- /dev/null +++ b/generator/config/query/centerSphere.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $centerSphere + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/' +type: + - geometry +encode: single +description: | + Specifies a circle using either legacy coordinate pairs or GeoJSON format for $geoWithin queries when using spherical geometry. The 2dsphere and 2d indexes support $centerSphere. +arguments: + - + name: value + type: + - array diff --git a/generator/config/query/comment.yaml b/generator/config/query/comment.yaml new file mode 100644 index 000000000..6fbae835d --- /dev/null +++ b/generator/config/query/comment.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $comment + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/comment/' +type: + - query +encode: single +description: | + Adds a comment to a query predicate. +arguments: + - + name: comment + type: + - string diff --git a/generator/config/query/elemMatch.yaml b/generator/config/query/elemMatch.yaml new file mode 100644 index 000000000..62f86c479 --- /dev/null +++ b/generator/config/query/elemMatch.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $elemMatch + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/elemMatch/' +type: + - fieldQuery +encode: object +description: | + The $elemMatch operator matches documents that contain an array field with at least one element that matches all the specified query criteria. +arguments: + - + name: query + type: + - query diff --git a/generator/config/query/eq.yaml b/generator/config/query/eq.yaml new file mode 100644 index 000000000..d26c7249f --- /dev/null +++ b/generator/config/query/eq.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $eq + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/eq/' +type: + - fieldQuery +encode: single +description: | + Matches values that are equal to a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/exists.yaml b/generator/config/query/exists.yaml new file mode 100644 index 000000000..197e86ab2 --- /dev/null +++ b/generator/config/query/exists.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $exists + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/exists/' +type: + - fieldQuery +encode: single +description: | + Matches documents that have the specified field. +arguments: + - + name: exists + type: + - bool diff --git a/generator/config/query/expr.yaml b/generator/config/query/expr.yaml new file mode 100644 index 000000000..8732e92a4 --- /dev/null +++ b/generator/config/query/expr.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $expr + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/expr/' +type: + - fieldQuery +encode: single +description: | + Allows use of aggregation expressions within the query language. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/query/geoIntersects.yaml b/generator/config/query/geoIntersects.yaml new file mode 100644 index 000000000..1b47c4d68 --- /dev/null +++ b/generator/config/query/geoIntersects.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $geoIntersects + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/geoIntersects/' +type: + - fieldQuery +encode: single +description: | + Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects. +arguments: + - + name: geometry + type: + - geometry diff --git a/generator/config/query/geoWithin.yaml b/generator/config/query/geoWithin.yaml new file mode 100644 index 000000000..c8ea5b21e --- /dev/null +++ b/generator/config/query/geoWithin.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $geoWithin + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/' +type: + - fieldQuery +encode: single +description: | + Selects geometries within a bounding GeoJSON geometry. The 2dsphere and 2d indexes support $geoWithin. +arguments: + - + name: geometry + type: + - geometry diff --git a/generator/config/query/geometry.yaml b/generator/config/query/geometry.yaml new file mode 100644 index 000000000..731c7acb3 --- /dev/null +++ b/generator/config/query/geometry.yaml @@ -0,0 +1,22 @@ +# $schema: ../schema.json +name: $geometry + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/geometry/' +type: + - geometry +encode: object +description: | + Specifies a geometry in GeoJSON format to geospatial query operators. +arguments: + - + name: type + type: + - string + - + name: coordinates + type: + - array + - + name: crs + type: + - object diff --git a/generator/config/query/gt.yaml b/generator/config/query/gt.yaml new file mode 100644 index 000000000..23b1d7823 --- /dev/null +++ b/generator/config/query/gt.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $gt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/gt/' +type: + - fieldQuery +encode: single +description: | + Matches values that are greater than a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/gte.yaml b/generator/config/query/gte.yaml new file mode 100644 index 000000000..f69e3151b --- /dev/null +++ b/generator/config/query/gte.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $gte + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/gte/' +type: + - fieldQuery +encode: single +description: | + Matches values that are greater than or equal to a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/in.yaml b/generator/config/query/in.yaml new file mode 100644 index 000000000..8e7175814 --- /dev/null +++ b/generator/config/query/in.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $in + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/in/' +type: + - fieldQuery +encode: single +description: | + Matches any of the values specified in an array. +arguments: + - + name: value + type: + - array # of expression diff --git a/generator/config/query/jsonSchema.yaml b/generator/config/query/jsonSchema.yaml new file mode 100644 index 000000000..b3341df7c --- /dev/null +++ b/generator/config/query/jsonSchema.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $jsonSchema + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/jsonSchema/' +type: + - query +encode: single +description: | + Validate documents against the given JSON Schema. +arguments: + - + name: schema + type: + - object diff --git a/generator/config/query/lt.yaml b/generator/config/query/lt.yaml new file mode 100644 index 000000000..5f8980a46 --- /dev/null +++ b/generator/config/query/lt.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $lt + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/lt/' +type: + - fieldQuery +encode: single +description: | + Matches values that are less than a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/lte.yaml b/generator/config/query/lte.yaml new file mode 100644 index 000000000..662fca508 --- /dev/null +++ b/generator/config/query/lte.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $lte + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/lte/' +type: + - fieldQuery +encode: single +description: | + Matches values that are less than or equal to a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/maxDistance.yaml b/generator/config/query/maxDistance.yaml new file mode 100644 index 000000000..359811868 --- /dev/null +++ b/generator/config/query/maxDistance.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $maxDistance + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/maxDistance/' +type: + - fieldQuery +encode: single +description: | + Specifies a maximum distance to limit the results of $near and $nearSphere queries. The 2dsphere and 2d indexes support $maxDistance. +arguments: + - + name: value + type: + - number diff --git a/generator/config/query/minDistance.yaml b/generator/config/query/minDistance.yaml new file mode 100644 index 000000000..95106a8ba --- /dev/null +++ b/generator/config/query/minDistance.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $minDistance + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/minDistance/' +type: + - fieldQuery +encode: single +description: | + Specifies a minimum distance to limit the results of $near and $nearSphere queries. For use with 2dsphere index only. +arguments: + - + name: value + type: + - int + - double diff --git a/generator/config/query/mod.yaml b/generator/config/query/mod.yaml new file mode 100644 index 000000000..ba6a81971 --- /dev/null +++ b/generator/config/query/mod.yaml @@ -0,0 +1,18 @@ +# $schema: ../schema.json +name: $mod + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/mod/' +type: + - fieldQuery +encode: array +description: | + Performs a modulo operation on the value of a field and selects documents with a specified result. +arguments: + - + name: divisor + type: + - int + - + name: remainder + type: + - int diff --git a/generator/config/query/natural.yaml b/generator/config/query/natural.yaml new file mode 100644 index 000000000..bef7b7311 --- /dev/null +++ b/generator/config/query/natural.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $natural + +link: 'https://www.mongodb.com/docs/v7.0/reference/operator/meta/natural/' +type: + - expression +encode: object +description: | + A special hint that can be provided via the sort() or hint() methods that can be used to force either a forward or reverse collection scan. diff --git a/generator/config/query/ne.yaml b/generator/config/query/ne.yaml new file mode 100644 index 000000000..507e7e1e0 --- /dev/null +++ b/generator/config/query/ne.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $ne + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/ne/' +type: + - fieldQuery +encode: single +description: | + Matches all values that are not equal to a specified value. +arguments: + - + name: value + type: + - any diff --git a/generator/config/query/near.yaml b/generator/config/query/near.yaml new file mode 100644 index 000000000..0cd0bc82a --- /dev/null +++ b/generator/config/query/near.yaml @@ -0,0 +1,28 @@ +# $schema: ../schema.json +name: $near + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/near/' +type: + - fieldQuery +encode: object +description: | + Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near. +arguments: + - + name: geometry + type: + - geometry + - + name: maxDistance + type: + - int + optional: true + description: | + Distance in meters. Limits the results to those documents that are at most the specified distance from the center point. + - + name: minDistance + type: + - int + optional: true + description: | + Distance in meters. Limits the results to those documents that are at least the specified distance from the center point. diff --git a/generator/config/query/nearSphere.yaml b/generator/config/query/nearSphere.yaml new file mode 100644 index 000000000..15d8aadc0 --- /dev/null +++ b/generator/config/query/nearSphere.yaml @@ -0,0 +1,28 @@ +# $schema: ../schema.json +name: $nearSphere + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/nearSphere/' +type: + - fieldQuery +encode: object +description: | + Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d indexes support $nearSphere. +arguments: + - + name: geometry + type: + - geometry + - + name: maxDistance + type: + - int + optional: true + description: | + Distance in meters. + - + name: minDistance + type: + - int + optional: true + description: | + Distance in meters. Limits the results to those documents that are at least the specified distance from the center point. diff --git a/generator/config/query/nin.yaml b/generator/config/query/nin.yaml new file mode 100644 index 000000000..ea04ed50b --- /dev/null +++ b/generator/config/query/nin.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $nin + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/nin/' +type: + - fieldQuery +encode: single +description: | + Matches none of the values specified in an array. +arguments: + - + name: value + type: + - array # of expression diff --git a/generator/config/query/nor.yaml b/generator/config/query/nor.yaml new file mode 100644 index 000000000..324bfd85f --- /dev/null +++ b/generator/config/query/nor.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $nor + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/nor/' +type: + - query +encode: single +description: | + Joins query clauses with a logical NOR returns all documents that fail to match both clauses. +arguments: + - + name: expression + type: + - query + variadic: array diff --git a/generator/config/query/not.yaml b/generator/config/query/not.yaml new file mode 100644 index 000000000..6788bf0f2 --- /dev/null +++ b/generator/config/query/not.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $not + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/not/' +type: + - fieldQuery +encode: single +description: | + Inverts the effect of a query expression and returns documents that do not match the query expression. +arguments: + - + name: expression + type: + - query + - regex diff --git a/generator/config/query/or.yaml b/generator/config/query/or.yaml new file mode 100644 index 000000000..9903d1743 --- /dev/null +++ b/generator/config/query/or.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $or + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/or/' +type: + - query +encode: single +description: | + Joins query clauses with a logical OR returns all documents that match the conditions of either clause. +arguments: + - + name: expression + type: + - query + variadic: array diff --git a/generator/config/query/polygon.yaml b/generator/config/query/polygon.yaml new file mode 100644 index 000000000..3885eeeeb --- /dev/null +++ b/generator/config/query/polygon.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $polygon + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/polygon/' +type: + - geometry +encode: single +description: | + Specifies a polygon to using legacy coordinate pairs for $geoWithin queries. The 2d index supports $center. +arguments: + - + name: points + type: + - array diff --git a/generator/config/query/rand.yaml b/generator/config/query/rand.yaml new file mode 100644 index 000000000..62ea16424 --- /dev/null +++ b/generator/config/query/rand.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $rand + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/rand/' +type: + - expression +encode: object +description: | + Generates a random float between 0 and 1. diff --git a/generator/config/query/regex.yaml b/generator/config/query/regex.yaml new file mode 100644 index 000000000..1605b5e0a --- /dev/null +++ b/generator/config/query/regex.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $regex + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/regex/' +type: + - fieldQuery +encode: single +description: | + Selects documents where values match a specified regular expression. +arguments: + - + name: regex + type: + - regex diff --git a/generator/config/query/size.yaml b/generator/config/query/size.yaml new file mode 100644 index 000000000..cceec7d8f --- /dev/null +++ b/generator/config/query/size.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $size + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/size/' +type: + - fieldQuery +encode: single +description: | + Selects documents if the array field is a specified size. +arguments: + - + name: value + type: + - int diff --git a/generator/config/query/text.yaml b/generator/config/query/text.yaml new file mode 100644 index 000000000..4ccafde32 --- /dev/null +++ b/generator/config/query/text.yaml @@ -0,0 +1,39 @@ +# $schema: ../schema.json +name: $text + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/text/' +type: + - query +encode: object +description: | + Performs text search. +arguments: + - + name: search + type: + - string + description: | + A string of terms that MongoDB parses and uses to query the text index. MongoDB performs a logical OR search of the terms unless specified as a phrase. + - + name: language + type: + - string + optional: true + description: | + The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index. + If you specify a default_language value of none, then the text index parses through each word in the field, including stop words, and ignores suffix stemming. + - + name: caseSensitive + type: + - bool + optional: true + description: | + A boolean flag to enable or disable case sensitive search. Defaults to false; i.e. the search defers to the case insensitivity of the text index. + - + name: diacriticSensitive + type: + - bool + optional: true + description: | + A boolean flag to enable or disable diacritic sensitive search against version 3 text indexes. Defaults to false; i.e. the search defers to the diacritic insensitivity of the text index. + Text searches against earlier versions of the text index are inherently diacritic sensitive and cannot be diacritic insensitive. As such, the $diacriticSensitive option has no effect with earlier versions of the text index. diff --git a/generator/config/query/type.yaml b/generator/config/query/type.yaml new file mode 100644 index 000000000..799136110 --- /dev/null +++ b/generator/config/query/type.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $type + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/type/' +type: + - fieldQuery +encode: single +description: | + Selects documents if a field is of the specified type. +arguments: + - + name: type + type: + - int + - string + - array # of int or string diff --git a/generator/config/query/where.yaml b/generator/config/query/where.yaml new file mode 100644 index 000000000..205d615ea --- /dev/null +++ b/generator/config/query/where.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $where + +link: 'https://www.mongodb.com/docs/manual/reference/operator/query/where/' +type: + - query +encode: single +description: | + Matches documents that satisfy a JavaScript expression. +arguments: + - + name: function + type: + - string diff --git a/generator/config/schema.json b/generator/config/schema.json new file mode 100644 index 000000000..ca61931bb --- /dev/null +++ b/generator/config/schema.json @@ -0,0 +1,165 @@ +{ + "$schema": "http://json-schema.org/draft-06/schema#", + "$ref": "#/definitions/Operator", + "definitions": { + "Operator": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "$comment": "The name of the operator. Must start with a $", + "type": "string", + "pattern": "^\\$[a-z][a-zA-Z]+$" + }, + "link": { + "$comment": "The link to the operator's documentation on MongoDB's website.", + "type": "string", + "format": "uri", + "qt-uri-protocols": [ + "https" + ] + }, + "type": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "accumulator", + "projection", + "stage", + "query", + "filter", + "window", + "geometry", + "resolvesToAny", + "resolvesToNumber", + "resolvesToDouble", + "resolvesToString", + "resolvesToObject", + "resolvesToArray", + "resolvesToBinData", + "resolvesToObjectId", + "resolvesToBool", + "resolvesToDate", + "resolvesToNull", + "resolvesToRegex", + "resolvesToJavascript", + "resolvesToInt", + "resolvesToTimestamp", + "resolvesToLong", + "resolvesToDecimal" + ] + } + }, + "encode": { + "$comment": "Specifies how operator parameters are encoded.", + "$comment": "array: parameters are encoded as an array of values in the order they are defined by the spec", + "$comment": "object: parameters are encoded as an object with keys matching the parameter names", + "$comment": "single: get the single parameter value", + "$comment": "group: specific for $group stage", + "type": "string", + "enum": [ + "array", + "object", + "single", + "group" + ] + }, + "description": { + "$comment": "The description of the argument from MongoDB's documentation.", + "type": "string" + }, + "arguments": { + "$comment": "An optional list of arguments for the operator.", + "type": "array", + "items": { + "$ref": "#/definitions/Argument" + } + } + }, + "required": [ + "description", + "encode", + "link", + "name", + "type" + ], + "title": "Operator" + }, + "Argument": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "pattern": "^([a-z][a-zA-Z0-9]*|N)$" + }, + "type": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "accumulator", + "query", + "pipeline", + "window", + "expression", + "geometry", + "any", + "resolvesToNumber", "numberFieldPath", "number", + "resolvesToDouble", "doubleFieldPath", "double", + "resolvesToString", "stringFieldPath", "string", + "resolvesToObject", "objectFieldPath", "object", + "resolvesToArray", "arrayFieldPath", "array", + "resolvesToBinData", "binDataFieldPath", "binData", + "resolvesToObjectId", "objectIdFieldPath", "objectId", + "resolvesToBool", "boolFieldPath", "bool", + "resolvesToDate", "dateFieldPath", "date", + "resolvesToNull", "nullFieldPath", "null", + "resolvesToRegex", "regexFieldPath", "regex", + "resolvesToJavascript", "javascriptFieldPath", "javascript", + "resolvesToInt", "intFieldPath", "int", + "resolvesToTimestamp", "timestampFieldPath", "timestamp", + "resolvesTolong", "longFieldPath", "long", + "resolvesToDecimal", "decimalFieldPath", "decimal" + ] + } + }, + "description": { + "$comment": "The description of the argument from MongoDB's documentation.", + "type": "string" + }, + "optional": { + "$comment": "Whether the argument is optional or not.", + "type": "boolean" + }, + "valueMin": { + "$comment": "The minimum value for a numeric argument.", + "type": "number" + }, + "valueMax": { + "$comment": "The minimum value for a numeric argument.", + "type": "number" + }, + "variadic": { + "$comment": "Whether the argument is variadic or not.", + "type": "string", + "enum": [ + "array", + "object" + ] + }, + "variadicMin": { + "$comment": "The minimum number of arguments for a variadic parameter.", + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "name", + "type" + ], + "title": "Argument" + } + } +} diff --git a/generator/config/stage/addFields.yaml b/generator/config/stage/addFields.yaml new file mode 100644 index 000000000..1f2c5162a --- /dev/null +++ b/generator/config/stage/addFields.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $addFields + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/addFields/' +type: + - stage +encode: single +description: | + Adds new fields to documents. Outputs documents that contain all existing fields from the input documents and newly added fields. +arguments: + - + name: expression + type: + - expression + variadic: object + description: | + Specify the name of each field to add and set its value to an aggregation expression or an empty object. diff --git a/generator/config/stage/bucket.yaml b/generator/config/stage/bucket.yaml new file mode 100644 index 000000000..262b92713 --- /dev/null +++ b/generator/config/stage/bucket.yaml @@ -0,0 +1,43 @@ +# $schema: ../schema.json +name: $bucket + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucket/' +type: + - stage +encode: object +description: | + Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries. +arguments: + - + name: groupBy + type: + - expression # mainly fieldPath + description: | + An expression to group documents by. To specify a field path, prefix the field name with a dollar sign $ and enclose it in quotes. + Unless $bucket includes a default specification, each input document must resolve the groupBy field path or expression to a value that falls within one of the ranges specified by the boundaries. + - + name: boundaries + type: + - array # of expression + description: | + An array of values based on the groupBy expression that specify the boundaries for each bucket. Each adjacent pair of values acts as the inclusive lower boundary and the exclusive upper boundary for the bucket. You must specify at least two boundaries. + The specified values must be in ascending order and all of the same type. The exception is if the values are of mixed numeric types, such as: + - + name: default + type: + - expression + optional: true + description: | + A literal that specifies the _id of an additional bucket that contains all documents whose groupBy expression result does not fall into a bucket specified by boundaries. + If unspecified, each input document must resolve the groupBy expression to a value within one of the bucket ranges specified by boundaries or the operation throws an error. + The default value must be less than the lowest boundaries value, or greater than or equal to the highest boundaries value. + The default value can be of a different type than the entries in boundaries. + - + name: output + type: + - object # of Accumulator + optional: true + description: | + A document that specifies the fields to include in the output documents in addition to the _id field. To specify the field to include, you must use accumulator expressions. + If you do not specify an output document, the operation returns a count field containing the number of documents in each bucket. + If you specify an output document, only the fields specified in the document are returned; i.e. the count field is not returned unless it is explicitly included in the output document. diff --git a/generator/config/stage/bucketAuto.yaml b/generator/config/stage/bucketAuto.yaml new file mode 100644 index 000000000..e6cda7cfd --- /dev/null +++ b/generator/config/stage/bucketAuto.yaml @@ -0,0 +1,38 @@ +# $schema: ../schema.json +name: $bucketAuto + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketAuto/' +type: + - stage +encode: object +description: | + Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression. Bucket boundaries are automatically determined in an attempt to evenly distribute the documents into the specified number of buckets. +arguments: + - + name: groupBy + type: + - expression + description: | + An expression to group documents by. To specify a field path, prefix the field name with a dollar sign $ and enclose it in quotes. + - + name: buckets + type: + - int + description: | + A positive 32-bit integer that specifies the number of buckets into which input documents are grouped. + - + name: output + type: + - object # of Accumulator + optional: true + description: | + A document that specifies the fields to include in the output documents in addition to the _id field. To specify the field to include, you must use accumulator expressions. + The default count field is not included in the output document when output is specified. Explicitly specify the count expression as part of the output document to include it. + - + name: granularity + type: + - object # Granularity + optional: true + description: | + A string that specifies the preferred number series to use to ensure that the calculated boundary edges end on preferred round numbers or their powers of 10. + Available only if the all groupBy values are numeric and none of them are NaN. diff --git a/generator/config/stage/changeStream.yaml b/generator/config/stage/changeStream.yaml new file mode 100644 index 000000000..659384aba --- /dev/null +++ b/generator/config/stage/changeStream.yaml @@ -0,0 +1,60 @@ +# $schema: ../schema.json +name: $changeStream + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStream/' +type: + - stage +encode: object +description: | + Returns a Change Stream cursor for the collection or database. This stage can only occur once in an aggregation pipeline and it must occur as the first stage. +arguments: + - + name: allChangesForCluster + type: + - bool + optional: true + description: | + A flag indicating whether the stream should report all changes that occur on the deployment, aside from those on internal databases or collections. + - + name: fullDocument + type: + - FullDocument + optional: true + description: | + Specifies whether change notifications include a copy of the full document when modified by update operations. + - + name: fullDocumentBeforeChange + type: + - FullDocumentBeforeChange + optional: true + description: | + Valid values are "off", "whenAvailable", or "required". If set to "off", the "fullDocumentBeforeChange" field of the output document is always omitted. If set to "whenAvailable", the "fullDocumentBeforeChange" field will be populated with the pre-image of the document modified by the current change event if such a pre-image is available, and will be omitted otherwise. If set to "required", then the "fullDocumentBeforeChange" field is always populated and an exception is thrown if the pre-image is not available. + - + name: resumeAfter + type: + - int + optional: true + description: | + Specifies a resume token as the logical starting point for the change stream. Cannot be used with startAfter or startAtOperationTime fields. + - + name: showExpandedEvents + type: + - bool + optional: true + description: | + Specifies whether to include additional change events, such as such as DDL and index operations. + New in version 6.0. + - + name: startAfter + type: + - object + optional: true + description: | + Specifies a resume token as the logical starting point for the change stream. Cannot be used with resumeAfter or startAtOperationTime fields. + - + name: startAtOperationTime + type: + - timestamp + optional: true + description: | + Specifies a time as the logical starting point for the change stream. Cannot be used with resumeAfter or startAfter fields. diff --git a/generator/config/stage/changeStreamSplitLargeEvent.yaml b/generator/config/stage/changeStreamSplitLargeEvent.yaml new file mode 100644 index 000000000..6ecbbeef4 --- /dev/null +++ b/generator/config/stage/changeStreamSplitLargeEvent.yaml @@ -0,0 +1,10 @@ +# $schema: ../schema.json +name: $changeStreamSplitLargeEvent + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStreamSplitLargeEvent/' +type: + - stage +encode: object +description: | + Splits large change stream events that exceed 16 MB into smaller fragments returned in a change stream cursor. + You can only use $changeStreamSplitLargeEvent in a $changeStream pipeline and it must be the final stage in the pipeline. diff --git a/generator/config/stage/collStats.yaml b/generator/config/stage/collStats.yaml new file mode 100644 index 000000000..5fbbc5060 --- /dev/null +++ b/generator/config/stage/collStats.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $collStats + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/' +type: + - stage +encode: single +description: | + Returns statistics regarding a collection or view. +arguments: + - + name: config + type: + - object diff --git a/generator/config/stage/count.yaml b/generator/config/stage/count.yaml new file mode 100644 index 000000000..a22621c59 --- /dev/null +++ b/generator/config/stage/count.yaml @@ -0,0 +1,17 @@ +# $schema: ../schema.json +name: $count + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/count/' +type: + - stage +encode: single +description: | + Returns a count of the number of documents at this stage of the aggregation pipeline. + Distinct from the $count aggregation accumulator. +arguments: + - + name: field + type: + - string + description: | + Name of the output field which has the count as its value. It must be a non-empty string, must not start with $ and must not contain the . character. diff --git a/generator/config/stage/currentOp.yaml b/generator/config/stage/currentOp.yaml new file mode 100644 index 000000000..be677f117 --- /dev/null +++ b/generator/config/stage/currentOp.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $currentOp + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentOp/' +type: + - stage +encode: object +description: | + Returns information on active and/or dormant operations for the MongoDB deployment. To run, use the db.aggregate() method. diff --git a/generator/config/stage/densify.yaml b/generator/config/stage/densify.yaml new file mode 100644 index 000000000..1c92837c9 --- /dev/null +++ b/generator/config/stage/densify.yaml @@ -0,0 +1,31 @@ +# $schema: ../schema.json +name: $densify + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/' +type: + - stage +encode: object +description: | + Creates new documents in a sequence of documents where certain values in a field are missing. +arguments: + - + name: field + type: + - string # field name + description: | + The field to densify. The values of the specified field must either be all numeric values or all dates. + Documents that do not contain the specified field continue through the pipeline unmodified. + To specify a in an embedded document or in an array, use dot notation. + - + name: partitionByFields + type: + - array # of string + optional: true + description: | + The field(s) that will be used as the partition keys. + - + name: range + type: + - object # Range + description: | + Specification for range based densification. diff --git a/generator/config/stage/documents.yaml b/generator/config/stage/documents.yaml new file mode 100644 index 000000000..af434a6d6 --- /dev/null +++ b/generator/config/stage/documents.yaml @@ -0,0 +1,20 @@ +# $schema: ../schema.json +name: $documents + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/' +type: + - stage +encode: single +description: | + Returns literal documents from input values. +arguments: + - + name: documents + type: + - resolvesToArray # of object + description: | + $documents accepts any valid expression that resolves to an array of objects. This includes: + - system variables, such as $$NOW or $$SEARCH_META + - $let expressions + - variables in scope from $lookup expressions + Expressions that do not resolve to a current document, like $myField or $$ROOT, will result in an error. diff --git a/generator/config/stage/facet.yaml b/generator/config/stage/facet.yaml new file mode 100644 index 000000000..4861a38fc --- /dev/null +++ b/generator/config/stage/facet.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $facet + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/' +type: + - stage +encode: single +description: | + Processes multiple aggregation pipelines within a single stage on the same set of input documents. Enables the creation of multi-faceted aggregations capable of characterizing data across multiple dimensions, or facets, in a single stage. +arguments: + - + name: facet + type: + - pipeline + variadic: object diff --git a/generator/config/stage/fill.yaml b/generator/config/stage/fill.yaml new file mode 100644 index 000000000..90a4012a3 --- /dev/null +++ b/generator/config/stage/fill.yaml @@ -0,0 +1,43 @@ +# $schema: ../schema.json +name: $fill + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/' +type: + - stage +encode: object +description: | + Populates null and missing field values within documents. +arguments: + - + name: partitionBy + type: + - object # of expression + - string + optional: true + description: | + Specifies an expression to group the documents. In the $fill stage, a group of documents is known as a partition. + If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection. + partitionBy and partitionByFields are mutually exclusive. + - + name: partitionByFields + type: + - array # of string + optional: true + description: | + Specifies an array of fields as the compound key to group the documents. In the $fill stage, each group of documents is known as a partition. + If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection. + partitionBy and partitionByFields are mutually exclusive. + - + name: sortBy + type: + - object # SortSpec + optional: true + description: | + Specifies the field or fields to sort the documents within each partition. Uses the same syntax as the $sort stage. + - + name: output + type: + - object # of object{value:expression} or object{method:string}> + description: | + Specifies an object containing each field for which to fill missing values. You can specify multiple fields in the output object. + The object name is the name of the field to fill. The object value specifies how the field is filled. diff --git a/generator/config/stage/geoNear.yaml b/generator/config/stage/geoNear.yaml new file mode 100644 index 000000000..26cb41192 --- /dev/null +++ b/generator/config/stage/geoNear.yaml @@ -0,0 +1,77 @@ +# $schema: ../schema.json +name: $geoNear + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/' +type: + - stage +encode: object +description: | + Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field. +arguments: + - + name: distanceField + type: + - string + description: | + The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation. + - + name: distanceMultiplier + type: + - number + optional: true + description: | + The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth. + - + name: includeLocs + type: + - string + optional: true + description: | + This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation. + - + name: key + type: + - string + optional: true + description: | + Specify the geospatial indexed field to use when calculating the distance. + - + name: maxDistance + type: + - number + optional: true + description: | + The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point. + Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs. + - + name: minDistance + type: + - number + optional: true + description: | + The minimum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall outside the specified distance from the center point. + Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs. + - + name: near + type: + - object # GeoPoint + description: | + The point for which to find the closest documents. + - + name: query + type: + - query + optional: true + description: | + Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax. + You cannot specify a $near predicate in the query field of the $geoNear stage. + - + name: spherical + type: + - bool + optional: true + description: | + Determines how MongoDB calculates the distance between two points: + - When true, MongoDB uses $nearSphere semantics and calculates distances using spherical geometry. + - When false, MongoDB uses $near semantics: spherical geometry for 2dsphere indexes and planar geometry for 2d indexes. + Default: false. diff --git a/generator/config/stage/graphLookup.yaml b/generator/config/stage/graphLookup.yaml new file mode 100644 index 000000000..ef14905cd --- /dev/null +++ b/generator/config/stage/graphLookup.yaml @@ -0,0 +1,63 @@ +# $schema: ../schema.json +name: $graphLookup + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/' +type: + - stage +encode: object +description: | + Performs a recursive search on a collection. To each output document, adds a new array field that contains the traversal results of the recursive search for that document. +arguments: + - + name: from + type: + - string + description: | + Target collection for the $graphLookup operation to search, recursively matching the connectFromField to the connectToField. The from collection must be in the same database as any other collections used in the operation. + Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded. + - + name: startWith + type: + - expression + - array + description: | + Expression that specifies the value of the connectFromField with which to start the recursive search. Optionally, startWith may be array of values, each of which is individually followed through the traversal process. + - + name: connectFromField + type: + - string + description: | + Field name whose value $graphLookup uses to recursively match against the connectToField of other documents in the collection. If the value is an array, each element is individually followed through the traversal process. + - + name: connectToField + type: + - string + description: | + Field name in other documents against which to match the value of the field specified by the connectFromField parameter. + - + name: as + type: + - string + description: | + Name of the array field added to each output document. Contains the documents traversed in the $graphLookup stage to reach the document. + - + name: maxDepth + type: + - int + optional: true + description: | + Non-negative integral number specifying the maximum recursion depth. + - + name: depthField + type: + - string + optional: true + description: | + Name of the field to add to each traversed document in the search path. The value of this field is the recursion depth for the document, represented as a NumberLong. Recursion depth value starts at zero, so the first lookup corresponds to zero depth. + - + name: restrictSearchWithMatch + type: + - query + optional: true + description: | + A document specifying additional conditions for the recursive search. The syntax is identical to query filter syntax. diff --git a/generator/config/stage/group.yaml b/generator/config/stage/group.yaml new file mode 100644 index 000000000..21402a919 --- /dev/null +++ b/generator/config/stage/group.yaml @@ -0,0 +1,23 @@ +# $schema: ../schema.json +name: $group + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/' +type: + - stage +encode: group +description: | + Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields. +arguments: + - + name: _id + type: + - expression + description: | + The _id expression specifies the group key. If you specify an _id value of null, or any other constant value, the $group stage returns a single document that aggregates values across all of the input documents. + - + name: field + type: + - accumulator + variadic: object + description: | + Computed using the accumulator operators. diff --git a/generator/config/stage/indexStats.yaml b/generator/config/stage/indexStats.yaml new file mode 100644 index 000000000..fef249048 --- /dev/null +++ b/generator/config/stage/indexStats.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $indexStats + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/' +type: + - stage +encode: object +description: | + Returns statistics regarding the use of each index for the collection. diff --git a/generator/config/stage/limit.yaml b/generator/config/stage/limit.yaml new file mode 100644 index 000000000..72bab62b4 --- /dev/null +++ b/generator/config/stage/limit.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $limit + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/' +type: + - stage +encode: single +description: | + Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents). +arguments: + - + name: limit + type: + - int diff --git a/generator/config/stage/listLocalSessions.yaml b/generator/config/stage/listLocalSessions.yaml new file mode 100644 index 000000000..7dce16c99 --- /dev/null +++ b/generator/config/stage/listLocalSessions.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $listLocalSessions + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/' +type: + - stage +encode: object +description: | + Lists all active sessions recently in use on the currently connected mongos or mongod instance. These sessions may have not yet propagated to the system.sessions collection. +arguments: + - + name: users + type: + - array + optional: true + description: | + Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users. + - + name: allUsers + type: + - bool + optional: true + description: | + Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster. diff --git a/generator/config/stage/listSampledQueries.yaml b/generator/config/stage/listSampledQueries.yaml new file mode 100644 index 000000000..5e48359e0 --- /dev/null +++ b/generator/config/stage/listSampledQueries.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $listSampledQueries + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/' +type: + - stage +encode: object +description: | + Lists sampled queries for all collections or a specific collection. +arguments: + - + name: namespace + type: + - string + optional: true diff --git a/generator/config/stage/listSearchIndexes.yaml b/generator/config/stage/listSearchIndexes.yaml new file mode 100644 index 000000000..6f7e6861e --- /dev/null +++ b/generator/config/stage/listSearchIndexes.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $listSearchIndexes + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/' +type: + - stage +encode: object +description: | + Returns information about existing Atlas Search indexes on a specified collection. +arguments: + - + name: id + type: + - string + optional: true + description: | + The id of the index to return information about. + - + name: name + type: + - string + optional: true + description: | + The name of the index to return information about. diff --git a/generator/config/stage/listSessions.yaml b/generator/config/stage/listSessions.yaml new file mode 100644 index 000000000..7f7c1e4cc --- /dev/null +++ b/generator/config/stage/listSessions.yaml @@ -0,0 +1,24 @@ +# $schema: ../schema.json +name: $listSessions + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/' +type: + - stage +encode: object +description: | + Lists all sessions that have been active long enough to propagate to the system.sessions collection. +arguments: + - + name: users + type: + - array + optional: true + description: | + Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users. + - + name: allUsers + type: + - bool + optional: true + description: | + Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster. diff --git a/generator/config/stage/lookup.yaml b/generator/config/stage/lookup.yaml new file mode 100644 index 000000000..11c61ee89 --- /dev/null +++ b/generator/config/stage/lookup.yaml @@ -0,0 +1,55 @@ +# $schema: ../schema.json +name: $lookup + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/' +type: + - stage +encode: object +description: | + Performs a left outer join to another collection in the same database to filter in documents from the "joined" collection for processing. +arguments: + - + name: from + type: + - string + optional: true + description: | + Specifies the collection in the same database to perform the join with. + from is optional, you can use a $documents stage in a $lookup stage instead. For an example, see Use a $documents Stage in a $lookup Stage. + Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded. + - + name: localField + type: + - string + optional: true + description: | + Specifies the field from the documents input to the $lookup stage. $lookup performs an equality match on the localField to the foreignField from the documents of the from collection. If an input document does not contain the localField, the $lookup treats the field as having a value of null for matching purposes. + - + name: foreignField + type: + - string + optional: true + description: | + Specifies the field from the documents in the from collection. $lookup performs an equality match on the foreignField to the localField from the input documents. If a document in the from collection does not contain the foreignField, the $lookup treats the value as null for matching purposes. + - + name: let + type: + - object # of expression + optional: true + description: | + Specifies variables to use in the pipeline stages. Use the variable expressions to access the fields from the joined collection's documents that are input to the pipeline. + - + name: pipeline + type: + - pipeline + optional: true + description: | + Specifies the pipeline to run on the joined collection. The pipeline determines the resulting documents from the joined collection. To return all documents, specify an empty pipeline []. + The pipeline cannot include the $out stage or the $mergestage. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline. + The pipeline cannot directly access the joined document fields. Instead, define variables for the joined document fields using the let option and then reference the variables in the pipeline stages. + - + name: as + type: + - string + description: | + Specifies the name of the new array field to add to the input documents. The new array field contains the matching documents from the from collection. If the specified name already exists in the input document, the existing field is overwritten. diff --git a/generator/config/stage/match.yaml b/generator/config/stage/match.yaml new file mode 100644 index 000000000..cb387e8f0 --- /dev/null +++ b/generator/config/stage/match.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $match + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/' +type: + - stage +encode: single +description: | + Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match). +arguments: + - + name: query + type: + - query diff --git a/generator/config/stage/merge.yaml b/generator/config/stage/merge.yaml new file mode 100644 index 000000000..958d88fc6 --- /dev/null +++ b/generator/config/stage/merge.yaml @@ -0,0 +1,47 @@ +# $schema: ../schema.json +name: $merge + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/' +type: + - stage +encode: object +description: | + Writes the resulting documents of the aggregation pipeline to a collection. The stage can incorporate (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) the results into an output collection. To use the $merge stage, it must be the last stage in the pipeline. + New in version 4.2. +arguments: + - + name: into + type: + - string + #- OutCollection + description: | + The output collection. + - + name: 'on' + type: + - string + - array # of string + optional: true + description: | + Field or fields that act as a unique identifier for a document. The identifier determines if a results document matches an existing document in the output collection. + - + name: let + type: + - object + optional: true + description: | + Specifies variables for use in the whenMatched pipeline. + - + name: whenMatched + type: + - string # WhenMatched + optional: true + description: | + The behavior of $merge if a result document and an existing document in the collection have the same value for the specified on field(s). + - + name: whenNotMatched + type: + - WhenNotMatched + optional: true + description: | + The behavior of $merge if a result document does not match an existing document in the out collection. diff --git a/generator/config/stage/out.yaml b/generator/config/stage/out.yaml new file mode 100644 index 000000000..85fc95bd9 --- /dev/null +++ b/generator/config/stage/out.yaml @@ -0,0 +1,29 @@ +# $schema: ../schema.json +name: $out + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/' +type: + - stage +encode: object +description: | + Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline. +arguments: + - + name: db + type: + - string + description: | + Target collection name to write documents from $out to. + - + name: coll + type: + - string + description: | + Target database name to write documents from $out to. + - + name: timeseries + type: + - object + optional: true + description: | + If set, the aggregation stage will use these options to create or replace a time-series collection in the given namespace. diff --git a/generator/config/stage/planCacheStats.yaml b/generator/config/stage/planCacheStats.yaml new file mode 100644 index 000000000..2a5e5b5b4 --- /dev/null +++ b/generator/config/stage/planCacheStats.yaml @@ -0,0 +1,9 @@ +# $schema: ../schema.json +name: $planCacheStats + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/' +type: + - stage +encode: object +description: | + Returns plan cache information for a collection. diff --git a/generator/config/stage/project.yaml b/generator/config/stage/project.yaml new file mode 100644 index 000000000..40cfd9650 --- /dev/null +++ b/generator/config/stage/project.yaml @@ -0,0 +1,19 @@ +# $schema: ../schema.json +name: $project + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/' +type: + - stage +encode: single +description: | + Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document. +arguments: + - + name: specification + type: + - bool + - int + - projection + - resolvesToBool + - object + variadic: object diff --git a/generator/config/stage/redact.yaml b/generator/config/stage/redact.yaml new file mode 100644 index 000000000..cd378dc58 --- /dev/null +++ b/generator/config/stage/redact.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $redact + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/' +type: + - stage +encode: single +description: | + Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero documents. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/stage/replaceRoot.yaml b/generator/config/stage/replaceRoot.yaml new file mode 100644 index 000000000..a0207c242 --- /dev/null +++ b/generator/config/stage/replaceRoot.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $replaceRoot + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/' +type: + - stage +encode: object +description: | + Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. +arguments: + - + name: newRoot + type: + - resolvesToObject diff --git a/generator/config/stage/replaceWith.yaml b/generator/config/stage/replaceWith.yaml new file mode 100644 index 000000000..b050b8007 --- /dev/null +++ b/generator/config/stage/replaceWith.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $replaceWith + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/' +type: + - stage +encode: single +description: | + Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. + Alias for $replaceRoot. +arguments: + - + name: expression + type: + - resolvesToObject diff --git a/generator/config/stage/sample.yaml b/generator/config/stage/sample.yaml new file mode 100644 index 000000000..562b9f1db --- /dev/null +++ b/generator/config/stage/sample.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $sample + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/' +type: + - stage +encode: object +description: | + Randomly selects the specified number of documents from its input. +arguments: + - + name: size + type: + - int + description: | + The number of documents to randomly select. diff --git a/generator/config/stage/search.yaml b/generator/config/stage/search.yaml new file mode 100644 index 000000000..bab223a19 --- /dev/null +++ b/generator/config/stage/search.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $search + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/search/' +type: + - stage +encode: single +description: | + Performs a full-text search of the field or fields in an Atlas collection. + NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. +arguments: + - + name: search + type: + - object diff --git a/generator/config/stage/searchMeta.yaml b/generator/config/stage/searchMeta.yaml new file mode 100644 index 000000000..368d60a1c --- /dev/null +++ b/generator/config/stage/searchMeta.yaml @@ -0,0 +1,15 @@ +# $schema: ../schema.json +name: $searchMeta + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/searchMeta/' +type: + - stage +encode: single +description: | + Returns different types of metadata result documents for the Atlas Search query against an Atlas collection. + NOTE: $searchMeta is only available for MongoDB Atlas clusters running MongoDB v4.4.9 or higher, and is not available for self-managed deployments. +arguments: + - + name: meta + type: + - object diff --git a/generator/config/stage/set.yaml b/generator/config/stage/set.yaml new file mode 100644 index 000000000..50931a43d --- /dev/null +++ b/generator/config/stage/set.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $set + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/' +type: + - stage +encode: single +description: | + Adds new fields to documents. Outputs documents that contain all existing fields from the input documents and newly added fields. + Alias for $addFields. +arguments: + - + name: field + type: + - expression + variadic: object diff --git a/generator/config/stage/setWindowFields.yaml b/generator/config/stage/setWindowFields.yaml new file mode 100644 index 000000000..302a704a8 --- /dev/null +++ b/generator/config/stage/setWindowFields.yaml @@ -0,0 +1,37 @@ +# $schema: ../schema.json +name: $setWindowFields + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/' +type: + - stage +encode: object +description: | + Groups documents into windows and applies one or more operators to the documents in each window. + New in version 5.0. +arguments: + - + name: partitionBy + type: + - expression + description: | + Specifies an expression to group the documents. In the $setWindowFields stage, the group of documents is known as a partition. Default is one partition for the entire collection. + - + name: sortBy + type: + - SortSpec + description: | + Specifies the field(s) to sort the documents by in the partition. Uses the same syntax as the $sort stage. Default is no sorting. + - + name: output + type: + - object + description: | + Specifies the field(s) to append to the documents in the output returned by the $setWindowFields stage. Each field is set to the result returned by the window operator. + A field can contain dots to specify embedded document fields and array fields. The semantics for the embedded document dotted notation in the $setWindowFields stage are the same as the $addFields and $set stages. + - + name: window + type: + - Window + optional: true + description: | + Specifies the window boundaries and parameters. Window boundaries are inclusive. Default is an unbounded window, which includes all documents in the partition. diff --git a/generator/config/stage/shardedDataDistribution.yaml b/generator/config/stage/shardedDataDistribution.yaml new file mode 100644 index 000000000..c430a4178 --- /dev/null +++ b/generator/config/stage/shardedDataDistribution.yaml @@ -0,0 +1,10 @@ +# $schema: ../schema.json +name: $shardedDataDistribution + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/' +type: + - stage +encode: object +description: | + Provides data and size distribution information on sharded collections. + New in version 6.0.3. diff --git a/generator/config/stage/skip.yaml b/generator/config/stage/skip.yaml new file mode 100644 index 000000000..93676473d --- /dev/null +++ b/generator/config/stage/skip.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $skip + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/' +type: + - stage +encode: single +description: | + Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents). +arguments: + - + name: skip + type: + - int diff --git a/generator/config/stage/sort.yaml b/generator/config/stage/sort.yaml new file mode 100644 index 000000000..e858254b8 --- /dev/null +++ b/generator/config/stage/sort.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $sort + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/' +type: + - stage +encode: single +description: | + Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document. +arguments: + - + name: sort + type: + - SortSpec diff --git a/generator/config/stage/sortByCount.yaml b/generator/config/stage/sortByCount.yaml new file mode 100644 index 000000000..66cfe204c --- /dev/null +++ b/generator/config/stage/sortByCount.yaml @@ -0,0 +1,14 @@ +# $schema: ../schema.json +name: $sortByCount + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/' +type: + - stage +encode: object +description: | + Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. +arguments: + - + name: expression + type: + - expression diff --git a/generator/config/stage/unionWith.yaml b/generator/config/stage/unionWith.yaml new file mode 100644 index 000000000..71c32ee26 --- /dev/null +++ b/generator/config/stage/unionWith.yaml @@ -0,0 +1,25 @@ +# $schema: ../schema.json +name: $unionWith + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/' +type: + - stage +encode: object +description: | + Performs a union of two collections; i.e. combines pipeline results from two collections into a single result set. + New in version 4.4. +arguments: + - + name: coll + type: + - string + description: | + The collection or view whose pipeline results you wish to include in the result set. + - + name: pipeline + type: + - pipeline + optional: true + description: | + An aggregation pipeline to apply to the specified coll. + The pipeline cannot include the $out and $merge stages. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline. diff --git a/generator/config/stage/unset.yaml b/generator/config/stage/unset.yaml new file mode 100644 index 000000000..16a11de6a --- /dev/null +++ b/generator/config/stage/unset.yaml @@ -0,0 +1,16 @@ +# $schema: ../schema.json +name: $unset + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/' +type: + - stage +encode: single +description: | + Removes or excludes fields from documents. + Alias for $project stage that removes or excludes fields. +arguments: + - + name: field + type: + - fieldPath + variadic: array diff --git a/generator/config/stage/unwind.yaml b/generator/config/stage/unwind.yaml new file mode 100644 index 000000000..985abf2a6 --- /dev/null +++ b/generator/config/stage/unwind.yaml @@ -0,0 +1,32 @@ +# $schema: ../schema.json +name: $unwind + +link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/' +type: + - stage +encode: object +description: | + Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array. +arguments: + - + name: path + type: + - arrayFieldPath + description: | + Field path to an array field. + - + name: includeArrayIndex + type: + - string + optional: true + description: | + The name of a new field to hold the array index of the element. The name cannot start with a dollar sign $. + - + name: preserveNullAndEmptyArrays + type: + - bool + optional: true + description: | + If true, if the path is null, missing, or an empty array, $unwind outputs the document. + If false, if path is null, missing, or an empty array, $unwind does not output a document. + The default value is false. diff --git a/generator/config/stages.yaml b/generator/config/stages.yaml deleted file mode 100644 index b973c6db2..000000000 --- a/generator/config/stages.yaml +++ /dev/null @@ -1,33 +0,0 @@ -- name: match - type: stage - args: - - name: query - type: expression -- name: sort - type: stage - args: - # @todo should generate be a map, not a list - - name: sortSpecification - type: [int, object] # should be an enum PHPLIB-1269 - isVariadic: true -- name: limit - type: stage - args: - - name: limit - type: int -- name: group - type: stage - encode: object - args: - - name: _id - type: [expression, "null"] - - name: fields - type: expression - isVariadic: true - variadicMin: 0 -- name: project - type: stage - args: - - name: specifications - type: expression - isVariadic: true diff --git a/generator/src/AbstractGenerator.php b/generator/src/AbstractGenerator.php index 406184e47..49c705906 100644 --- a/generator/src/AbstractGenerator.php +++ b/generator/src/AbstractGenerator.php @@ -18,6 +18,7 @@ use function file_put_contents; use function implode; use function is_dir; +use function ltrim; use function mkdir; use function sprintf; use function str_replace; @@ -40,7 +41,7 @@ public function __construct( */ final protected function splitNamespaceAndClassName(string $fqcn): array { - $parts = explode('\\', $fqcn); + $parts = explode('\\', ltrim($fqcn, '\\')); $className = array_pop($parts); return [implode('\\', $parts), $className]; @@ -51,7 +52,7 @@ final protected function writeFile(PhpNamespace $namespace): void $classes = $namespace->getClasses(); assert(count($classes) === 1, sprintf('Expected exactly one class in namespace "%s", got %d.', $namespace->getName(), count($classes))); - $filename = $this->rootDir . '/' . $this->getFileName($namespace->getName(), current($classes)->getName()); + $filename = $this->rootDir . $this->getFileName($namespace->getName(), current($classes)->getName()); $dirname = dirname($filename); if (! is_dir($dirname)) { diff --git a/generator/src/Command/GenerateCommand.php b/generator/src/Command/GenerateCommand.php index faa4a13d7..f690a7c00 100644 --- a/generator/src/Command/GenerateCommand.php +++ b/generator/src/Command/GenerateCommand.php @@ -3,7 +3,6 @@ namespace MongoDB\CodeGenerator\Command; -use MongoDB\Builder\Expression\ExpressionInterface; use MongoDB\CodeGenerator\Definition\ExpressionDefinition; use MongoDB\CodeGenerator\Definition\GeneratorDefinition; use MongoDB\CodeGenerator\ExpressionClassGenerator; @@ -69,10 +68,10 @@ private function generateExpressionClasses(OutputInterface $output): array return $definitions; } - /** @param array, ExpressionDefinition> $expressions */ + /** @param array $expressions */ private function generateOperatorClasses(array $expressions, OutputInterface $output): void { - $config = require $this->configDir . '/operators.php'; + $config = require $this->configDir . '/definitions.php'; assert(is_array($config)); foreach ($config as $def) { @@ -80,7 +79,7 @@ private function generateOperatorClasses(array $expressions, OutputInterface $ou $definition = new GeneratorDefinition(...$def); foreach ($definition->generators as $generatorClass) { - $output->writeln(sprintf('Generating classes for %s with %s', basename($definition->configFile), $generatorClass)); + $output->writeln(sprintf('Generating classes for %s with %s', basename($definition->configFiles), $generatorClass)); assert(is_a($generatorClass, OperatorGenerator::class, true)); $generator = new $generatorClass($this->rootDir, $expressions); $generator->generate($definition); diff --git a/generator/src/Definition/ArgumentDefinition.php b/generator/src/Definition/ArgumentDefinition.php index bfb5eeef4..9408a4e05 100644 --- a/generator/src/Definition/ArgumentDefinition.php +++ b/generator/src/Definition/ArgumentDefinition.php @@ -12,14 +12,16 @@ final readonly class ArgumentDefinition { + public ?VariadicType $variadic; public ?int $variadicMin; public function __construct( public string $name, - /** @psalm-assert string|list $type */ - public string|array $type, - public bool $isOptional = false, - public bool $isVariadic = false, + /** @psalm-assert list $type */ + public array $type, + public ?string $description = null, + public bool $optional = false, + ?string $variadic = null, ?int $variadicMin = null, ) { if (is_array($type)) { @@ -29,13 +31,16 @@ public function __construct( } } - if (! $isVariadic) { - assert($variadicMin === null); - $this->variadicMin = null; - } elseif ($variadicMin === null) { - $this->variadicMin = $isOptional ? 0 : 1; + if ($variadic) { + $this->variadic = VariadicType::from($variadic); + if ($variadicMin === null) { + $this->variadicMin = $optional ? 0 : 1; + } else { + $this->variadicMin = $variadicMin; + } } else { - $this->variadicMin = $variadicMin; + $this->variadic = null; + $this->variadicMin = null; } } } diff --git a/generator/src/Definition/ExpressionDefinition.php b/generator/src/Definition/ExpressionDefinition.php index f5be42116..8f8e28f72 100644 --- a/generator/src/Definition/ExpressionDefinition.php +++ b/generator/src/Definition/ExpressionDefinition.php @@ -4,19 +4,41 @@ namespace MongoDB\CodeGenerator\Definition; use function assert; +use function interface_exists; +use function is_string; +use function ucfirst; final readonly class ExpressionDefinition { + /** @var list */ + public array $acceptedTypes; + + /** @var string|null Interface to implement for operators that resolve to this type. Generated class/enum/interface. */ + public ?string $returnType; + public function __construct( public string $name, - /** @var list */ - public array $types, - public bool $scalar = false, - public bool $class = false, + array $acceptedTypes, + ?string $returnType = null, public ?string $extends = null, /** @var list */ public array $implements = [], + public array $values = [], + public ?PhpObject $generate = null, ) { - assert($class || ! $extends, 'Cannot specify "extends" when "class" is not true'); + assert($generate === PhpObject::PhpClass || ! $extends, $name . ': Cannot specify "extends" when "generate" is not "class"'); + assert($generate === PhpObject::PhpEnum || ! $this->values, $name . ': Cannot specify "values" when "generate" is not "enum"'); + assert($returnType === null || interface_exists($returnType), $name . ': Return type must be an interface'); + + foreach ($acceptedTypes as $acceptedType) { + assert(is_string($acceptedType), $name . ': AcceptedTypes must be an array of strings.'); + } + + if ($generate) { + $returnType = 'MongoDB\\Builder\\Expression\\' . ucfirst($this->name); + } + + $this->returnType = $returnType; + $this->acceptedTypes = $acceptedTypes; } } diff --git a/generator/src/Definition/GeneratorDefinition.php b/generator/src/Definition/GeneratorDefinition.php index 936136f47..f0a09b7bf 100644 --- a/generator/src/Definition/GeneratorDefinition.php +++ b/generator/src/Definition/GeneratorDefinition.php @@ -17,7 +17,7 @@ final readonly class GeneratorDefinition { public function __construct( - public string $configFile, + public string $configFiles, /** @psalm-assert list> */ public array $generators, public string $namespace, diff --git a/generator/src/Definition/OperatorDefinition.php b/generator/src/Definition/OperatorDefinition.php index 3c8b5ae2c..a297d40ea 100644 --- a/generator/src/Definition/OperatorDefinition.php +++ b/generator/src/Definition/OperatorDefinition.php @@ -3,29 +3,54 @@ namespace MongoDB\CodeGenerator\Definition; -use function array_map; +use MongoDB\Builder\Type\Encode; +use UnexpectedValueException; + +use function array_merge; use function assert; use function count; -use function in_array; use function sprintf; final readonly class OperatorDefinition { + public Encode $encode; /** @var list */ public array $arguments; public function __construct( public string $name, - public ?string $encode = null, - public ?string $type = null, - array $args = [], + public string $link, + string $encode, + public array $type, + public ?string $description = null, + array $arguments = [], ) { - assert($encode || count($args) === 1, sprintf('Operator "%s" has %d arguments. The "encode" parameter must be specified.', $name, count($args))); - assert(in_array($encode, [null, 'array', 'object'], true), sprintf('Operator "%s" expect "encode" value to be "array" or "object". Got "%s".', $name, $encode)); + $this->encode = match ($encode) { + 'single' => Encode::Single, + 'array' => Encode::Array, + 'object' => Encode::Object, + 'group' => Encode::Group, + default => throw new UnexpectedValueException(sprintf('Unexpected "encode" value for operator "%s". Got "%s"', $name, $encode)), + }; + + // Convert arguments to ArgumentDefinition objects + // Optional arguments must be after required arguments + $requiredArgs = $optionalArgs = []; + foreach ($arguments as $arg) { + $arg = new ArgumentDefinition(...$arg); + if ($arg->optional) { + $optionalArgs[] = $arg; + } else { + $requiredArgs[] = $arg; + } + } + + // "single" encode operators must have one required argument + if ($this->encode === Encode::Single) { + assert(count($requiredArgs) === 1, sprintf('Single encode operator "%s" must have one argument', $name)); + assert(count($optionalArgs) === 0, sprintf('Single encode operator "%s" argument cannot be optional', $name)); + } - $this->arguments = array_map( - fn ($arg): ArgumentDefinition => new ArgumentDefinition(...$arg), - $args, - ); + $this->arguments = array_merge($requiredArgs, $optionalArgs); } } diff --git a/generator/src/Definition/PhpObject.php b/generator/src/Definition/PhpObject.php new file mode 100644 index 000000000..7b5af75a2 --- /dev/null +++ b/generator/src/Definition/PhpObject.php @@ -0,0 +1,13 @@ +> */ - private static array $definitions = []; - /** @return list */ - public function read(string $filename): array + public function read(string $dirname): array { - if (array_key_exists($filename, self::$definitions)) { - return self::$definitions[$filename]; - } - - $config = Yaml::parseFile($filename); - assert(is_array($config)); + $finder = new Finder(); + $finder->files()->in($dirname)->name('*.yaml')->sortByName(); $definitions = []; - foreach ($config as $operator) { + foreach ($finder as $file) { + $operator = Yaml::parseFile($file->getPathname()); assert(is_array($operator)); $definitions[] = new OperatorDefinition(...$operator); } - return self::$definitions[$filename] = $definitions; + return $definitions; } } diff --git a/generator/src/ExpressionClassGenerator.php b/generator/src/ExpressionClassGenerator.php index cd988bc3f..d9fb41653 100644 --- a/generator/src/ExpressionClassGenerator.php +++ b/generator/src/ExpressionClassGenerator.php @@ -3,11 +3,17 @@ namespace MongoDB\CodeGenerator; +use LogicException; use MongoDB\CodeGenerator\Definition\ExpressionDefinition; +use MongoDB\CodeGenerator\Definition\PhpObject; use Nette\PhpGenerator\PhpNamespace; use Nette\PhpGenerator\Type; +use RuntimeException; +use Throwable; use function array_map; +use function ucfirst; +use function var_export; /** * Generates a value object class for expressions @@ -16,16 +22,20 @@ class ExpressionClassGenerator extends AbstractGenerator { public function generate(ExpressionDefinition $definition): void { - if ($definition->scalar) { + if (! $definition->generate) { return; } - $this->writeFile($this->createClassOrInterface($definition)); + try { + $this->writeFile($this->createClassOrInterface($definition)); + } catch (Throwable $e) { + throw new RuntimeException('Failed to generate expression class for ' . $definition->name, 0, $e); + } } public function createClassOrInterface(ExpressionDefinition $definition): PhpNamespace { - [$namespace, $className] = $this->splitNamespaceAndClassName($definition->name); + [$namespace, $className] = $this->splitNamespaceAndClassName($definition->returnType); $namespace = new PhpNamespace($namespace); foreach ($definition->implements as $interface) { $namespace->addUse($interface); @@ -36,26 +46,36 @@ public function createClassOrInterface(ExpressionDefinition $definition): PhpNam 'list' => 'array', default => $type, }, - $definition->types, + $definition->acceptedTypes, ); - if ($definition->class) { + if ($definition->generate === PhpObject::PhpClass) { $class = $namespace->addClass($className); + $class->setReadOnly(); $class->setImplements($definition->implements); $class->setExtends($definition->extends); // Replace with promoted property in PHP 8.1 $propertyType = Type::union(...$types); - $class->addProperty('expression') + $class->addProperty('name') ->setType($propertyType) ->setPublic(); $constructor = $class->addMethod('__construct'); - $constructor->addParameter('expression')->setType($propertyType); - $constructor->addBody('$this->expression = $expression;'); + $constructor->addParameter('name')->setType($propertyType); + $constructor->addBody('$this->name = $name;'); + } elseif ($definition->generate === PhpObject::PhpInterface) { + $interface = $namespace->addInterface($className); + $interface->setExtends($definition->implements); + } elseif ($definition->generate === PhpObject::PhpEnum) { + $enum = $namespace->addEnum($className); + $enum->setType('string'); + array_map( + fn (string $case) => $enum->addCase(ucfirst($case), $case), + $definition->values, + ); } else { - $class = $namespace->addInterface($className); - $class->setExtends($definition->implements); + throw new LogicException('Unknown generate type: ' . var_export($definition->generate, true)); } return $namespace; diff --git a/generator/src/ExpressionFactoryGenerator.php b/generator/src/ExpressionFactoryGenerator.php index e208f424f..1bad8d6e2 100644 --- a/generator/src/ExpressionFactoryGenerator.php +++ b/generator/src/ExpressionFactoryGenerator.php @@ -4,6 +4,7 @@ namespace MongoDB\CodeGenerator; use MongoDB\CodeGenerator\Definition\ExpressionDefinition; +use MongoDB\CodeGenerator\Definition\PhpObject; use Nette\PhpGenerator\PhpNamespace; use function lcfirst; @@ -20,32 +21,28 @@ public function generate(array $expressions): void /** @param array $expressions */ private function createFactoryClass(array $expressions): PhpNamespace { - $namespace = new PhpNamespace('MongoDB\\Builder'); - $class = $namespace->addClass('Expression'); - $class->setFinal(); + $namespace = new PhpNamespace('MongoDB\\Builder\\Expression'); + $trait = $namespace->addTrait('ExpressionFactoryTrait'); + $trait->addComment('@internal'); // Pedantry requires methods to be ordered alphabetically usort($expressions, fn (ExpressionDefinition $a, ExpressionDefinition $b) => $a->name <=> $b->name); foreach ($expressions as $expression) { - if (! $expression->class) { + if ($expression->generate !== PhpObject::PhpClass) { continue; } - $namespace->addUse($expression->name); - $expressionShortClassName = $this->splitNamespaceAndClassName($expression->name)[1]; + $namespace->addUse($expression->returnType); + $expressionShortClassName = $this->splitNamespaceAndClassName($expression->returnType)[1]; - $method = $class->addMethod(lcfirst($expressionShortClassName)); + $method = $trait->addMethod(lcfirst($expressionShortClassName)); $method->setStatic(); - $method->addParameter('expression')->setType('string'); - $method->addBody('return new ' . $expressionShortClassName . '($expression);'); - $method->setReturnType($expression->name); + $method->addParameter('name')->setType('string'); + $method->addBody('return new ' . $expressionShortClassName . '($name);'); + $method->setReturnType($expression->returnType); } - // Pedantry requires private methods to be at the end - $class->addMethod('__construct')->setPrivate() - ->setComment('This class cannot be instantiated.'); - return $namespace; } } diff --git a/generator/src/OperatorClassGenerator.php b/generator/src/OperatorClassGenerator.php index 2c65d4075..e64ea4ada 100644 --- a/generator/src/OperatorClassGenerator.php +++ b/generator/src/OperatorClassGenerator.php @@ -3,14 +3,21 @@ namespace MongoDB\CodeGenerator; -use MongoDB\Builder\Stage\StageInterface; +use MongoDB\Builder\Type\Encode; +use MongoDB\Builder\Type\QueryObject; use MongoDB\CodeGenerator\Definition\GeneratorDefinition; use MongoDB\CodeGenerator\Definition\OperatorDefinition; +use MongoDB\CodeGenerator\Definition\VariadicType; +use MongoDB\Exception\InvalidArgumentException; use Nette\PhpGenerator\Literal; use Nette\PhpGenerator\PhpNamespace; +use RuntimeException; +use stdClass; +use Throwable; use function assert; use function interface_exists; +use function rtrim; use function sprintf; /** @@ -21,7 +28,11 @@ class OperatorClassGenerator extends OperatorGenerator public function generate(GeneratorDefinition $definition): void { foreach ($this->getOperators($definition) as $operator) { - $this->writeFile($this->createClass($definition, $operator)); + try { + $this->writeFile($this->createClass($definition, $operator)); + } catch (Throwable $e) { + throw new RuntimeException(sprintf('Failed to generate class for operator "%s"', $operator->name), 0, $e); + } } } @@ -35,59 +46,103 @@ public function createClass(GeneratorDefinition $definition, OperatorDefinition } $class = $namespace->addClass($this->getOperatorClassName($definition, $operator)); + $class->setReadOnly(); $class->setImplements($interfaces); // Expose operator metadata as constants // @todo move to encoder class - $class->addConstant('NAME', '$' . $operator->name); - $class->addConstant('ENCODE', $operator->encode ?? 'single'); + $class->addComment($operator->description); + $class->addComment('@see ' . $operator->link); + $class->addConstant('NAME', $operator->name); + $namespace->addUse(Encode::class); + $class->addConstant('ENCODE', new Literal('Encode::' . $operator->encode->name)); $constuctor = $class->addMethod('__construct'); foreach ($operator->arguments as $argument) { - $type = $this->generateExpressionTypes($argument); + $type = $this->getAcceptedTypes($argument); foreach ($type->use as $use) { $namespace->addUse($use); } - // Property - $propertyComment = ''; $property = $class->addProperty($argument->name); - if ($argument->isVariadic) { - $property->setType('array'); - $propertyComment .= '@param list<' . $type->doc . '> ...$' . $argument->name; - } else { - $property->setType($type->native); - } - - $property->setComment($propertyComment); - - // Constructor $constuctorParam = $constuctor->addParameter($argument->name); $constuctorParam->setType($type->native); - if ($argument->isVariadic) { + + if ($argument->variadic) { $constuctor->setVariadic(); + $constuctor->addComment('@param ' . $type->doc . ' ...$' . $argument->name . rtrim(' ' . $argument->description)); - if ($argument->variadicMin > 0) { + if ($argument->variadicMin !== null) { $constuctor->addBody(<<name}) < {$argument->variadicMin}) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', $argument->variadicMin, \count(\${$argument->name}))); + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for \${$argument->name}, got %d.', {$argument->variadicMin}, \count(\${$argument->name}))); } + PHP); + } + if ($argument->variadic === VariadicType::Array) { + $property->setType('array'); + $property->addComment('@param list<' . $type->doc . '> ...$' . $argument->name . rtrim(' ' . $argument->description)); + // Warn that named arguments are not supported + // @see https://psalm.dev/docs/running_psalm/issues/NamedArgumentNotAllowed/ + $constuctor->addComment('@no-named-arguments'); + $namespace->addUseFunction('array_is_list'); + $namespace->addUse(InvalidArgumentException::class); + $constuctor->addBody(<<name})) { + throw new InvalidArgumentException('Expected \${$argument->name} arguments to be a list (array), named arguments are not supported'); + } + PHP); + } elseif ($argument->variadic === VariadicType::Object) { + $namespace->addUse(stdClass::class); + $property->setType(stdClass::class); + $property->addComment('@param stdClass<' . $type->doc . '> ...$' . $argument->name . rtrim(' ' . $argument->description)); + $namespace->addUseFunction('is_string'); + $namespace->addUse(InvalidArgumentException::class); + $constuctor->addBody(<<name} as \$key => \$value) { + if (! is_string(\$key)) { + throw new InvalidArgumentException('Expected \${$argument->name} arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + \${$argument->name} = (object) \${$argument->name}; PHP); } - } elseif ($argument->isOptional) { - $constuctorParam->setDefaultValue(new Literal('Optional::Undefined')); - } + } else { + // Non-variadic arguments + $property->addComment('@param ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description)); + $property->setType($type->native); + $constuctor->addComment('@param ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description)); + + if ($argument->optional) { + // We use a special Optional::Undefined type to differentiate between null and undefined + $constuctorParam->setDefaultValue(new Literal('Optional::Undefined')); + } - $constuctor->addComment('@param ' . $type->doc . ' $' . $argument->name); + // List type must be validated with array_is_list() + if ($type->list) { + $namespace->addUseFunction('is_array'); + $namespace->addUseFunction('array_is_list'); + $namespace->addUse(InvalidArgumentException::class); + $constuctor->addBody(<<name}) && ! array_is_list(\${$argument->name})) { + throw new InvalidArgumentException('Expected \${$argument->name} argument to be a list, got an associative array.'); + } - // List type must be validated with array_is_list() - if ($type->list) { - $constuctor->addBody(<<name}) && ! \array_is_list(\${$argument->name})) { - throw new \InvalidArgumentException('Expected \${$argument->name} argument to be a list, got an associative array.'); + PHP); + } + + if ($type->query) { + $namespace->addUseFunction('is_array'); + $namespace->addUseFunction('is_object'); + $namespace->addUse(QueryObject::class); + $constuctor->addBody(<<name}) || is_object(\${$argument->name})) { + \${$argument->name} = QueryObject::create(\${$argument->name}); + } + + PHP); } - PHP); } // Set property from constructor argument @@ -102,17 +157,13 @@ public function createClass(GeneratorDefinition $definition, OperatorDefinition */ private function getInterfaces(OperatorDefinition $definition): array { - if ($definition->type === null) { - return []; - } + $interfaces = []; - if ($definition->type === 'stage') { - return ['\\' . StageInterface::class]; + foreach ($definition->type as $type) { + $interfaces[] = $interface = $this->getType($type)->returnType; + assert(interface_exists($interface), sprintf('"%s" is not an interface.', $interface)); } - $interface = $this->getExpressionTypeInterface($definition->type); - assert(interface_exists($interface), sprintf('"%s" is not an interface.', $interface)); - - return [$interface]; + return $interfaces; } } diff --git a/generator/src/OperatorFactoryGenerator.php b/generator/src/OperatorFactoryGenerator.php index b7e63594c..36cbd4011 100644 --- a/generator/src/OperatorFactoryGenerator.php +++ b/generator/src/OperatorFactoryGenerator.php @@ -7,69 +7,80 @@ use MongoDB\CodeGenerator\Definition\OperatorDefinition; use Nette\PhpGenerator\Literal; use Nette\PhpGenerator\PhpNamespace; +use Nette\PhpGenerator\TraitType; +use RuntimeException; +use Throwable; use function implode; use function ltrim; +use function rtrim; +use function sprintf; use function str_replace; +use function strcasecmp; use function usort; final class OperatorFactoryGenerator extends OperatorGenerator { public function generate(GeneratorDefinition $definition): void { - $this->writeFile($this->createFactoryClass($definition)); + $this->writeFile($this->createFactoryTrait($definition)); } - private function createFactoryClass(GeneratorDefinition $definition): PhpNamespace + private function createFactoryTrait(GeneratorDefinition $definition): PhpNamespace { - // Use the operators namespace as factory class name. - [$namespace, $className] = $this->splitNamespaceAndClassName($definition->namespace); - $namespace = new PhpNamespace($namespace); - $class = $namespace->addClass($className); - $class->setFinal(); + $namespace = new PhpNamespace($definition->namespace); + $trait = $namespace->addTrait('FactoryTrait'); + $trait->addComment('@internal'); // Pedantry requires methods to be ordered alphabetically $operators = $this->getOperators($definition); - usort($operators, fn (OperatorDefinition $a, OperatorDefinition $b) => $a->name <=> $b->name); + usort($operators, fn (OperatorDefinition $a, OperatorDefinition $b) => strcasecmp($a->name, $b->name)); foreach ($operators as $operator) { - $operatorClassName = '\\' . $definition->namespace . '\\' . $this->getOperatorClassName($definition, $operator); - $namespace->addUse($operatorClassName); + try { + $this->addMethod($definition, $operator, $namespace, $trait); + } catch (Throwable $e) { + throw new RuntimeException(sprintf('Failed to generate class for operator "%s"', $operator->name), 0, $e); + } + } - $method = $class->addMethod($operator->name); - $method->setStatic(); - $args = []; - foreach ($operator->arguments as $argument) { - $type = $this->generateExpressionTypes($argument); - foreach ($type->use as $use) { - $namespace->addUse($use); - } + return $namespace; + } + + private function addMethod(GeneratorDefinition $definition, OperatorDefinition $operator, PhpNamespace $namespace, TraitType $trait): void + { + $operatorClassName = '\\' . $definition->namespace . '\\' . $this->getOperatorClassName($definition, $operator); + $namespace->addUse($operatorClassName); - $parameter = $method->addParameter($argument->name); - $parameter->setType($type->native); - if ($argument->isVariadic) { - $method->setVariadic(); - $method->addComment('@param ' . $type->doc . ' ...$' . $argument->name); - $args[] = '...$' . $argument->name; - } else { - if ($argument->isOptional) { - $parameter->setDefaultValue(new Literal('Optional::Undefined')); - } + $method = $trait->addMethod(ltrim($operator->name, '$')); + $method->setStatic(); + $method->addComment($operator->description); + $method->addComment('@see ' . $operator->link); + $args = []; + foreach ($operator->arguments as $argument) { + $type = $this->getAcceptedTypes($argument); + foreach ($type->use as $use) { + $namespace->addUse($use); + } - $method->addComment('@param ' . $type->doc . ' $' . $argument->name); - $args[] = '$' . $argument->name; + $parameter = $method->addParameter($argument->name); + $parameter->setType($type->native); + if ($argument->variadic) { + $method->setVariadic(); + $method->addComment('@param ' . $type->doc . ' ...$' . $argument->name . rtrim(' ' . $argument->description)); + $args[] = '...$' . $argument->name; + } else { + if ($argument->optional) { + $parameter->setDefaultValue(new Literal('Optional::Undefined')); } - } - $operatorShortClassName = ltrim(str_replace($definition->namespace, '', $operatorClassName), '\\'); - $method->addBody('return new ' . $operatorShortClassName . '(' . implode(', ', $args) . ');'); - $method->setReturnType($operatorClassName); + $method->addComment('@param ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description)); + $args[] = '$' . $argument->name; + } } - // Pedantry requires private methods to be at the end - $class->addMethod('__construct')->setPrivate() - ->setComment('This class cannot be instantiated.'); - - return $namespace; + $operatorShortClassName = ltrim(str_replace($definition->namespace, '', $operatorClassName), '\\'); + $method->addBody('return new ' . $operatorShortClassName . '(' . implode(', ', $args) . ');'); + $method->setReturnType($operatorClassName); } } diff --git a/generator/src/OperatorGenerator.php b/generator/src/OperatorGenerator.php index b1571a313..e75456a2b 100644 --- a/generator/src/OperatorGenerator.php +++ b/generator/src/OperatorGenerator.php @@ -3,15 +3,18 @@ namespace MongoDB\CodeGenerator; -use MongoDB\Builder\Expression\ExpressionInterface; -use MongoDB\Builder\Optional; +use MongoDB\BSON\Document; +use MongoDB\BSON\PackedArray; +use MongoDB\Builder\Type\Optional; use MongoDB\CodeGenerator\Definition\ArgumentDefinition; use MongoDB\CodeGenerator\Definition\ExpressionDefinition; use MongoDB\CodeGenerator\Definition\GeneratorDefinition; use MongoDB\CodeGenerator\Definition\OperatorDefinition; use MongoDB\CodeGenerator\Definition\YamlReader; use Nette\PhpGenerator\Type; +use stdClass; +use function array_filter; use function array_key_exists; use function array_merge; use function array_unique; @@ -19,9 +22,11 @@ use function class_exists; use function in_array; use function interface_exists; +use function ltrim; use function sort; use function sprintf; use function ucfirst; +use function usort; abstract class OperatorGenerator extends AbstractGenerator { @@ -29,7 +34,7 @@ abstract class OperatorGenerator extends AbstractGenerator final public function __construct( string $rootDir, - /** @var array, ExpressionDefinition> */ + /** @var array */ private array $expressions ) { parent::__construct($rootDir); @@ -39,71 +44,55 @@ final public function __construct( abstract public function generate(GeneratorDefinition $definition): void; - /** @return list */ final protected function getOperators(GeneratorDefinition $definition): array { - return $this->yamlReader->read($definition->configFile); + // Remove unsupported operators + return array_filter( + $this->yamlReader->read($definition->configFiles), + fn (OperatorDefinition $operator): bool => ! in_array($operator->name, ['$'], true), + ); } final protected function getOperatorClassName(GeneratorDefinition $definition, OperatorDefinition $operator): string { - return ucfirst($operator->name) . $definition->classNameSuffix; + return ucfirst(ltrim($operator->name, '$')) . $definition->classNameSuffix; } - /** @return class-string|string */ - final protected function getExpressionTypeInterface(string $type): string + final protected function getType(string $type): ExpressionDefinition { - if ('expression' === $type) { - return ExpressionInterface::class; - } - - // Scalar types - if (array_key_exists($type, $this->expressions)) { - return $type; - } + assert(array_key_exists($type, $this->expressions), sprintf('Invalid expression type "%s".', $type)); - $interface = 'MongoDB\\Builder\\Expression\\' . ucfirst($type); - assert(array_key_exists($interface, $this->expressions), sprintf('Invalid expression type "%s".', $type)); - - return $interface; + return $this->expressions[$type]; } /** * Expression types can contain class names, interface, native types or "list". * PHPDoc types are more precise than native types, so we use them systematically even if redundant. * - * @return object{native:string,doc:string,use:list,list:bool} + * @return object{native:string,doc:string,use:list,list:bool,query:bool} */ - final protected function generateExpressionTypes(ArgumentDefinition $arg): object + final protected function getAcceptedTypes(ArgumentDefinition $arg): stdClass { $nativeTypes = []; - foreach ((array) $arg->type as $type) { - $interface = $this->getExpressionTypeInterface($type); - $types = $this->expressions[$interface]->types; - // Add the interface to the allowed types if it is not a scalar - if (! $this->expressions[$interface]->scalar) { - $types = array_merge([$interface], $types); + foreach ($arg->type as $type) { + $type = $this->getType($type); + $nativeTypes = array_merge($nativeTypes, $type->acceptedTypes); + + if (isset($type->returnType)) { + $nativeTypes[] = $type->returnType; } + } - $nativeTypes = array_merge($nativeTypes, $types); + if ($arg->optional) { + $use[] = '\\' . Optional::class; + $nativeTypes[] = Optional::class; } $docTypes = $nativeTypes = array_unique($nativeTypes); - $listCheck = false; $use = []; foreach ($nativeTypes as $key => $typeName) { - // "list" is a special type of array that needs to be checked in the code - if ($typeName === 'list') { - $listCheck = true; - $nativeTypes[$key] = 'array'; - // @todo allow to specify the type of the elements in the list - $docTypes[$key] = 'list'; - $use[] = '\\' . ExpressionInterface::class; - continue; - } - // strings cannot be empty if ($typeName === 'string') { $docTypes[$key] = 'non-empty-string'; @@ -119,19 +108,20 @@ final protected function generateExpressionTypes(ArgumentDefinition $arg): objec } } - if ($arg->isOptional) { - $use[] = '\\' . Optional::class; - $docTypes[] = 'Optional'; - $nativeTypes[] = Optional::class; - } + // If an array is expected, but not an object, we can check for a list + $listCheck = in_array('\\' . PackedArray::class, $nativeTypes, true) + && ! in_array('\\' . Document::class, $nativeTypes, true); + + // If the argument is a query, we need to convert it to a QueryObject + $isQuery = in_array('query', $arg->type, true); // mixed can only be used as a standalone type if (in_array('mixed', $nativeTypes, true)) { $nativeTypes = ['mixed']; } - sort($nativeTypes); - sort($docTypes); + usort($nativeTypes, self::sortTypesCallback(...)); + usort($docTypes, self::sortTypesCallback(...)); sort($use); return (object) [ @@ -139,6 +129,25 @@ final protected function generateExpressionTypes(ArgumentDefinition $arg): objec 'doc' => Type::union(...array_unique($docTypes)), 'use' => array_unique($use), 'list' => $listCheck, + 'query' => $isQuery, ]; } + + /** + * usort() callback for sorting types. + * "Optional" is always first, for documentation of optional parameters, + * then types are sorted alphabetically. + */ + private static function sortTypesCallback(string $type1, string $type2): int + { + if ($type1 === 'Optional' || $type1 === '\\' . Optional::class) { + return -1; + } + + if ($type2 === 'Optional' || $type2 === '\\' . Optional::class) { + return 1; + } + + return $type1 <=> $type2; + } } diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 949748155..0cbdbe2aa 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -20,8 +20,7 @@ rector.php - src/Builder/(Aggregation|Expression|Query|Stage)\.php - src/Builder/(Aggregation|Expression|Query|Stage)/*\.php + src/Builder/(Accumulator|Expression|Query|Projection|Stage)/*\.php diff --git a/psalm-baseline.xml b/psalm-baseline.xml index a06fddc08..309a48158 100644 --- a/psalm-baseline.xml +++ b/psalm-baseline.xml @@ -1,5 +1,5 @@ - + decrypt($document->encryptedField)]]> @@ -46,6 +46,33 @@ stdClass + + + $array + $document + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + $expression + + EncodeIfSupported @@ -57,24 +84,64 @@ $encoded[] - $expr - $expression - $field - $key - $key - $query + $result $result $result[] $val $val + $val + $val + $val + $value[$key] + + + $expression + $expression + $expression + $value + + + + + $field + + + + + $expression + + + + + $facet + + + + + $field + + + + + $specification + + + + + $field + + self::CURSOR_NOT_FOUND + + __toString + @@ -88,6 +155,9 @@ + + __toString + $options @@ -104,6 +174,11 @@ + + + __toString + + @@ -210,6 +285,9 @@ + + __toString + $key diff --git a/psalm.xml.dist b/psalm.xml.dist index 380d4e853..1803c00f4 100644 --- a/psalm.xml.dist +++ b/psalm.xml.dist @@ -1,6 +1,6 @@ init = $init; + $this->accumulate = $accumulate; + if (is_array($accumulateArgs) && ! array_is_list($accumulateArgs)) { + throw new InvalidArgumentException('Expected $accumulateArgs argument to be a list, got an associative array.'); + } + + $this->accumulateArgs = $accumulateArgs; + $this->merge = $merge; + $this->lang = $lang; + if (is_array($initArgs) && ! array_is_list($initArgs)) { + throw new InvalidArgumentException('Expected $initArgs argument to be a list, got an associative array.'); + } + + $this->initArgs = $initArgs; + $this->finalize = $finalize; + } +} diff --git a/src/Builder/Accumulator/AddToSetAccumulator.php b/src/Builder/Accumulator/AddToSetAccumulator.php new file mode 100644 index 000000000..4f91a8689 --- /dev/null +++ b/src/Builder/Accumulator/AddToSetAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/AvgAccumulator.php b/src/Builder/Accumulator/AvgAccumulator.php new file mode 100644 index 000000000..7ea9aa61c --- /dev/null +++ b/src/Builder/Accumulator/AvgAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/BottomAccumulator.php b/src/Builder/Accumulator/BottomAccumulator.php new file mode 100644 index 000000000..11b6b1814 --- /dev/null +++ b/src/Builder/Accumulator/BottomAccumulator.php @@ -0,0 +1,46 @@ +sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Accumulator/BottomNAccumulator.php b/src/Builder/Accumulator/BottomNAccumulator.php new file mode 100644 index 000000000..57bf8d1f8 --- /dev/null +++ b/src/Builder/Accumulator/BottomNAccumulator.php @@ -0,0 +1,54 @@ +n = $n; + $this->sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Accumulator/CountAccumulator.php b/src/Builder/Accumulator/CountAccumulator.php new file mode 100644 index 000000000..05882ed5e --- /dev/null +++ b/src/Builder/Accumulator/CountAccumulator.php @@ -0,0 +1,28 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Accumulator/CovarianceSampAccumulator.php b/src/Builder/Accumulator/CovarianceSampAccumulator.php new file mode 100644 index 000000000..548bc9ce7 --- /dev/null +++ b/src/Builder/Accumulator/CovarianceSampAccumulator.php @@ -0,0 +1,43 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Accumulator/DenseRankAccumulator.php b/src/Builder/Accumulator/DenseRankAccumulator.php new file mode 100644 index 000000000..3a8e4b870 --- /dev/null +++ b/src/Builder/Accumulator/DenseRankAccumulator.php @@ -0,0 +1,26 @@ +input = $input; + $this->unit = $unit; + } +} diff --git a/src/Builder/Accumulator/DocumentNumberAccumulator.php b/src/Builder/Accumulator/DocumentNumberAccumulator.php new file mode 100644 index 000000000..e965184aa --- /dev/null +++ b/src/Builder/Accumulator/DocumentNumberAccumulator.php @@ -0,0 +1,26 @@ +input = $input; + $this->N = $N; + $this->alpha = $alpha; + } +} diff --git a/src/Builder/Accumulator/FactoryTrait.php b/src/Builder/Accumulator/FactoryTrait.php new file mode 100644 index 000000000..624389e57 --- /dev/null +++ b/src/Builder/Accumulator/FactoryTrait.php @@ -0,0 +1,510 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/FirstNAccumulator.php b/src/Builder/Accumulator/FirstNAccumulator.php new file mode 100644 index 000000000..bd0d213b6 --- /dev/null +++ b/src/Builder/Accumulator/FirstNAccumulator.php @@ -0,0 +1,50 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Accumulator/LastAccumulator.php b/src/Builder/Accumulator/LastAccumulator.php new file mode 100644 index 000000000..5126c3b64 --- /dev/null +++ b/src/Builder/Accumulator/LastAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/LastNAccumulator.php b/src/Builder/Accumulator/LastNAccumulator.php new file mode 100644 index 000000000..9b27886e2 --- /dev/null +++ b/src/Builder/Accumulator/LastNAccumulator.php @@ -0,0 +1,49 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Accumulator/MaxAccumulator.php b/src/Builder/Accumulator/MaxAccumulator.php new file mode 100644 index 000000000..9f6bb56e6 --- /dev/null +++ b/src/Builder/Accumulator/MaxAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/MaxNAccumulator.php b/src/Builder/Accumulator/MaxNAccumulator.php new file mode 100644 index 000000000..1ff9b6050 --- /dev/null +++ b/src/Builder/Accumulator/MaxNAccumulator.php @@ -0,0 +1,50 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Accumulator/MedianAccumulator.php b/src/Builder/Accumulator/MedianAccumulator.php new file mode 100644 index 000000000..13594239a --- /dev/null +++ b/src/Builder/Accumulator/MedianAccumulator.php @@ -0,0 +1,46 @@ +input = $input; + $this->method = $method; + } +} diff --git a/src/Builder/Accumulator/MergeObjectsAccumulator.php b/src/Builder/Accumulator/MergeObjectsAccumulator.php new file mode 100644 index 000000000..644e06736 --- /dev/null +++ b/src/Builder/Accumulator/MergeObjectsAccumulator.php @@ -0,0 +1,46 @@ + ...$document Any valid expression that resolves to a document. */ + public array $document; + + /** + * @param Document|ResolvesToObject|Serializable|array|stdClass ...$document Any valid expression that resolves to a document. + * @no-named-arguments + */ + public function __construct(Document|Serializable|ResolvesToObject|stdClass|array ...$document) + { + if (\count($document) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $document, got %d.', 1, \count($document))); + } + if (! array_is_list($document)) { + throw new InvalidArgumentException('Expected $document arguments to be a list (array), named arguments are not supported'); + } + $this->document = $document; + } +} diff --git a/src/Builder/Accumulator/MinAccumulator.php b/src/Builder/Accumulator/MinAccumulator.php new file mode 100644 index 000000000..897bc6db9 --- /dev/null +++ b/src/Builder/Accumulator/MinAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/MinNAccumulator.php b/src/Builder/Accumulator/MinNAccumulator.php new file mode 100644 index 000000000..2cfca9973 --- /dev/null +++ b/src/Builder/Accumulator/MinNAccumulator.php @@ -0,0 +1,50 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Accumulator/PercentileAccumulator.php b/src/Builder/Accumulator/PercentileAccumulator.php new file mode 100644 index 000000000..b0ce299dc --- /dev/null +++ b/src/Builder/Accumulator/PercentileAccumulator.php @@ -0,0 +1,72 @@ +input = $input; + if (is_array($p) && ! array_is_list($p)) { + throw new InvalidArgumentException('Expected $p argument to be a list, got an associative array.'); + } + + $this->p = $p; + $this->method = $method; + } +} diff --git a/src/Builder/Accumulator/PushAccumulator.php b/src/Builder/Accumulator/PushAccumulator.php new file mode 100644 index 000000000..efc2811c3 --- /dev/null +++ b/src/Builder/Accumulator/PushAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/ShiftAccumulator.php b/src/Builder/Accumulator/ShiftAccumulator.php new file mode 100644 index 000000000..5c8a6ba4e --- /dev/null +++ b/src/Builder/Accumulator/ShiftAccumulator.php @@ -0,0 +1,65 @@ +output = $output; + $this->by = $by; + $this->default = $default; + } +} diff --git a/src/Builder/Accumulator/StdDevPopAccumulator.php b/src/Builder/Accumulator/StdDevPopAccumulator.php new file mode 100644 index 000000000..be80f63c5 --- /dev/null +++ b/src/Builder/Accumulator/StdDevPopAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/StdDevSampAccumulator.php b/src/Builder/Accumulator/StdDevSampAccumulator.php new file mode 100644 index 000000000..94f113100 --- /dev/null +++ b/src/Builder/Accumulator/StdDevSampAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/SumAccumulator.php b/src/Builder/Accumulator/SumAccumulator.php new file mode 100644 index 000000000..3dab7231f --- /dev/null +++ b/src/Builder/Accumulator/SumAccumulator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Accumulator/TopAccumulator.php b/src/Builder/Accumulator/TopAccumulator.php new file mode 100644 index 000000000..68df722e2 --- /dev/null +++ b/src/Builder/Accumulator/TopAccumulator.php @@ -0,0 +1,47 @@ +sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Accumulator/TopNAccumulator.php b/src/Builder/Accumulator/TopNAccumulator.php new file mode 100644 index 000000000..97ab95c13 --- /dev/null +++ b/src/Builder/Accumulator/TopNAccumulator.php @@ -0,0 +1,54 @@ +n = $n; + $this->sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Aggregation.php b/src/Builder/Aggregation.php deleted file mode 100644 index cb7393e0b..000000000 --- a/src/Builder/Aggregation.php +++ /dev/null @@ -1,149 +0,0 @@ - $input - * @param ResolvesToBool|bool $cond - * @param Optional|ResolvesToString|non-empty-string $as - * @param Int64|Optional|ResolvesToInt|int $limit - */ - public static function filter( - PackedArray|ResolvesToArray|BSONArray|array $input, - ResolvesToBool|bool $cond, - Optional|ResolvesToString|string $as = Optional::Undefined, - Optional|Int64|ResolvesToInt|int $limit = Optional::Undefined, - ): FilterAggregation - { - return new FilterAggregation($input, $cond, $as, $limit); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function gt(mixed $expression1, mixed $expression2): GtAggregation - { - return new GtAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function gte(mixed $expression1, mixed $expression2): GteAggregation - { - return new GteAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function lt(mixed $expression1, mixed $expression2): LtAggregation - { - return new LtAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression - */ - public static function max(mixed $expression): MaxAggregation - { - return new MaxAggregation($expression); - } - - /** - * @param ExpressionInterface|mixed $expression - */ - public static function min(mixed $expression): MinAggregation - { - return new MinAggregation($expression); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function mod(mixed $expression1, mixed $expression2): ModAggregation - { - return new ModAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function ne(mixed $expression1, mixed $expression2): NeAggregation - { - return new NeAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression1 - * @param ExpressionInterface|mixed $expression2 - */ - public static function subtract(mixed $expression1, mixed $expression2): SubtractAggregation - { - return new SubtractAggregation($expression1, $expression2); - } - - /** - * @param ExpressionInterface|mixed $expression - */ - public static function sum(mixed $expression): SumAggregation - { - return new SumAggregation($expression); - } - - /** - * This class cannot be instantiated. - */ - private function __construct() - { - } -} diff --git a/src/Builder/Aggregation/AndAggregation.php b/src/Builder/Aggregation/AndAggregation.php deleted file mode 100644 index 54ca6c46c..000000000 --- a/src/Builder/Aggregation/AndAggregation.php +++ /dev/null @@ -1,31 +0,0 @@ - ...$expressions */ - public array $expressions; - - /** - * @param ExpressionInterface|mixed $expressions - */ - public function __construct(mixed ...$expressions) - { - if (\count($expressions) < 1) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', 1, \count($expressions))); - } - - $this->expressions = $expressions; - } -} diff --git a/src/Builder/Aggregation/EqAggregation.php b/src/Builder/Aggregation/EqAggregation.php deleted file mode 100644 index f70757755..000000000 --- a/src/Builder/Aggregation/EqAggregation.php +++ /dev/null @@ -1,29 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/FilterAggregation.php b/src/Builder/Aggregation/FilterAggregation.php deleted file mode 100644 index d0d0b12d6..000000000 --- a/src/Builder/Aggregation/FilterAggregation.php +++ /dev/null @@ -1,49 +0,0 @@ - $input - * @param ResolvesToBool|bool $cond - * @param Optional|ResolvesToString|non-empty-string $as - * @param Int64|Optional|ResolvesToInt|int $limit - */ - public function __construct( - PackedArray|ResolvesToArray|BSONArray|array $input, - ResolvesToBool|bool $cond, - Optional|ResolvesToString|string $as = Optional::Undefined, - Optional|Int64|ResolvesToInt|int $limit = Optional::Undefined, - ) { - if (\is_array($input) && ! \array_is_list($input)) { - throw new \InvalidArgumentException('Expected $input argument to be a list, got an associative array.'); - } - $this->input = $input; - $this->cond = $cond; - $this->as = $as; - $this->limit = $limit; - } -} diff --git a/src/Builder/Aggregation/GtAggregation.php b/src/Builder/Aggregation/GtAggregation.php deleted file mode 100644 index af8b16a00..000000000 --- a/src/Builder/Aggregation/GtAggregation.php +++ /dev/null @@ -1,29 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/GteAggregation.php b/src/Builder/Aggregation/GteAggregation.php deleted file mode 100644 index b8933db72..000000000 --- a/src/Builder/Aggregation/GteAggregation.php +++ /dev/null @@ -1,29 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/LtAggregation.php b/src/Builder/Aggregation/LtAggregation.php deleted file mode 100644 index a135ed169..000000000 --- a/src/Builder/Aggregation/LtAggregation.php +++ /dev/null @@ -1,29 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/MaxAggregation.php b/src/Builder/Aggregation/MaxAggregation.php deleted file mode 100644 index 97f0d66bd..000000000 --- a/src/Builder/Aggregation/MaxAggregation.php +++ /dev/null @@ -1,25 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Aggregation/MinAggregation.php b/src/Builder/Aggregation/MinAggregation.php deleted file mode 100644 index 43db134af..000000000 --- a/src/Builder/Aggregation/MinAggregation.php +++ /dev/null @@ -1,25 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Aggregation/ModAggregation.php b/src/Builder/Aggregation/ModAggregation.php deleted file mode 100644 index 082532895..000000000 --- a/src/Builder/Aggregation/ModAggregation.php +++ /dev/null @@ -1,28 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/NeAggregation.php b/src/Builder/Aggregation/NeAggregation.php deleted file mode 100644 index c277e8134..000000000 --- a/src/Builder/Aggregation/NeAggregation.php +++ /dev/null @@ -1,29 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/SubtractAggregation.php b/src/Builder/Aggregation/SubtractAggregation.php deleted file mode 100644 index b3d2581ed..000000000 --- a/src/Builder/Aggregation/SubtractAggregation.php +++ /dev/null @@ -1,28 +0,0 @@ -expression1 = $expression1; - $this->expression2 = $expression2; - } -} diff --git a/src/Builder/Aggregation/SumAggregation.php b/src/Builder/Aggregation/SumAggregation.php deleted file mode 100644 index 2a4e232c1..000000000 --- a/src/Builder/Aggregation/SumAggregation.php +++ /dev/null @@ -1,26 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/BuilderEncoder.php b/src/Builder/BuilderEncoder.php index 61b618b04..d4c0e5de7 100644 --- a/src/Builder/BuilderEncoder.php +++ b/src/Builder/BuilderEncoder.php @@ -3,26 +3,37 @@ namespace MongoDB\Builder; use LogicException; -use MongoDB\Builder\Expression\ExpressionInterface; -use MongoDB\Builder\Expression\FieldPath; use MongoDB\Builder\Expression\Variable; -use MongoDB\Builder\Query\OrQuery; use MongoDB\Builder\Stage\GroupStage; -use MongoDB\Builder\Stage\ProjectStage; -use MongoDB\Builder\Stage\SortStage; -use MongoDB\Builder\Stage\StageInterface; +use MongoDB\Builder\Type\AccumulatorInterface; +use MongoDB\Builder\Type\CombinedFieldQuery; +use MongoDB\Builder\Type\Encode; +use MongoDB\Builder\Type\ExpressionInterface; +use MongoDB\Builder\Type\FieldPathInterface; +use MongoDB\Builder\Type\FieldQueryInterface; +use MongoDB\Builder\Type\Optional; +use MongoDB\Builder\Type\OutputWindow; +use MongoDB\Builder\Type\ProjectionInterface; +use MongoDB\Builder\Type\QueryInterface; +use MongoDB\Builder\Type\QueryObject; +use MongoDB\Builder\Type\StageInterface; +use MongoDB\Builder\Type\WindowInterface; use MongoDB\Codec\EncodeIfSupported; use MongoDB\Codec\Encoder; use MongoDB\Exception\UnsupportedValueException; use stdClass; -use function array_is_list; -use function array_merge; +use function array_key_first; +use function assert; +use function get_debug_type; use function get_object_vars; use function is_array; +use function is_object; +use function MongoDB\is_first_key_operator; +use function property_exists; use function sprintf; -/** @template-implements Encoder */ +/** @template-implements Encoder */ class BuilderEncoder implements Encoder { use EncodeIfSupported; @@ -32,7 +43,14 @@ class BuilderEncoder implements Encoder */ public function canEncode($value): bool { - return $value instanceof Pipeline || $value instanceof StageInterface || $value instanceof ExpressionInterface; + return $value instanceof Pipeline + || $value instanceof StageInterface + || $value instanceof ExpressionInterface + || $value instanceof QueryInterface + || $value instanceof FieldQueryInterface + || $value instanceof AccumulatorInterface + || $value instanceof ProjectionInterface + || $value instanceof WindowInterface; } /** @@ -55,118 +73,210 @@ public function encode($value): stdClass|array|string } // This specific encoding code if temporary until we have a generic way to encode stages and operators - if ($value instanceof FieldPath) { - return '$' . $value->expression; + if ($value instanceof FieldPathInterface) { + return '$' . $value->name; } if ($value instanceof Variable) { - return '$$' . $value->expression; + return '$$' . $value->name; } - if ($value instanceof GroupStage) { - $result = new stdClass(); - $result->_id = $this->encodeIfSupported($value->_id); - // Specific: fields are encoded as a map of properties to their values at the top level as _id - foreach ($value->fields ?? [] as $key => $val) { - $result->{$key} = $this->encodeIfSupported($val); - } - - return $this->wrap($value, $result); + if ($value instanceof QueryObject) { + return $this->encodeQueryObject($value); } - if ($value instanceof ProjectStage) { - $result = new stdClass(); - // Specific: fields are encoded as a map of properties to their values at the top level as _id - foreach ($value->specifications as $key => $val) { - $result->{$key} = $this->encodeIfSupported($val); - } - - return $this->wrap($value, $result); + if ($value instanceof CombinedFieldQuery) { + return $this->encodeCombinedFilter($value); } - if ($value instanceof SortStage) { - return $this->wrap($value, (object) $value->sortSpecification); - } - - if ($value instanceof OrQuery) { - $result = []; - foreach ($value->query as $query) { - $encodedQuery = new stdClass(); - foreach ($query as $field => $expression) { - // Specific: $or queries are encoded as a list of expressions - // We need to merge query expressions into a single object - if (is_array($expression) && array_is_list($expression)) { - $mergedExpressions = []; - foreach ($expression as $expr) { - $mergedExpressions = array_merge($mergedExpressions, (array) $this->encodeIfSupported($expr)); - } - - $encodedQuery->{$field} = (object) $mergedExpressions; - } else { - $encodedQuery->{$field} = $this->encodeIfSupported($expression); - } - } - - $result[] = $encodedQuery; - } - - return $this->wrap($value, $result); + if ($value instanceof OutputWindow) { + return $this->encodeOutputWindow($value); } // The generic but incomplete encoding code switch ($value::ENCODE) { - case 'single': + case Encode::Single: return $this->encodeAsSingle($value); - case 'array': + case Encode::Array: return $this->encodeAsArray($value); - case 'object': + case Encode::Object: return $this->encodeAsObject($value); + + case Encode::Group: + assert($value instanceof GroupStage); + + return $this->encodeAsGroup($value); } throw new LogicException(sprintf('Class "%s" does not have a valid ENCODE constant.', $value::class)); } - private function encodeAsArray(ExpressionInterface|StageInterface $value): stdClass + /** + * Encode the value as an array of properties, in the order they are defined in the class. + */ + private function encodeAsArray(object $value): stdClass { $result = []; /** @var mixed $val */ foreach (get_object_vars($value) as $val) { - $result[] = $this->encodeIfSupported($val); + // Skip optional arguments. + // $slice operator has the optional argument in the middle of the array + if ($val === Optional::Undefined) { + continue; + } + + $result[] = $this->recursiveEncode($val); } return $this->wrap($value, $result); } - private function encodeAsObject(ExpressionInterface|StageInterface $value): stdClass + /** + * $group stage have a specific encoding because the _id argument is required and others are variadic + */ + private function encodeAsGroup(GroupStage $value): stdClass + { + $result = new stdClass(); + $result->_id = $this->recursiveEncode($value->_id); + + foreach (get_object_vars($value->field) as $key => $val) { + $result->{$key} = $this->recursiveEncode($val); + } + + return $this->wrap($value, $result); + } + + private function encodeAsObject(object $value): stdClass { $result = new stdClass(); - /** @var mixed $val */ foreach (get_object_vars($value) as $key => $val) { - /** @var mixed $val */ - $val = $this->encodeIfSupported($val); - if ($val !== Optional::Undefined) { - $result->{$key} = $val; + // Skip optional arguments. If they have a default value, it is resolved by the server. + if ($val === Optional::Undefined) { + continue; } + + $result->{$key} = $this->recursiveEncode($val); } return $this->wrap($value, $result); } - private function encodeAsSingle(ExpressionInterface|StageInterface $value): stdClass + /** + * Get the unique property of the operator as value + */ + private function encodeAsSingle(AccumulatorInterface|ExpressionInterface|StageInterface|QueryInterface|FieldQueryInterface|WindowInterface $value): stdClass { - $result = []; - /** @var mixed $val */ foreach (get_object_vars($value) as $val) { - $result = $this->encodeIfSupported($val); - break; + $result = $this->recursiveEncode($val); + + return $this->wrap($value, $result); } - return $this->wrap($value, $result); + throw new LogicException(sprintf('Class "%s" does not have a single property.', $value::class)); + } + + private function encodeCombinedFilter(CombinedFieldQuery $filter): stdClass + { + $result = new stdClass(); + foreach ($filter->filters as $filter) { + $filter = $this->recursiveEncode($filter); + if (is_object($filter)) { + $filter = get_object_vars($filter); + } elseif (! is_array($filter)) { + throw new LogicException(sprintf('Query filters must an array or an object. Got "%s"', get_debug_type($filter))); + } + + foreach ($filter as $key => $value) { + $result->{$key} = $value; + } + } + + return $result; + } + + /** + * Query objects are encoded by merging query operator with field path to filter operators in the same object. + */ + private function encodeQueryObject(QueryObject $query): stdClass + { + $result = new stdClass(); + foreach ($query->queries as $key => $value) { + if ($value instanceof QueryInterface) { + // The sub-objects is merged into the main object, replacing duplicate keys + foreach (get_object_vars($this->recursiveEncode($value)) as $subKey => $subValue) { + if (property_exists($result, $subKey)) { + throw new LogicException(sprintf('Duplicate key "%s" in query object', $subKey)); + } + + $result->{$subKey} = $subValue; + } + } else { + if (property_exists($result, $key)) { + throw new LogicException(sprintf('Duplicate key "%s" in query object', $key)); + } + + $result->{$key} = $this->encodeIfSupported($value); + } + } + + return $result; + } + + /** + * For the $setWindowFields stage output parameter, the optional window parameter is encoded in the same object + * of the window operator. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/ + */ + private function encodeOutputWindow(OutputWindow $outputWindow): stdClass + { + $result = $this->recursiveEncode($outputWindow->operator); + + // Transform the result into an stdClass if a document is provided + if (! $outputWindow->operator instanceof WindowInterface && (is_array($result) || is_object($result))) { + if (! is_first_key_operator($result)) { + throw new LogicException(sprintf('Expected OutputWindow::$operator to be an operator. Got "%s"', array_key_first($result))); + } + + $result = (object) $result; + } + + if (! $result instanceof stdClass) { + throw new LogicException(sprintf('Expected OutputWindow::$operator to be an stdClass, array or WindowInterface. Got "%s"', get_debug_type($result))); + } + + if ($outputWindow->window !== Optional::Undefined) { + $result->window = $this->recursiveEncode($outputWindow->window); + } + + return $result; + } + + /** + * Nested arrays and objects must be encoded recursively. + */ + private function recursiveEncode(mixed $value): mixed + { + if (is_array($value)) { + foreach ($value as $key => $val) { + $value[$key] = $this->recursiveEncode($val); + } + + return $value; + } + + if ($value instanceof stdClass) { + foreach (get_object_vars($value) as $key => $val) { + $value->{$key} = $this->recursiveEncode($val); + } + } + + return $this->encodeIfSupported($value); } - private function wrap(ExpressionInterface|StageInterface $value, mixed $result): stdClass + private function wrap(object $value, mixed $result): stdClass { $object = new stdClass(); $object->{$value::NAME} = $result; diff --git a/src/Builder/Expression.php b/src/Builder/Expression.php index c1d20dd83..78aa63573 100644 --- a/src/Builder/Expression.php +++ b/src/Builder/Expression.php @@ -1,102 +1,14 @@ value = $value; + } +} diff --git a/src/Builder/Expression/AccumulatorOperator.php b/src/Builder/Expression/AccumulatorOperator.php new file mode 100644 index 000000000..23dcbf261 --- /dev/null +++ b/src/Builder/Expression/AccumulatorOperator.php @@ -0,0 +1,85 @@ +init = $init; + $this->accumulate = $accumulate; + if (is_array($accumulateArgs) && ! array_is_list($accumulateArgs)) { + throw new InvalidArgumentException('Expected $accumulateArgs argument to be a list, got an associative array.'); + } + + $this->accumulateArgs = $accumulateArgs; + $this->merge = $merge; + $this->lang = $lang; + if (is_array($initArgs) && ! array_is_list($initArgs)) { + throw new InvalidArgumentException('Expected $initArgs argument to be a list, got an associative array.'); + } + + $this->initArgs = $initArgs; + $this->finalize = $finalize; + } +} diff --git a/src/Builder/Expression/AcosOperator.php b/src/Builder/Expression/AcosOperator.php new file mode 100644 index 000000000..b87811cf2 --- /dev/null +++ b/src/Builder/Expression/AcosOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AcoshOperator.php b/src/Builder/Expression/AcoshOperator.php new file mode 100644 index 000000000..9bf8cc4ed --- /dev/null +++ b/src/Builder/Expression/AcoshOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AddOperator.php b/src/Builder/Expression/AddOperator.php new file mode 100644 index 000000000..50d56a996 --- /dev/null +++ b/src/Builder/Expression/AddOperator.php @@ -0,0 +1,44 @@ + ...$expression The arguments can be any valid expression as long as they resolve to either all numbers or to numbers and a date. */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToDate|ResolvesToNumber|UTCDateTime|float|int ...$expression The arguments can be any valid expression as long as they resolve to either all numbers or to numbers and a date. + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|UTCDateTime|ResolvesToDate|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/AddToSetOperator.php b/src/Builder/Expression/AddToSetOperator.php new file mode 100644 index 000000000..93a8a9af5 --- /dev/null +++ b/src/Builder/Expression/AddToSetOperator.php @@ -0,0 +1,48 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AllElementsTrueOperator.php b/src/Builder/Expression/AllElementsTrueOperator.php new file mode 100644 index 000000000..ddbd2d1aa --- /dev/null +++ b/src/Builder/Expression/AllElementsTrueOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + * @no-named-arguments + */ + public function __construct(PackedArray|ResolvesToArray|BSONArray|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/AndOperator.php b/src/Builder/Expression/AndOperator.php new file mode 100644 index 000000000..2064a0cf5 --- /dev/null +++ b/src/Builder/Expression/AndOperator.php @@ -0,0 +1,47 @@ + ...$expression */ + public array $expression; + + /** + * @param Decimal128|ExpressionInterface|Int64|ResolvesToBool|ResolvesToNull|ResolvesToNumber|ResolvesToString|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct( + Decimal128|Int64|Type|ResolvesToBool|ResolvesToNull|ResolvesToNumber|ResolvesToString|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ) { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/AnyElementTrueOperator.php b/src/Builder/Expression/AnyElementTrueOperator.php new file mode 100644 index 000000000..f7774e90d --- /dev/null +++ b/src/Builder/Expression/AnyElementTrueOperator.php @@ -0,0 +1,41 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ArrayElemAtOperator.php b/src/Builder/Expression/ArrayElemAtOperator.php new file mode 100644 index 000000000..187b2efc7 --- /dev/null +++ b/src/Builder/Expression/ArrayElemAtOperator.php @@ -0,0 +1,46 @@ +array = $array; + $this->idx = $idx; + } +} diff --git a/src/Builder/Expression/ArrayFieldPath.php b/src/Builder/Expression/ArrayFieldPath.php index 46d1fc380..c4514279c 100644 --- a/src/Builder/Expression/ArrayFieldPath.php +++ b/src/Builder/Expression/ArrayFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class ArrayFieldPath extends FieldPath implements ResolvesToArray +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class ArrayFieldPath implements FieldPathInterface, ResolvesToArray { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/ArrayToObjectOperator.php b/src/Builder/Expression/ArrayToObjectOperator.php new file mode 100644 index 000000000..c1f0034a4 --- /dev/null +++ b/src/Builder/Expression/ArrayToObjectOperator.php @@ -0,0 +1,41 @@ +array = $array; + } +} diff --git a/src/Builder/Expression/AsinOperator.php b/src/Builder/Expression/AsinOperator.php new file mode 100644 index 000000000..1296561b8 --- /dev/null +++ b/src/Builder/Expression/AsinOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AsinhOperator.php b/src/Builder/Expression/AsinhOperator.php new file mode 100644 index 000000000..9a5be89d8 --- /dev/null +++ b/src/Builder/Expression/AsinhOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/Atan2Operator.php b/src/Builder/Expression/Atan2Operator.php new file mode 100644 index 000000000..5b36dbb28 --- /dev/null +++ b/src/Builder/Expression/Atan2Operator.php @@ -0,0 +1,46 @@ +y = $y; + $this->x = $x; + } +} diff --git a/src/Builder/Expression/AtanOperator.php b/src/Builder/Expression/AtanOperator.php new file mode 100644 index 000000000..81d818dbb --- /dev/null +++ b/src/Builder/Expression/AtanOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AtanhOperator.php b/src/Builder/Expression/AtanhOperator.php new file mode 100644 index 000000000..034c4408a --- /dev/null +++ b/src/Builder/Expression/AtanhOperator.php @@ -0,0 +1,39 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/AvgOperator.php b/src/Builder/Expression/AvgOperator.php new file mode 100644 index 000000000..9a889c100 --- /dev/null +++ b/src/Builder/Expression/AvgOperator.php @@ -0,0 +1,44 @@ + ...$expression */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/BinDataFieldPath.php b/src/Builder/Expression/BinDataFieldPath.php new file mode 100644 index 000000000..653cf1f12 --- /dev/null +++ b/src/Builder/Expression/BinDataFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/BinarySizeOperator.php b/src/Builder/Expression/BinarySizeOperator.php new file mode 100644 index 000000000..d73249c6e --- /dev/null +++ b/src/Builder/Expression/BinarySizeOperator.php @@ -0,0 +1,32 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/BitAndOperator.php b/src/Builder/Expression/BitAndOperator.php new file mode 100644 index 000000000..4f384dd74 --- /dev/null +++ b/src/Builder/Expression/BitAndOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param Int64|ResolvesToInt|ResolvesToLong|int ...$expression + * @no-named-arguments + */ + public function __construct(Int64|ResolvesToInt|ResolvesToLong|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/BitNotOperator.php b/src/Builder/Expression/BitNotOperator.php new file mode 100644 index 000000000..d71c0c9e9 --- /dev/null +++ b/src/Builder/Expression/BitNotOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/BitOrOperator.php b/src/Builder/Expression/BitOrOperator.php new file mode 100644 index 000000000..da6ba6d0b --- /dev/null +++ b/src/Builder/Expression/BitOrOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param Int64|ResolvesToInt|ResolvesToLong|int ...$expression + * @no-named-arguments + */ + public function __construct(Int64|ResolvesToInt|ResolvesToLong|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/BitXorOperator.php b/src/Builder/Expression/BitXorOperator.php new file mode 100644 index 000000000..6c54f1ae4 --- /dev/null +++ b/src/Builder/Expression/BitXorOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param Int64|ResolvesToInt|ResolvesToLong|int ...$expression + * @no-named-arguments + */ + public function __construct(Int64|ResolvesToInt|ResolvesToLong|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/BoolFieldPath.php b/src/Builder/Expression/BoolFieldPath.php index 38c055af1..f6081e2b0 100644 --- a/src/Builder/Expression/BoolFieldPath.php +++ b/src/Builder/Expression/BoolFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class BoolFieldPath extends FieldPath implements ResolvesToBool +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class BoolFieldPath implements FieldPathInterface, ResolvesToBool { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/BottomNOperator.php b/src/Builder/Expression/BottomNOperator.php new file mode 100644 index 000000000..b090385d8 --- /dev/null +++ b/src/Builder/Expression/BottomNOperator.php @@ -0,0 +1,61 @@ +n = $n; + $this->sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Expression/BottomOperator.php b/src/Builder/Expression/BottomOperator.php new file mode 100644 index 000000000..e714504b9 --- /dev/null +++ b/src/Builder/Expression/BottomOperator.php @@ -0,0 +1,56 @@ +sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Expression/BsonSizeOperator.php b/src/Builder/Expression/BsonSizeOperator.php new file mode 100644 index 000000000..ab55a3ff9 --- /dev/null +++ b/src/Builder/Expression/BsonSizeOperator.php @@ -0,0 +1,34 @@ +object = $object; + } +} diff --git a/src/Builder/Expression/CeilOperator.php b/src/Builder/Expression/CeilOperator.php new file mode 100644 index 000000000..e4c7ddfcf --- /dev/null +++ b/src/Builder/Expression/CeilOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/CmpOperator.php b/src/Builder/Expression/CmpOperator.php new file mode 100644 index 000000000..01b8303ac --- /dev/null +++ b/src/Builder/Expression/CmpOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/ConcatArraysOperator.php b/src/Builder/Expression/ConcatArraysOperator.php new file mode 100644 index 000000000..cbc04c02d --- /dev/null +++ b/src/Builder/Expression/ConcatArraysOperator.php @@ -0,0 +1,43 @@ + ...$array */ + public array $array; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array ...$array + * @no-named-arguments + */ + public function __construct(PackedArray|ResolvesToArray|BSONArray|array ...$array) + { + if (\count($array) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $array, got %d.', 1, \count($array))); + } + if (! array_is_list($array)) { + throw new InvalidArgumentException('Expected $array arguments to be a list (array), named arguments are not supported'); + } + $this->array = $array; + } +} diff --git a/src/Builder/Expression/ConcatOperator.php b/src/Builder/Expression/ConcatOperator.php new file mode 100644 index 000000000..a84d5a841 --- /dev/null +++ b/src/Builder/Expression/ConcatOperator.php @@ -0,0 +1,41 @@ + ...$expression */ + public array $expression; + + /** + * @param ResolvesToString|non-empty-string ...$expression + * @no-named-arguments + */ + public function __construct(ResolvesToString|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/CondOperator.php b/src/Builder/Expression/CondOperator.php new file mode 100644 index 000000000..372f8d538 --- /dev/null +++ b/src/Builder/Expression/CondOperator.php @@ -0,0 +1,47 @@ +if = $if; + $this->then = $then; + $this->else = $else; + } +} diff --git a/src/Builder/Expression/ConvertOperator.php b/src/Builder/Expression/ConvertOperator.php new file mode 100644 index 000000000..b8ea1743d --- /dev/null +++ b/src/Builder/Expression/ConvertOperator.php @@ -0,0 +1,63 @@ +input = $input; + $this->to = $to; + $this->onError = $onError; + $this->onNull = $onNull; + } +} diff --git a/src/Builder/Expression/CosOperator.php b/src/Builder/Expression/CosOperator.php new file mode 100644 index 000000000..d1622aec0 --- /dev/null +++ b/src/Builder/Expression/CosOperator.php @@ -0,0 +1,37 @@ + resolves to a 128-bit decimal value. + */ + public Decimal128|Int64|ResolvesToNumber|float|int $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $cos takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + * By default $cos returns values as a double. $cos can also return values as a 128-bit decimal as long as the resolves to a 128-bit decimal value. + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int $expression) + { + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/CoshOperator.php b/src/Builder/Expression/CoshOperator.php new file mode 100644 index 000000000..704bcf61a --- /dev/null +++ b/src/Builder/Expression/CoshOperator.php @@ -0,0 +1,37 @@ + resolves to a 128-bit decimal value. + */ + public Decimal128|Int64|ResolvesToNumber|float|int $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $cosh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + * By default $cosh returns values as a double. $cosh can also return values as a 128-bit decimal if the resolves to a 128-bit decimal value. + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int $expression) + { + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/CountOperator.php b/src/Builder/Expression/CountOperator.php new file mode 100644 index 000000000..698b10989 --- /dev/null +++ b/src/Builder/Expression/CountOperator.php @@ -0,0 +1,35 @@ +field = $field; + } +} diff --git a/src/Builder/Expression/CovariancePopOperator.php b/src/Builder/Expression/CovariancePopOperator.php new file mode 100644 index 000000000..bb145330a --- /dev/null +++ b/src/Builder/Expression/CovariancePopOperator.php @@ -0,0 +1,42 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/CovarianceSampOperator.php b/src/Builder/Expression/CovarianceSampOperator.php new file mode 100644 index 000000000..dfd5bd7f8 --- /dev/null +++ b/src/Builder/Expression/CovarianceSampOperator.php @@ -0,0 +1,42 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/DateAddOperator.php b/src/Builder/Expression/DateAddOperator.php new file mode 100644 index 000000000..2e607d33b --- /dev/null +++ b/src/Builder/Expression/DateAddOperator.php @@ -0,0 +1,55 @@ +startDate = $startDate; + $this->unit = $unit; + $this->amount = $amount; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DateDiffOperator.php b/src/Builder/Expression/DateDiffOperator.php new file mode 100644 index 000000000..a62ce2457 --- /dev/null +++ b/src/Builder/Expression/DateDiffOperator.php @@ -0,0 +1,60 @@ +startDate = $startDate; + $this->endDate = $endDate; + $this->unit = $unit; + $this->timezone = $timezone; + $this->startOfWeek = $startOfWeek; + } +} diff --git a/src/Builder/Expression/DateFieldPath.php b/src/Builder/Expression/DateFieldPath.php index a00664a2b..89b60a346 100644 --- a/src/Builder/Expression/DateFieldPath.php +++ b/src/Builder/Expression/DateFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class DateFieldPath extends FieldPath implements ResolvesToDate +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class DateFieldPath implements FieldPathInterface, ResolvesToDate { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/DateFromPartsOperator.php b/src/Builder/Expression/DateFromPartsOperator.php new file mode 100644 index 000000000..3a05305dd --- /dev/null +++ b/src/Builder/Expression/DateFromPartsOperator.php @@ -0,0 +1,95 @@ +year = $year; + $this->isoWeekYear = $isoWeekYear; + $this->month = $month; + $this->isoWeek = $isoWeek; + $this->day = $day; + $this->isoDayOfWeek = $isoDayOfWeek; + $this->hour = $hour; + $this->minute = $minute; + $this->second = $second; + $this->millisecond = $millisecond; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DateFromStringOperator.php b/src/Builder/Expression/DateFromStringOperator.php new file mode 100644 index 000000000..f335d65b8 --- /dev/null +++ b/src/Builder/Expression/DateFromStringOperator.php @@ -0,0 +1,72 @@ +dateString = $dateString; + $this->format = $format; + $this->timezone = $timezone; + $this->onError = $onError; + $this->onNull = $onNull; + } +} diff --git a/src/Builder/Expression/DateSubtractOperator.php b/src/Builder/Expression/DateSubtractOperator.php new file mode 100644 index 000000000..1ab7a23af --- /dev/null +++ b/src/Builder/Expression/DateSubtractOperator.php @@ -0,0 +1,55 @@ +startDate = $startDate; + $this->unit = $unit; + $this->amount = $amount; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DateToPartsOperator.php b/src/Builder/Expression/DateToPartsOperator.php new file mode 100644 index 000000000..747779ac6 --- /dev/null +++ b/src/Builder/Expression/DateToPartsOperator.php @@ -0,0 +1,48 @@ +date = $date; + $this->timezone = $timezone; + $this->iso8601 = $iso8601; + } +} diff --git a/src/Builder/Expression/DateToStringOperator.php b/src/Builder/Expression/DateToStringOperator.php new file mode 100644 index 000000000..034e76ff5 --- /dev/null +++ b/src/Builder/Expression/DateToStringOperator.php @@ -0,0 +1,65 @@ +date = $date; + $this->format = $format; + $this->timezone = $timezone; + $this->onNull = $onNull; + } +} diff --git a/src/Builder/Expression/DateTruncOperator.php b/src/Builder/Expression/DateTruncOperator.php new file mode 100644 index 000000000..e6b1ba404 --- /dev/null +++ b/src/Builder/Expression/DateTruncOperator.php @@ -0,0 +1,74 @@ +date = $date; + $this->unit = $unit; + $this->binSize = $binSize; + $this->timezone = $timezone; + $this->startOfWeek = $startOfWeek; + } +} diff --git a/src/Builder/Expression/DayOfMonthOperator.php b/src/Builder/Expression/DayOfMonthOperator.php new file mode 100644 index 000000000..8b3a4f4ea --- /dev/null +++ b/src/Builder/Expression/DayOfMonthOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DayOfWeekOperator.php b/src/Builder/Expression/DayOfWeekOperator.php new file mode 100644 index 000000000..947d1182d --- /dev/null +++ b/src/Builder/Expression/DayOfWeekOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DayOfYearOperator.php b/src/Builder/Expression/DayOfYearOperator.php new file mode 100644 index 000000000..9ccffaa7d --- /dev/null +++ b/src/Builder/Expression/DayOfYearOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/DecimalFieldPath.php b/src/Builder/Expression/DecimalFieldPath.php index c8327df61..3139122bc 100644 --- a/src/Builder/Expression/DecimalFieldPath.php +++ b/src/Builder/Expression/DecimalFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class DecimalFieldPath extends FieldPath implements ResolvesToDecimal +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class DecimalFieldPath implements FieldPathInterface, ResolvesToDecimal { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/DegreesToRadiansOperator.php b/src/Builder/Expression/DegreesToRadiansOperator.php new file mode 100644 index 000000000..30224e854 --- /dev/null +++ b/src/Builder/Expression/DegreesToRadiansOperator.php @@ -0,0 +1,37 @@ + resolves to a 128-bit decimal value. + */ + public Decimal128|Int64|ResolvesToNumber|float|int $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $degreesToRadians takes any valid expression that resolves to a number. + * By default $degreesToRadians returns values as a double. $degreesToRadians can also return values as a 128-bit decimal as long as the resolves to a 128-bit decimal value. + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int $expression) + { + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/DenseRankOperator.php b/src/Builder/Expression/DenseRankOperator.php new file mode 100644 index 000000000..a322790d5 --- /dev/null +++ b/src/Builder/Expression/DenseRankOperator.php @@ -0,0 +1,26 @@ +input = $input; + $this->unit = $unit; + } +} diff --git a/src/Builder/Expression/DivideOperator.php b/src/Builder/Expression/DivideOperator.php new file mode 100644 index 000000000..352688139 --- /dev/null +++ b/src/Builder/Expression/DivideOperator.php @@ -0,0 +1,40 @@ +dividend = $dividend; + $this->divisor = $divisor; + } +} diff --git a/src/Builder/Expression/DocumentNumberOperator.php b/src/Builder/Expression/DocumentNumberOperator.php new file mode 100644 index 000000000..f05b9a8c3 --- /dev/null +++ b/src/Builder/Expression/DocumentNumberOperator.php @@ -0,0 +1,26 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/EqOperator.php b/src/Builder/Expression/EqOperator.php new file mode 100644 index 000000000..e13071881 --- /dev/null +++ b/src/Builder/Expression/EqOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/ExpMovingAvgOperator.php b/src/Builder/Expression/ExpMovingAvgOperator.php new file mode 100644 index 000000000..57f8d216f --- /dev/null +++ b/src/Builder/Expression/ExpMovingAvgOperator.php @@ -0,0 +1,59 @@ +input = $input; + $this->N = $N; + $this->alpha = $alpha; + } +} diff --git a/src/Builder/Expression/ExpOperator.php b/src/Builder/Expression/ExpOperator.php new file mode 100644 index 000000000..a7bb2d39e --- /dev/null +++ b/src/Builder/Expression/ExpOperator.php @@ -0,0 +1,33 @@ +exponent = $exponent; + } +} diff --git a/src/Builder/Expression/ExpressionFactoryTrait.php b/src/Builder/Expression/ExpressionFactoryTrait.php new file mode 100644 index 000000000..88b15061c --- /dev/null +++ b/src/Builder/Expression/ExpressionFactoryTrait.php @@ -0,0 +1,103 @@ + resolves to a 128-bit decimal value. + */ + public static function cos(Decimal128|Int64|ResolvesToNumber|float|int $expression): CosOperator + { + return new CosOperator($expression); + } + + /** + * Returns the hyperbolic cosine of a value that is measured in radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/cosh/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $cosh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + * By default $cosh returns values as a double. $cosh can also return values as a 128-bit decimal if the resolves to a 128-bit decimal value. + */ + public static function cosh(Decimal128|Int64|ResolvesToNumber|float|int $expression): CoshOperator + { + return new CoshOperator($expression); + } + + /** + * Adds a number of time units to a date object. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateAdd/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $startDate The beginning date, in UTC, for the addition operation. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param ResolvesToString|non-empty-string $unit The unit used to measure the amount of time added to the startDate. + * @param Int64|ResolvesToInt|ResolvesToLong|int $amount + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dateAdd( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $startDate, + ResolvesToString|string $unit, + Int64|ResolvesToInt|ResolvesToLong|int $amount, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DateAddOperator + { + return new DateAddOperator($startDate, $unit, $amount, $timezone); + } + + /** + * Returns the difference between two dates. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateDiff/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $startDate The start of the time period. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $endDate The end of the time period. The endDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param ResolvesToString|non-empty-string $unit The time measurement unit between the startDate and endDate + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + * @param Optional|ResolvesToString|non-empty-string $startOfWeek Used when the unit is equal to week. Defaults to Sunday. The startOfWeek parameter is an expression that resolves to a case insensitive string + */ + public static function dateDiff( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $startDate, + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $endDate, + ResolvesToString|string $unit, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + Optional|ResolvesToString|string $startOfWeek = Optional::Undefined, + ): DateDiffOperator + { + return new DateDiffOperator($startDate, $endDate, $unit, $timezone, $startOfWeek); + } + + /** + * Constructs a BSON Date object given the date's constituent parts. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromParts/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $year Calendar year. Can be any expression that evaluates to a number. + * @param Decimal128|Int64|ResolvesToNumber|float|int $isoWeekYear ISO Week Date Year. Can be any expression that evaluates to a number. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $month Month. Defaults to 1. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $isoWeek Week of year. Defaults to 1. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $day Day of month. Defaults to 1. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $isoDayOfWeek Day of week (Monday 1 - Sunday 7). Defaults to 1. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $hour Hour. Defaults to 0. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $minute Minute. Defaults to 0. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $second Second. Defaults to 0. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $millisecond Millisecond. Defaults to 0. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dateFromParts( + Decimal128|Int64|ResolvesToNumber|float|int $year, + Decimal128|Int64|ResolvesToNumber|float|int $isoWeekYear, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $month = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $isoWeek = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $day = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $isoDayOfWeek = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $hour = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $minute = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $second = Optional::Undefined, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $millisecond = Optional::Undefined, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DateFromPartsOperator + { + return new DateFromPartsOperator($year, $isoWeekYear, $month, $isoWeek, $day, $isoDayOfWeek, $hour, $minute, $second, $millisecond, $timezone); + } + + /** + * Converts a date/time string to a date object. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromString/ + * @param ResolvesToString|non-empty-string $dateString The date/time string to convert to a date object. + * @param Optional|ResolvesToString|non-empty-string $format The date format specification of the dateString. The format can be any expression that evaluates to a string literal, containing 0 or more format specifiers. + * If unspecified, $dateFromString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format but accepts a variety of formats and attempts to parse the dateString if possible. + * @param Optional|ResolvesToString|non-empty-string $timezone The time zone to use to format the date. + * @param Optional|ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $onError If $dateFromString encounters an error while parsing the given dateString, it outputs the result value of the provided onError expression. This result value can be of any type. + * If you do not specify onError, $dateFromString throws an error if it cannot parse dateString. + * @param Optional|ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $onNull If the dateString provided to $dateFromString is null or missing, it outputs the result value of the provided onNull expression. This result value can be of any type. + * If you do not specify onNull and dateString is null or missing, then $dateFromString outputs null. + */ + public static function dateFromString( + ResolvesToString|string $dateString, + Optional|ResolvesToString|string $format = Optional::Undefined, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + Optional|Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $onError = Optional::Undefined, + Optional|Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $onNull = Optional::Undefined, + ): DateFromStringOperator + { + return new DateFromStringOperator($dateString, $format, $timezone, $onError, $onNull); + } + + /** + * Subtracts a number of time units from a date object. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateSubtract/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $startDate The beginning date, in UTC, for the addition operation. The startDate can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param ResolvesToString|non-empty-string $unit The unit used to measure the amount of time added to the startDate. + * @param Int64|ResolvesToInt|ResolvesToLong|int $amount + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dateSubtract( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $startDate, + ResolvesToString|string $unit, + Int64|ResolvesToInt|ResolvesToLong|int $amount, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DateSubtractOperator + { + return new DateSubtractOperator($startDate, $unit, $amount, $timezone); + } + + /** + * Returns a document containing the constituent parts of a date. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToParts/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The input date for which to return parts. date can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + * @param Optional|bool $iso8601 If set to true, modifies the output document to use ISO week date fields. Defaults to false. + */ + public static function dateToParts( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + Optional|bool $iso8601 = Optional::Undefined, + ): DateToPartsOperator + { + return new DateToPartsOperator($date, $timezone, $iso8601); + } + + /** + * Returns the date as a formatted string. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToString/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to convert to string. Must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $format The date format specification of the dateString. The format can be any expression that evaluates to a string literal, containing 0 or more format specifiers. + * If unspecified, $dateFromString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format but accepts a variety of formats and attempts to parse the dateString if possible. + * @param Optional|ResolvesToString|non-empty-string $timezone The time zone to use to format the date. + * @param Optional|ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $onNull The value to return if the date is null or missing. + * If unspecified, $dateToString returns null if the date is null or missing. + */ + public static function dateToString( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $format = Optional::Undefined, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + Optional|Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $onNull = Optional::Undefined, + ): DateToStringOperator + { + return new DateToStringOperator($date, $format, $timezone, $onNull); + } + + /** + * Truncates a date. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateTrunc/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to truncate, specified in UTC. The date can be any expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param ResolvesToString|non-empty-string $unit The unit of time, specified as an expression that must resolve to one of these strings: year, quarter, week, month, day, hour, minute, second. + * Together, binSize and unit specify the time period used in the $dateTrunc calculation. + * @param Optional|Decimal128|Int64|ResolvesToNumber|float|int $binSize The numeric time value, specified as an expression that must resolve to a positive non-zero number. Defaults to 1. + * Together, binSize and unit specify the time period used in the $dateTrunc calculation. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone to carry out the operation. $timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + * @param Optional|non-empty-string $startOfWeek The start of the week. Used when + * unit is week. Defaults to Sunday. + */ + public static function dateTrunc( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + ResolvesToString|string $unit, + Optional|Decimal128|Int64|ResolvesToNumber|float|int $binSize = Optional::Undefined, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + Optional|string $startOfWeek = Optional::Undefined, + ): DateTruncOperator + { + return new DateTruncOperator($date, $unit, $binSize, $timezone, $startOfWeek); + } + + /** + * Returns the day of the month for a date as a number between 1 and 31. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfMonth/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dayOfMonth( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DayOfMonthOperator + { + return new DayOfMonthOperator($date, $timezone); + } + + /** + * Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfWeek/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dayOfWeek( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DayOfWeekOperator + { + return new DayOfWeekOperator($date, $timezone); + } + + /** + * Returns the day of the year for a date as a number between 1 and 366 (leap year). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfYear/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function dayOfYear( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): DayOfYearOperator + { + return new DayOfYearOperator($date, $timezone); + } + + /** + * Converts a value from degrees to radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/degreesToRadians/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $degreesToRadians takes any valid expression that resolves to a number. + * By default $degreesToRadians returns values as a double. $degreesToRadians can also return values as a 128-bit decimal as long as the resolves to a 128-bit decimal value. + */ + public static function degreesToRadians( + Decimal128|Int64|ResolvesToNumber|float|int $expression, + ): DegreesToRadiansOperator + { + return new DegreesToRadiansOperator($expression); + } + + /** + * Returns the result of dividing the first number by the second. Accepts two argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/divide/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $dividend The first argument is the dividend, and the second argument is the divisor; i.e. the first argument is divided by the second argument. + * @param Decimal128|Int64|ResolvesToNumber|float|int $divisor + */ + public static function divide( + Decimal128|Int64|ResolvesToNumber|float|int $dividend, + Decimal128|Int64|ResolvesToNumber|float|int $divisor, + ): DivideOperator + { + return new DivideOperator($dividend, $divisor); + } + + /** + * Returns true if the values are equivalent. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/eq/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function eq( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): EqOperator + { + return new EqOperator($expression1, $expression2); + } + + /** + * Raises e to the specified exponent. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/exp/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $exponent + */ + public static function exp(Decimal128|Int64|ResolvesToNumber|float|int $exponent): ExpOperator + { + return new ExpOperator($exponent); + } + + /** + * Selects a subset of the array to return an array with only the elements that match the filter condition. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input + * @param ResolvesToBool|bool $cond An expression that resolves to a boolean value used to determine if an element should be included in the output array. The expression references each element of the input array individually with the variable name specified in as. + * @param Optional|non-empty-string $as A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this. + * @param Optional|ResolvesToInt|int $limit A number expression that restricts the number of matching array elements that $filter returns. You cannot specify a limit less than 1. The matching array elements are returned in the order they appear in the input array. + * If the specified limit is greater than the number of matching array elements, $filter returns all matching array elements. If the limit is null, $filter returns all matching array elements. + */ + public static function filter( + PackedArray|ResolvesToArray|BSONArray|array $input, + ResolvesToBool|bool $cond, + Optional|string $as = Optional::Undefined, + Optional|ResolvesToInt|int $limit = Optional::Undefined, + ): FilterOperator + { + return new FilterOperator($input, $cond, $as, $limit); + } + + /** + * Returns the largest integer less than or equal to the specified number. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/floor/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression + */ + public static function floor(Decimal128|Int64|ResolvesToNumber|float|int $expression): FloorOperator + { + return new FloorOperator($expression); + } + + /** + * Defines a custom function. + * New in version 4.4. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/function/ + * @param non-empty-string $body The function definition. You can specify the function definition as either BSON type Code or String. + * @param BSONArray|PackedArray|array $args Arguments passed to the function body. If the body function does not take an argument, you can specify an empty array [ ]. + * @param non-empty-string $lang + */ + public static function function(string $body, PackedArray|BSONArray|array $args, string $lang): FunctionOperator + { + return new FunctionOperator($body, $args, $lang); + } + + /** + * Returns the value of a specified field from a document. You can use $getField to retrieve the value of fields with names that contain periods (.) or start with dollar signs ($). + * New in version 5.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/getField/ + * @param non-empty-string $field Field in the input object for which you want to return a value. field can be any valid expression that resolves to a string constant. + * If field begins with a dollar sign ($), place the field name inside of a $literal expression to return its value. + * @param Optional|ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $input Default: $$CURRENT + * A valid expression that contains the field for which you want to return a value. input must resolve to an object, missing, null, or undefined. If omitted, defaults to the document currently being processed in the pipeline ($$CURRENT). + */ + public static function getField( + string $field, + Optional|Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $input = Optional::Undefined, + ): GetFieldOperator + { + return new GetFieldOperator($field, $input); + } + + /** + * Returns true if the first value is greater than the second. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/gt/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function gt( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): GtOperator + { + return new GtOperator($expression1, $expression2); + } + + /** + * Returns true if the first value is greater than or equal to the second. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/gte/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function gte( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): GteOperator + { + return new GteOperator($expression1, $expression2); + } + + /** + * Returns the hour for a date as a number between 0 and 23. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/hour/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function hour( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): HourOperator + { + return new HourOperator($date, $timezone); + } + + /** + * Returns either the non-null result of the first expression or the result of the second expression if the first expression results in a null result. Null result encompasses instances of undefined values or missing fields. Accepts two expressions as arguments. The result of the second expression can be null. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ifNull/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function ifNull( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): IfNullOperator + { + return new IfNullOperator(...$expression); + } + + /** + * Returns a boolean indicating whether a specified value is in an array. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/in/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression Any valid expression expression. + * @param BSONArray|PackedArray|ResolvesToArray|array $array Any valid expression that resolves to an array. + */ + public static function in( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + PackedArray|ResolvesToArray|BSONArray|array $array, + ): InOperator + { + return new InOperator($expression, $array); + } + + /** + * Searches an array for an occurrence of a specified value and returns the array index of the first occurrence. Array indexes start at zero. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfArray/ + * @param ResolvesToString|non-empty-string $array Can be any valid expression as long as it resolves to an array. + * If the array expression resolves to a value of null or refers to a field that is missing, $indexOfArray returns null. + * If the array expression does not resolve to an array or null nor refers to a missing field, $indexOfArray returns an error. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $search + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public static function indexOfArray( + ResolvesToString|string $array, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $search, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ): IndexOfArrayOperator + { + return new IndexOfArrayOperator($array, $search, $start, $end); + } + + /** + * Searches a string for an occurrence of a substring and returns the UTF-8 byte index of the first occurrence. If the substring is not found, returns -1. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfBytes/ + * @param ResolvesToString|non-empty-string $string Can be any valid expression as long as it resolves to a string. + * If the string expression resolves to a value of null or refers to a field that is missing, $indexOfBytes returns null. + * If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfBytes returns an error. + * @param ResolvesToString|non-empty-string $substring Can be any valid expression as long as it resolves to a string. + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public static function indexOfBytes( + ResolvesToString|string $string, + ResolvesToString|string $substring, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ): IndexOfBytesOperator + { + return new IndexOfBytesOperator($string, $substring, $start, $end); + } + + /** + * Searches a string for an occurrence of a substring and returns the UTF-8 code point index of the first occurrence. If the substring is not found, returns -1 + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfCP/ + * @param ResolvesToString|non-empty-string $string Can be any valid expression as long as it resolves to a string. + * If the string expression resolves to a value of null or refers to a field that is missing, $indexOfCP returns null. + * If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfCP returns an error. + * @param ResolvesToString|non-empty-string $substring Can be any valid expression as long as it resolves to a string. + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public static function indexOfCP( + ResolvesToString|string $string, + ResolvesToString|string $substring, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ): IndexOfCPOperator + { + return new IndexOfCPOperator($string, $substring, $start, $end); + } + + /** + * Returns the approximation of the area under a curve. + * New in version 5.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/integral/ + * @param Decimal128|Int64|ResolvesToDate|ResolvesToNumber|UTCDateTime|float|int $input + * @param Optional|ResolvesToString|non-empty-string $unit A string that specifies the time unit. Use one of these strings: "week", "day","hour", "minute", "second", "millisecond". + * If the sortBy field is not a date, you must omit a unit. If you specify a unit, you must specify a date in the sortBy field. + */ + public static function integral( + Decimal128|Int64|UTCDateTime|ResolvesToDate|ResolvesToNumber|float|int $input, + Optional|ResolvesToString|string $unit = Optional::Undefined, + ): IntegralOperator + { + return new IntegralOperator($input, $unit); + } + + /** + * Determines if the operand is an array. Returns a boolean. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/isArray/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function isArray( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): IsArrayOperator + { + return new IsArrayOperator(...$expression); + } + + /** + * Returns boolean true if the specified expression resolves to an integer, decimal, double, or long. + * Returns boolean false if the expression resolves to any other BSON type, null, or a missing field. + * New in version 4.4. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/isNumber/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function isNumber( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): IsNumberOperator + { + return new IsNumberOperator(...$expression); + } + + /** + * Returns the weekday number in ISO 8601 format, ranging from 1 (for Monday) to 7 (for Sunday). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoDayOfWeek/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function isoDayOfWeek( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): IsoDayOfWeekOperator + { + return new IsoDayOfWeekOperator($date, $timezone); + } + + /** + * Returns the week number in ISO 8601 format, ranging from 1 to 53. Week numbers start at 1 with the week (Monday through Sunday) that contains the year's first Thursday. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoWeek/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function isoWeek( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): IsoWeekOperator + { + return new IsoWeekOperator($date, $timezone); + } + + /** + * Returns the year number in ISO 8601 format. The year starts with the Monday of week 1 (ISO 8601) and ends with the Sunday of the last week (ISO 8601). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/isoWeekYear/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function isoWeekYear( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): IsoWeekYearOperator + { + return new IsoWeekYearOperator($date, $timezone); + } + + /** + * Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters. + * Accepts any number of argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/let/ + * @param Document|Serializable|array|stdClass $vars Assignment block for the variables accessible in the in expression. To assign a variable, specify a string for the variable name and assign a valid expression for the value. + * The variable assignments have no meaning outside the in expression, not even within the vars block itself. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $in The expression to evaluate. + */ + public static function let( + Document|Serializable|stdClass|array $vars, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $in, + ): LetOperator + { + return new LetOperator($vars, $in); + } + + /** + * Fills null and missing fields in a window using linear interpolation based on surrounding field values. + * Available in the $setWindowFields stage. + * New in version 5.3. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/linearFill/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression + */ + public static function linearFill(Decimal128|Int64|ResolvesToNumber|float|int $expression): LinearFillOperator + { + return new LinearFillOperator($expression); + } + + /** + * Return a value without parsing. Use for values that the aggregation pipeline may interpret as an expression. For example, use a $literal expression to a string that starts with a dollar sign ($) to avoid parsing as a field path. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/literal/ + * @param Type|array|bool|float|int|non-empty-string|null|stdClass $value If the value is an expression, $literal does not evaluate the expression but instead returns the unparsed expression. + */ + public static function literal(Type|stdClass|array|bool|float|int|null|string $value): LiteralOperator + { + return new LiteralOperator($value); + } + + /** + * Calculates the natural log of a number. + * $ln is equivalent to $log: [ , Math.E ] expression, where Math.E is a JavaScript representation for Euler's number e. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ln/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number Any valid expression as long as it resolves to a non-negative number. For more information on expressions, see Expressions. + */ + public static function ln(Decimal128|Int64|ResolvesToNumber|float|int $number): LnOperator + { + return new LnOperator($number); + } + + /** + * Last observation carried forward. Sets values for null and missing fields in a window to the last non-null value for the field. + * Available in the $setWindowFields stage. + * New in version 5.2. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/locf/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function locf( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): LocfOperator + { + return new LocfOperator($expression); + } + + /** + * Calculates the log of a number in the specified base. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/log/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number Any valid expression as long as it resolves to a non-negative number. + * @param Decimal128|Int64|ResolvesToNumber|float|int $base Any valid expression as long as it resolves to a positive number greater than 1. + */ + public static function log( + Decimal128|Int64|ResolvesToNumber|float|int $number, + Decimal128|Int64|ResolvesToNumber|float|int $base, + ): LogOperator + { + return new LogOperator($number, $base); + } + + /** + * Calculates the log base 10 of a number. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/log10/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number Any valid expression as long as it resolves to a non-negative number. + */ + public static function log10(Decimal128|Int64|ResolvesToNumber|float|int $number): Log10Operator + { + return new Log10Operator($number); + } + + /** + * Returns true if the first value is less than the second. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/lt/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function lt( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): LtOperator + { + return new LtOperator($expression1, $expression2); + } + + /** + * Returns true if the first value is less than or equal to the second. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/lte/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function lte( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): LteOperator + { + return new LteOperator($expression1, $expression2); + } + + /** + * Removes whitespace or the specified characters from the beginning of a string. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ltrim/ + * @param ResolvesToString|non-empty-string $input The string to trim. The argument can be any valid expression that resolves to a string. + * @param Optional|ResolvesToString|non-empty-string $chars The character(s) to trim from the beginning of the input. + * The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + * If unspecified, $ltrim removes whitespace characters, including the null character. + */ + public static function ltrim( + ResolvesToString|string $input, + Optional|ResolvesToString|string $chars = Optional::Undefined, + ): LtrimOperator + { + return new LtrimOperator($input, $chars); + } + + /** + * Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/map/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input An expression that resolves to an array. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $in An expression that is applied to each element of the input array. The expression references each element individually with the variable name specified in as. + * @param Optional|ResolvesToString|non-empty-string $as A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this. + */ + public static function map( + PackedArray|ResolvesToArray|BSONArray|array $input, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $in, + Optional|ResolvesToString|string $as = Optional::Undefined, + ): MapOperator + { + return new MapOperator($input, $in, $as); + } + + /** + * Returns the maximum value that results from applying an expression to each document. + * Changed in version 5.0: Available in the $setWindowFields stage. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/max/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function max( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): MaxOperator + { + return new MaxOperator(...$expression); + } + + /** + * Returns the n largest values in an array. Distinct from the $maxN accumulator. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxN-array-element/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input An expression that resolves to the array from which to return the maximal n elements. + * @param ResolvesToInt|int $n An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. + */ + public static function maxN( + PackedArray|ResolvesToArray|BSONArray|array $input, + ResolvesToInt|int $n, + ): MaxNOperator + { + return new MaxNOperator($input, $n); + } + + /** + * Returns an approximation of the median, the 50th percentile, as a scalar value. + * New in version 7.0. + * This operator is available as an accumulator in these stages: + * $group + * $setWindowFields + * It is also available as an aggregation expression. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/median/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $input $median calculates the 50th percentile value of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $median calculation ignores it. + * @param non-empty-string $method The method that mongod uses to calculate the 50th percentile value. The method must be 'approximate'. + */ + public static function median(Decimal128|Int64|ResolvesToNumber|float|int $input, string $method): MedianOperator + { + return new MedianOperator($input, $method); + } + + /** + * Access available per-document metadata related to the aggregation operation. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta/ + * @param non-empty-string $keyword + */ + public static function meta(string $keyword): MetaOperator + { + return new MetaOperator($keyword); + } + + /** + * Returns the milliseconds of a date as a number between 0 and 999. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/millisecond/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function millisecond( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): MillisecondOperator + { + return new MillisecondOperator($date, $timezone); + } + + /** + * Returns the minimum value that results from applying an expression to each document. + * Changed in version 5.0: Available in the $setWindowFields stage. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/min/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function min( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): MinOperator + { + return new MinOperator(...$expression); + } + + /** + * Returns the n smallest values in an array. Distinct from the $minN accumulator. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/minN-array-element/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input An expression that resolves to the array from which to return the maximal n elements. + * @param ResolvesToInt|int $n An expression that resolves to a positive integer. The integer specifies the number of array elements that $maxN returns. + */ + public static function minN( + PackedArray|ResolvesToArray|BSONArray|array $input, + ResolvesToInt|int $n, + ): MinNOperator + { + return new MinNOperator($input, $n); + } + + /** + * Returns the minute for a date as a number between 0 and 59. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/minute/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function minute( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): MinuteOperator + { + return new MinuteOperator($date, $timezone); + } + + /** + * Returns the remainder of the first number divided by the second. Accepts two argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/mod/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $dividend The first argument is the dividend, and the second argument is the divisor; i.e. first argument is divided by the second argument. + * @param Decimal128|Int64|ResolvesToNumber|float|int $divisor + */ + public static function mod( + Decimal128|Int64|ResolvesToNumber|float|int $dividend, + Decimal128|Int64|ResolvesToNumber|float|int $divisor, + ): ModOperator + { + return new ModOperator($dividend, $divisor); + } + + /** + * Returns the month for a date as a number between 1 (January) and 12 (December). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/month/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function month( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): MonthOperator + { + return new MonthOperator($date, $timezone); + } + + /** + * Multiplies numbers to return the product. Accepts any number of argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/multiply/ + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression The arguments can be any valid expression as long as they resolve to numbers. + * Starting in MongoDB 6.1 you can optimize the $multiply operation. To improve performance, group references at the end of the argument list. + */ + public static function multiply(Decimal128|Int64|ResolvesToNumber|float|int ...$expression): MultiplyOperator + { + return new MultiplyOperator(...$expression); + } + + /** + * Returns true if the values are not equivalent. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ne/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression1 + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression2 + */ + public static function ne( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression1, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression2, + ): NeOperator + { + return new NeOperator($expression1, $expression2); + } + + /** + * Returns the boolean value that is the opposite of its argument expression. Accepts a single argument expression. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/not/ + * @param ExpressionInterface|ResolvesToBool|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function not( + Type|ResolvesToBool|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): NotOperator + { + return new NotOperator($expression); + } + + /** + * Converts a document to an array of documents representing key-value pairs. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/objectToArray/ + * @param Document|ResolvesToObject|Serializable|array|stdClass $object Any valid expression as long as it resolves to a document object. $objectToArray applies to the top-level fields of its argument. If the argument is a document that itself contains embedded document fields, the $objectToArray does not recursively apply to the embedded document fields. + */ + public static function objectToArray( + Document|Serializable|ResolvesToObject|stdClass|array $object, + ): ObjectToArrayOperator + { + return new ObjectToArrayOperator($object); + } + + /** + * Returns true when any of its expressions evaluates to true. Accepts any number of argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/or/ + * @param ExpressionInterface|ResolvesToBool|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + */ + public static function or( + Type|ResolvesToBool|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ): OrOperator + { + return new OrOperator(...$expression); + } + + /** + * Returns an array of scalar values that correspond to specified percentile values. + * New in version 7.0. + * + * This operator is available as an accumulator in these stages: + * $group + * + * $setWindowFields + * + * It is also available as an aggregation expression. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/percentile/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $input $percentile calculates the percentile values of this data. input must be a field name or an expression that evaluates to a numeric type. If the expression cannot be converted to a numeric type, the $percentile calculation ignores it. + * @param BSONArray|PackedArray|ResolvesToArray|array $p $percentile calculates a percentile value for each element in p. The elements represent percentages and must evaluate to numeric values in the range 0.0 to 1.0, inclusive. + * $percentile returns results in the same order as the elements in p. + * @param non-empty-string $method The method that mongod uses to calculate the percentile value. The method must be 'approximate'. + */ + public static function percentile( + Decimal128|Int64|ResolvesToNumber|float|int $input, + PackedArray|ResolvesToArray|BSONArray|array $p, + string $method, + ): PercentileOperator + { + return new PercentileOperator($input, $p, $method); + } + + /** + * Raises a number to the specified exponent. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/pow/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number + * @param Decimal128|Int64|ResolvesToNumber|float|int $exponent + */ + public static function pow( + Decimal128|Int64|ResolvesToNumber|float|int $number, + Decimal128|Int64|ResolvesToNumber|float|int $exponent, + ): PowOperator + { + return new PowOperator($number, $exponent); + } + + /** + * Converts a value from radians to degrees. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/radiansToDegrees/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression + */ + public static function radiansToDegrees( + Decimal128|Int64|ResolvesToNumber|float|int $expression, + ): RadiansToDegreesOperator + { + return new RadiansToDegreesOperator($expression); + } + + /** + * Returns a random float between 0 and 1 + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/rand/ + */ + public static function rand(): RandOperator + { + return new RandOperator(); + } + + /** + * Outputs an array containing a sequence of integers according to user-defined inputs. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/range/ + * @param ResolvesToInt|int $start An integer that specifies the start of the sequence. Can be any valid expression that resolves to an integer. + * @param ResolvesToInt|int $end An integer that specifies the exclusive upper limit of the sequence. Can be any valid expression that resolves to an integer. + * @param Optional|ResolvesToInt|int $step An integer that specifies the increment value. Can be any valid expression that resolves to a non-zero integer. Defaults to 1. + */ + public static function range( + ResolvesToInt|int $start, + ResolvesToInt|int $end, + Optional|ResolvesToInt|int $step = Optional::Undefined, + ): RangeOperator + { + return new RangeOperator($start, $end, $step); + } + + /** + * Returns the document position (known as the rank) relative to other documents in the $setWindowFields stage partition. + * New in version 5.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/rank/ + */ + public static function rank(): RankOperator + { + return new RankOperator(); + } + + /** + * Applies an expression to each element in an array and combines them into a single value. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/reduce/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input Can be any valid expression that resolves to an array. + * If the argument resolves to a value of null or refers to a missing field, $reduce returns null. + * If the argument does not resolve to an array or null nor refers to a missing field, $reduce returns an error. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $initialValue The initial cumulative value set before in is applied to the first element of the input array. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $in A valid expression that $reduce applies to each element in the input array in left-to-right order. Wrap the input value with $reverseArray to yield the equivalent of applying the combining expression from right-to-left. + * During evaluation of the in expression, two variables will be available: + * - value is the variable that represents the cumulative value of the expression. + * - this is the variable that refers to the element being processed. + */ + public static function reduce( + PackedArray|ResolvesToArray|BSONArray|array $input, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $initialValue, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $in, + ): ReduceOperator + { + return new ReduceOperator($input, $initialValue, $in); + } + + /** + * Applies a regular expression (regex) to a string and returns information on the first matched substring. + * New in version 4.2. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexFind/ + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public static function regexFind( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ): RegexFindOperator + { + return new RegexFindOperator($input, $regex, $options); + } + + /** + * Applies a regular expression (regex) to a string and returns information on the all matched substrings. + * New in version 4.2. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexFindAll/ + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public static function regexFindAll( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ): RegexFindAllOperator + { + return new RegexFindAllOperator($input, $regex, $options); + } + + /** + * Applies a regular expression (regex) to a string and returns a boolean that indicates if a match is found or not. + * New in version 4.2. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/regexMatch/ + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public static function regexMatch( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ): RegexMatchOperator + { + return new RegexMatchOperator($input, $regex, $options); + } + + /** + * Replaces all instances of a search string in an input string with a replacement string. + * $replaceAll is both case-sensitive and diacritic-sensitive, and ignores any collation present on a collection. + * New in version 4.4. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceAll/ + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $input The string on which you wish to apply the find. Can be any valid expression that resolves to a string or a null. If input refers to a field that is missing, $replaceAll returns null. + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $find The string to search for within the given input. Can be any valid expression that resolves to a string or a null. If find refers to a field that is missing, $replaceAll returns null. + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $replacement The string to use to replace all matched instances of find in input. Can be any valid expression that resolves to a string or a null. + */ + public static function replaceAll( + ResolvesToNull|ResolvesToString|null|string $input, + ResolvesToNull|ResolvesToString|null|string $find, + ResolvesToNull|ResolvesToString|null|string $replacement, + ): ReplaceAllOperator + { + return new ReplaceAllOperator($input, $find, $replacement); + } + + /** + * Replaces the first instance of a matched string in a given input. + * New in version 4.4. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceOne/ + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $input The string on which you wish to apply the find. Can be any valid expression that resolves to a string or a null. If input refers to a field that is missing, $replaceAll returns null. + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $find The string to search for within the given input. Can be any valid expression that resolves to a string or a null. If find refers to a field that is missing, $replaceAll returns null. + * @param ResolvesToNull|ResolvesToString|non-empty-string|null $replacement The string to use to replace all matched instances of find in input. Can be any valid expression that resolves to a string or a null. + */ + public static function replaceOne( + ResolvesToNull|ResolvesToString|null|string $input, + ResolvesToNull|ResolvesToString|null|string $find, + ResolvesToNull|ResolvesToString|null|string $replacement, + ): ReplaceOneOperator + { + return new ReplaceOneOperator($input, $find, $replacement); + } + + /** + * Returns an array with the elements in reverse order. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/reverseArray/ + * @param BSONArray|PackedArray|ResolvesToArray|array $expression The argument can be any valid expression as long as it resolves to an array. + */ + public static function reverseArray(PackedArray|ResolvesToArray|BSONArray|array $expression): ReverseArrayOperator + { + return new ReverseArrayOperator($expression); + } + + /** + * Rounds a number to to a whole integer or to a specified decimal place. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/round/ + * @param Decimal128|Int64|ResolvesToDecimal|ResolvesToDouble|ResolvesToInt|ResolvesToLong|float|int $number Can be any valid expression that resolves to a number. Specifically, the expression must resolve to an integer, double, decimal, or long. + * $round returns an error if the expression resolves to a non-numeric data type. + * @param Optional|ResolvesToInt|int $place Can be any valid expression that resolves to an integer between -20 and 100, exclusive. + */ + public static function round( + Decimal128|Int64|ResolvesToDecimal|ResolvesToDouble|ResolvesToInt|ResolvesToLong|float|int $number, + Optional|ResolvesToInt|int $place = Optional::Undefined, + ): RoundOperator + { + return new RoundOperator($number, $place); + } + + /** + * Removes whitespace characters, including null, or the specified characters from the end of a string. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/rtrim/ + * @param ResolvesToString|non-empty-string $input The string to trim. The argument can be any valid expression that resolves to a string. + * @param Optional|ResolvesToString|non-empty-string $chars The character(s) to trim from the beginning of the input. + * The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + * If unspecified, $ltrim removes whitespace characters, including the null character. + */ + public static function rtrim( + ResolvesToString|string $input, + Optional|ResolvesToString|string $chars = Optional::Undefined, + ): RtrimOperator + { + return new RtrimOperator($input, $chars); + } + + /** + * Randomly select documents at a given rate. Although the exact number of documents selected varies on each run, the quantity chosen approximates the sample rate expressed as a percentage of the total number of documents. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sampleRate/ + * @param Int64|ResolvesToDouble|float|int $rate The selection process uses a uniform random distribution. The sample rate is a floating point number between 0 and 1, inclusive, which represents the probability that a given document will be selected as it passes through the pipeline. + * For example, a sample rate of 0.33 selects roughly one document in three. + */ + public static function sampleRate(Int64|ResolvesToDouble|float|int $rate): SampleRateOperator + { + return new SampleRateOperator($rate); + } + + /** + * Returns the seconds for a date as a number between 0 and 60 (leap seconds). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/second/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function second( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): SecondOperator + { + return new SecondOperator($date, $timezone); + } + + /** + * Returns a set with elements that appear in the first set but not in the second set; i.e. performs a relative complement of the second set relative to the first. Accepts exactly two argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setDifference/ + * @param BSONArray|PackedArray|ResolvesToArray|array $expression1 The arguments can be any valid expression as long as they each resolve to an array. + * @param BSONArray|PackedArray|ResolvesToArray|array $expression2 The arguments can be any valid expression as long as they each resolve to an array. + */ + public static function setDifference( + PackedArray|ResolvesToArray|BSONArray|array $expression1, + PackedArray|ResolvesToArray|BSONArray|array $expression2, + ): SetDifferenceOperator + { + return new SetDifferenceOperator($expression1, $expression2); + } + + /** + * Returns true if the input sets have the same distinct elements. Accepts two or more argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setEquals/ + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + */ + public static function setEquals(PackedArray|ResolvesToArray|BSONArray|array ...$expression): SetEqualsOperator + { + return new SetEqualsOperator(...$expression); + } + + /** + * Adds, updates, or removes a specified field in a document. You can use $setField to add, update, or remove fields with names that contain periods (.) or start with dollar signs ($). + * New in version 5.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setField/ + * @param ResolvesToString|non-empty-string $field Field in the input object that you want to add, update, or remove. field can be any valid expression that resolves to a string constant. + * @param Document|ResolvesToObject|Serializable|array|stdClass $input Document that contains the field that you want to add or update. input must resolve to an object, missing, null, or undefined. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $value The value that you want to assign to field. value can be any valid expression. + * Set to $$REMOVE to remove field from the input document. + */ + public static function setField( + ResolvesToString|string $field, + Document|Serializable|ResolvesToObject|stdClass|array $input, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $value, + ): SetFieldOperator + { + return new SetFieldOperator($field, $input, $value); + } + + /** + * Returns a set with elements that appear in all of the input sets. Accepts any number of argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setIntersection/ + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + */ + public static function setIntersection( + PackedArray|ResolvesToArray|BSONArray|array ...$expression, + ): SetIntersectionOperator + { + return new SetIntersectionOperator(...$expression); + } + + /** + * Returns true if all elements of the first set appear in the second set, including when the first set equals the second set; i.e. not a strict subset. Accepts exactly two argument expressions. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setIsSubset/ + * @param BSONArray|PackedArray|ResolvesToArray|array $expression1 + * @param BSONArray|PackedArray|ResolvesToArray|array $expression2 + */ + public static function setIsSubset( + PackedArray|ResolvesToArray|BSONArray|array $expression1, + PackedArray|ResolvesToArray|BSONArray|array $expression2, + ): SetIsSubsetOperator + { + return new SetIsSubsetOperator($expression1, $expression2); + } + + /** + * Returns a set with elements that appear in any of the input sets. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setUnion/ + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + */ + public static function setUnion(PackedArray|ResolvesToArray|BSONArray|array ...$expression): SetUnionOperator + { + return new SetUnionOperator(...$expression); + } + + /** + * Returns the sine of a value that is measured in radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sin/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $sin takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + * By default $sin returns values as a double. $sin can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. + */ + public static function sin(Decimal128|Int64|ResolvesToNumber|float|int $expression): SinOperator + { + return new SinOperator($expression); + } + + /** + * Returns the hyperbolic sine of a value that is measured in radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sinh/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $sinh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + * By default $sinh returns values as a double. $sinh can also return values as a 128-bit decimal if the expression resolves to a 128-bit decimal value. + */ + public static function sinh(Decimal128|Int64|ResolvesToNumber|float|int $expression): SinhOperator + { + return new SinhOperator($expression); + } + + /** + * Returns the number of elements in the array. Accepts a single expression as argument. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/size/ + * @param BSONArray|PackedArray|ResolvesToArray|array $expression The argument for $size can be any expression as long as it resolves to an array. + */ + public static function size(PackedArray|ResolvesToArray|BSONArray|array $expression): SizeOperator + { + return new SizeOperator($expression); + } + + /** + * Returns a subset of an array. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/slice/ + * @param BSONArray|PackedArray|ResolvesToArray|array $expression Any valid expression as long as it resolves to an array. + * @param ResolvesToInt|int $n Any valid expression as long as it resolves to an integer. If position is specified, n must resolve to a positive integer. + * If positive, $slice returns up to the first n elements in the array. If the position is specified, $slice returns the first n elements starting from the position. + * If negative, $slice returns up to the last n elements in the array. n cannot resolve to a negative number if is specified. + * @param Optional|ResolvesToInt|int $position Any valid expression as long as it resolves to an integer. + * If positive, $slice determines the starting position from the start of the array. If position is greater than the number of elements, the $slice returns an empty array. + * If negative, $slice determines the starting position from the end of the array. If the absolute value of the is greater than the number of elements, the starting position is the start of the array. + */ + public static function slice( + PackedArray|ResolvesToArray|BSONArray|array $expression, + ResolvesToInt|int $n, + Optional|ResolvesToInt|int $position = Optional::Undefined, + ): SliceOperator + { + return new SliceOperator($expression, $n, $position); + } + + /** + * Sorts the elements of an array. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortArray/ + * @param BSONArray|PackedArray|ResolvesToArray|array $input The array to be sorted. + * The result is null if the expression: is missing, evaluates to null, or evaluates to undefined + * If the expression evaluates to any other non-array value, the document returns an error. + * @param Document|Serializable|array|stdClass $sortBy The document specifies a sort ordering. + */ + public static function sortArray( + PackedArray|ResolvesToArray|BSONArray|array $input, + Document|Serializable|stdClass|array $sortBy, + ): SortArrayOperator + { + return new SortArrayOperator($input, $sortBy); + } + + /** + * Splits a string into substrings based on a delimiter. Returns an array of substrings. If the delimiter is not found within the string, returns an array containing the original string. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/split/ + * @param ResolvesToString|non-empty-string $string The string to be split. string expression can be any valid expression as long as it resolves to a string. + * @param ResolvesToString|non-empty-string $delimiter The delimiter to use when splitting the string expression. delimiter can be any valid expression as long as it resolves to a string. + */ + public static function split(ResolvesToString|string $string, ResolvesToString|string $delimiter): SplitOperator + { + return new SplitOperator($string, $delimiter); + } + + /** + * Calculates the square root. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sqrt/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number The argument can be any valid expression as long as it resolves to a non-negative number. + */ + public static function sqrt(Decimal128|Int64|ResolvesToNumber|float|int $number): SqrtOperator + { + return new SqrtOperator($number); + } + + /** + * Calculates the population standard deviation of the input values. Use if the values encompass the entire population of data you want to represent and do not wish to generalize about a larger population. $stdDevPop ignores non-numeric values. + * If the values represent only a sample of a population of data from which to generalize about the population, use $stdDevSamp instead. + * Changed in version 5.0: Available in the $setWindowFields stage. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevPop/ + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + */ + public static function stdDevPop(Decimal128|Int64|ResolvesToNumber|float|int ...$expression): StdDevPopOperator + { + return new StdDevPopOperator(...$expression); + } + + /** + * Calculates the sample standard deviation of the input values. Use if the values encompass a sample of a population of data from which to generalize about the population. $stdDevSamp ignores non-numeric values. + * If the values represent the entire population of data or you do not wish to generalize about a larger population, use $stdDevPop instead. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/stdDevSamp/ + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + */ + public static function stdDevSamp(Decimal128|Int64|ResolvesToNumber|float|int ...$expression): StdDevSampOperator + { + return new StdDevSampOperator(...$expression); + } + + /** + * Performs case-insensitive string comparison and returns: 0 if two strings are equivalent, 1 if the first string is greater than the second, and -1 if the first string is less than the second. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/strcasecmp/ + * @param ResolvesToString|non-empty-string $expression1 + * @param ResolvesToString|non-empty-string $expression2 + */ + public static function strcasecmp( + ResolvesToString|string $expression1, + ResolvesToString|string $expression2, + ): StrcasecmpOperator + { + return new StrcasecmpOperator($expression1, $expression2); + } + + /** + * Returns the number of UTF-8 encoded bytes in a string. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/strLenBytes/ + * @param ResolvesToString|non-empty-string $expression + */ + public static function strLenBytes(ResolvesToString|string $expression): StrLenBytesOperator + { + return new StrLenBytesOperator($expression); + } + + /** + * Returns the number of UTF-8 code points in a string. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/strLenCP/ + * @param ResolvesToString|non-empty-string $expression + */ + public static function strLenCP(ResolvesToString|string $expression): StrLenCPOperator + { + return new StrLenCPOperator($expression); + } + + /** + * Deprecated. Use $substrBytes or $substrCP. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr/ + * @param ResolvesToString|non-empty-string $string + * @param ResolvesToInt|int $start If start is a negative number, $substr returns an empty string "". + * @param ResolvesToInt|int $length If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. + */ + public static function substr( + ResolvesToString|string $string, + ResolvesToInt|int $start, + ResolvesToInt|int $length, + ): SubstrOperator + { + return new SubstrOperator($string, $start, $length); + } + + /** + * Returns the substring of a string. Starts with the character at the specified UTF-8 byte index (zero-based) in the string and continues for the specified number of bytes. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/substrBytes/ + * @param ResolvesToString|non-empty-string $string + * @param ResolvesToInt|int $start If start is a negative number, $substr returns an empty string "". + * @param ResolvesToInt|int $length If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. + */ + public static function substrBytes( + ResolvesToString|string $string, + ResolvesToInt|int $start, + ResolvesToInt|int $length, + ): SubstrBytesOperator + { + return new SubstrBytesOperator($string, $start, $length); + } + + /** + * Returns the substring of a string. Starts with the character at the specified UTF-8 code point (CP) index (zero-based) in the string and continues for the number of code points specified. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/substrCP/ + * @param ResolvesToString|non-empty-string $string + * @param ResolvesToInt|int $start If start is a negative number, $substr returns an empty string "". + * @param ResolvesToInt|int $length If length is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string. + */ + public static function substrCP( + ResolvesToString|string $string, + ResolvesToInt|int $start, + ResolvesToInt|int $length, + ): SubstrCPOperator + { + return new SubstrCPOperator($string, $start, $length); + } + + /** + * Returns the result of subtracting the second value from the first. If the two values are numbers, return the difference. If the two values are dates, return the difference in milliseconds. If the two values are a date and a number in milliseconds, return the resulting date. Accepts two argument expressions. If the two values are a date and a number, specify the date argument first as it is not meaningful to subtract a date from a number. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/subtract/ + * @param Decimal128|Int64|ResolvesToDate|ResolvesToNumber|UTCDateTime|float|int $expression1 + * @param Decimal128|Int64|ResolvesToDate|ResolvesToNumber|UTCDateTime|float|int $expression2 + */ + public static function subtract( + Decimal128|Int64|UTCDateTime|ResolvesToDate|ResolvesToNumber|float|int $expression1, + Decimal128|Int64|UTCDateTime|ResolvesToDate|ResolvesToNumber|float|int $expression2, + ): SubtractOperator + { + return new SubtractOperator($expression1, $expression2); + } + + /** + * Returns a sum of numerical values. Ignores non-numeric values. + * Changed in version 5.0: Available in the $setWindowFields stage. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum/ + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + */ + public static function sum(Decimal128|Int64|ResolvesToNumber|float|int ...$expression): SumOperator + { + return new SumOperator(...$expression); + } + + /** + * Evaluates a series of case expressions. When it finds an expression which evaluates to true, $switch executes a specified expression and breaks out of the control flow. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/switch/ + * @param BSONArray|PackedArray|array $branches An array of control branch documents. Each branch is a document with the following fields: + * - case Can be any valid expression that resolves to a boolean. If the result is not a boolean, it is coerced to a boolean value. More information about how MongoDB evaluates expressions as either true or false can be found here. + * - then Can be any valid expression. + * The branches array must contain at least one branch document. + * @param Optional|ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $default The path to take if no branch case expression evaluates to true. + * Although optional, if default is unspecified and no branch case evaluates to true, $switch returns an error. + */ + public static function switch( + PackedArray|BSONArray|array $branches, + Optional|Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $default = Optional::Undefined, + ): SwitchOperator + { + return new SwitchOperator($branches, $default); + } + + /** + * Returns the tangent of a value that is measured in radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/tan/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $tan takes any valid expression that resolves to a number. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the result to radians. + * By default $tan returns values as a double. $tan can also return values as a 128-bit decimal as long as the expression resolves to a 128-bit decimal value. + */ + public static function tan(Decimal128|Int64|ResolvesToNumber|float|int $expression): TanOperator + { + return new TanOperator($expression); + } + + /** + * Returns the hyperbolic tangent of a value that is measured in radians. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/tanh/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $expression $tanh takes any valid expression that resolves to a number, measured in radians. If the expression returns a value in degrees, use the $degreesToRadians operator to convert the value to radians. + * By default $tanh returns values as a double. $tanh can also return values as a 128-bit decimal if the expression resolves to a 128-bit decimal value. + */ + public static function tanh(Decimal128|Int64|ResolvesToNumber|float|int $expression): TanhOperator + { + return new TanhOperator($expression); + } + + /** + * Converts value to a boolean. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toBool/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toBool( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToBoolOperator + { + return new ToBoolOperator($expression); + } + + /** + * Converts value to a Date. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDate/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toDate( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToDateOperator + { + return new ToDateOperator($expression); + } + + /** + * Converts value to a Decimal128. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDecimal/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toDecimal( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToDecimalOperator + { + return new ToDecimalOperator($expression); + } + + /** + * Converts value to a double. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toDouble/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toDouble( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToDoubleOperator + { + return new ToDoubleOperator($expression); + } + + /** + * Converts value to an integer. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toInt/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toInt( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToIntOperator + { + return new ToIntOperator($expression); + } + + /** + * Converts value to a long. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toLong/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toLong( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToLongOperator + { + return new ToLongOperator($expression); + } + + /** + * Converts a string to lowercase. Accepts a single argument expression. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toLower/ + * @param ResolvesToString|non-empty-string $expression + */ + public static function toLower(ResolvesToString|string $expression): ToLowerOperator + { + return new ToLowerOperator($expression); + } + + /** + * Converts value to an ObjectId. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toObjectId/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toObjectId( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToObjectIdOperator + { + return new ToObjectIdOperator($expression); + } + + /** + * Converts value to a string. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toString/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function toString( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): ToStringOperator + { + return new ToStringOperator($expression); + } + + /** + * Converts a string to uppercase. Accepts a single argument expression. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/toUpper/ + * @param ResolvesToString|non-empty-string $expression + */ + public static function toUpper(ResolvesToString|string $expression): ToUpperOperator + { + return new ToUpperOperator($expression); + } + + /** + * Removes whitespace or the specified characters from the beginning and end of a string. + * New in version 4.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/trim/ + * @param ResolvesToString|non-empty-string $input The string to trim. The argument can be any valid expression that resolves to a string. + * @param Optional|ResolvesToString|non-empty-string $chars The character(s) to trim from the beginning of the input. + * The argument can be any valid expression that resolves to a string. The $ltrim operator breaks down the string into individual UTF code point to trim from input. + * If unspecified, $ltrim removes whitespace characters, including the null character. + */ + public static function trim( + ResolvesToString|string $input, + Optional|ResolvesToString|string $chars = Optional::Undefined, + ): TrimOperator + { + return new TrimOperator($input, $chars); + } + + /** + * Truncates a number to a whole integer or to a specified decimal place. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/trunc/ + * @param Decimal128|Int64|ResolvesToNumber|float|int $number Can be any valid expression that resolves to a number. Specifically, the expression must resolve to an integer, double, decimal, or long. + * $trunc returns an error if the expression resolves to a non-numeric data type. + * @param Optional|ResolvesToInt|int $place Can be any valid expression that resolves to an integer between -20 and 100, exclusive. e.g. -20 < place < 100. Defaults to 0. + */ + public static function trunc( + Decimal128|Int64|ResolvesToNumber|float|int $number, + Optional|ResolvesToInt|int $place = Optional::Undefined, + ): TruncOperator + { + return new TruncOperator($number, $place); + } + + /** + * Returns the incrementing ordinal from a timestamp as a long. + * New in version 5.1. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsIncrement/ + * @param ResolvesToTimestamp|Timestamp|int $expression + */ + public static function tsIncrement(Timestamp|ResolvesToTimestamp|int $expression): TsIncrementOperator + { + return new TsIncrementOperator($expression); + } + + /** + * Returns the seconds from a timestamp as a long. + * New in version 5.1. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsSecond/ + * @param ResolvesToTimestamp|Timestamp|int $expression + */ + public static function tsSecond(Timestamp|ResolvesToTimestamp|int $expression): TsSecondOperator + { + return new TsSecondOperator($expression); + } + + /** + * Return the BSON data type of the field. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/type/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function type( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): TypeOperator + { + return new TypeOperator($expression); + } + + /** + * You can use $unsetField to remove fields with names that contain periods (.) or that start with dollar signs ($). + * $unsetField is an alias for $setField using $$REMOVE to remove fields. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unsetField/ + * @param ResolvesToString|non-empty-string $field Field in the input object that you want to add, update, or remove. field can be any valid expression that resolves to a string constant. + * @param Document|ResolvesToObject|Serializable|array|stdClass $input Document that contains the field that you want to add or update. input must resolve to an object, missing, null, or undefined. + */ + public static function unsetField( + ResolvesToString|string $field, + Document|Serializable|ResolvesToObject|stdClass|array $input, + ): UnsetFieldOperator + { + return new UnsetFieldOperator($field, $input); + } + + /** + * Returns the week number for a date as a number between 0 (the partial week that precedes the first Sunday of the year) and 53 (leap year). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/week/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function week( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): WeekOperator + { + return new WeekOperator($date, $timezone); + } + + /** + * Returns the year for a date as a number (e.g. 2014). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/year/ + * @param ObjectId|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|Timestamp|UTCDateTime|int $date The date to which the operator is applied. date must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. + * @param Optional|ResolvesToString|non-empty-string $timezone The timezone of the operation result. timezone must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is displayed in UTC. + */ + public static function year( + ObjectId|Timestamp|UTCDateTime|ResolvesToDate|ResolvesToObjectId|ResolvesToTimestamp|int $date, + Optional|ResolvesToString|string $timezone = Optional::Undefined, + ): YearOperator + { + return new YearOperator($date, $timezone); + } + + /** + * Merge two arrays together. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/zip/ + * @param BSONArray|PackedArray|ResolvesToArray|array $inputs An array of expressions that resolve to arrays. The elements of these input arrays combine to form the arrays of the output array. + * If any of the inputs arrays resolves to a value of null or refers to a missing field, $zip returns null. + * If any of the inputs arrays does not resolve to an array or null nor refers to a missing field, $zip returns an error. + * @param bool $useLongestLength A boolean which specifies whether the length of the longest array determines the number of arrays in the output array. + * The default value is false: the shortest array length determines the number of arrays in the output array. + * @param BSONArray|PackedArray|array $defaults An array of default element values to use if the input arrays have different lengths. You must specify useLongestLength: true along with this field, or else $zip will return an error. + * If useLongestLength: true but defaults is empty or not specified, $zip uses null as the default value. + * If specifying a non-empty defaults, you must specify a default for each input array or else $zip will return an error. + */ + public static function zip( + PackedArray|ResolvesToArray|BSONArray|array $inputs, + bool $useLongestLength, + PackedArray|BSONArray|array $defaults, + ): ZipOperator + { + return new ZipOperator($inputs, $useLongestLength, $defaults); + } +} diff --git a/src/Builder/Expression/FieldName.php b/src/Builder/Expression/FieldName.php deleted file mode 100644 index d76dd6aa0..000000000 --- a/src/Builder/Expression/FieldName.php +++ /dev/null @@ -1,17 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Expression/FieldPath.php b/src/Builder/Expression/FieldPath.php index 15f6192d2..4d42f9706 100644 --- a/src/Builder/Expression/FieldPath.php +++ b/src/Builder/Expression/FieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class FieldPath implements ExpressionInterface +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class FieldPath implements FieldPathInterface, ResolvesToAny { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/FilterOperator.php b/src/Builder/Expression/FilterOperator.php new file mode 100644 index 000000000..f83cab5dd --- /dev/null +++ b/src/Builder/Expression/FilterOperator.php @@ -0,0 +1,65 @@ +input = $input; + $this->cond = $cond; + $this->as = $as; + $this->limit = $limit; + } +} diff --git a/src/Builder/Expression/FirstNOperator.php b/src/Builder/Expression/FirstNOperator.php new file mode 100644 index 000000000..dffaf544f --- /dev/null +++ b/src/Builder/Expression/FirstNOperator.php @@ -0,0 +1,48 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Expression/FirstOperator.php b/src/Builder/Expression/FirstOperator.php new file mode 100644 index 000000000..a995398b4 --- /dev/null +++ b/src/Builder/Expression/FirstOperator.php @@ -0,0 +1,48 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/FloatFieldPath.php b/src/Builder/Expression/FloatFieldPath.php deleted file mode 100644 index d58f5ce06..000000000 --- a/src/Builder/Expression/FloatFieldPath.php +++ /dev/null @@ -1,17 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Expression/FloorOperator.php b/src/Builder/Expression/FloorOperator.php new file mode 100644 index 000000000..670e22eb4 --- /dev/null +++ b/src/Builder/Expression/FloorOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/FullDocument.php b/src/Builder/Expression/FullDocument.php new file mode 100644 index 000000000..1dcf033ca --- /dev/null +++ b/src/Builder/Expression/FullDocument.php @@ -0,0 +1,15 @@ +body = $body; + if (is_array($args) && ! array_is_list($args)) { + throw new InvalidArgumentException('Expected $args argument to be a list, got an associative array.'); + } + + $this->args = $args; + $this->lang = $lang; + } +} diff --git a/src/Builder/Expression/GetFieldOperator.php b/src/Builder/Expression/GetFieldOperator.php new file mode 100644 index 000000000..6c54ea66e --- /dev/null +++ b/src/Builder/Expression/GetFieldOperator.php @@ -0,0 +1,51 @@ +field = $field; + $this->input = $input; + } +} diff --git a/src/Builder/Expression/GtOperator.php b/src/Builder/Expression/GtOperator.php new file mode 100644 index 000000000..cb1f501fa --- /dev/null +++ b/src/Builder/Expression/GtOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/GteOperator.php b/src/Builder/Expression/GteOperator.php new file mode 100644 index 000000000..e0d917a8f --- /dev/null +++ b/src/Builder/Expression/GteOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/HourOperator.php b/src/Builder/Expression/HourOperator.php new file mode 100644 index 000000000..b617d1b7f --- /dev/null +++ b/src/Builder/Expression/HourOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/IfNullOperator.php b/src/Builder/Expression/IfNullOperator.php new file mode 100644 index 000000000..2ed100821 --- /dev/null +++ b/src/Builder/Expression/IfNullOperator.php @@ -0,0 +1,44 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/InOperator.php b/src/Builder/Expression/InOperator.php new file mode 100644 index 000000000..f0c96bc65 --- /dev/null +++ b/src/Builder/Expression/InOperator.php @@ -0,0 +1,51 @@ +expression = $expression; + if (is_array($array) && ! array_is_list($array)) { + throw new InvalidArgumentException('Expected $array argument to be a list, got an associative array.'); + } + + $this->array = $array; + } +} diff --git a/src/Builder/Expression/IndexOfArrayOperator.php b/src/Builder/Expression/IndexOfArrayOperator.php new file mode 100644 index 000000000..7b6793314 --- /dev/null +++ b/src/Builder/Expression/IndexOfArrayOperator.php @@ -0,0 +1,68 @@ + index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public Optional|ResolvesToInt|int $end; + + /** + * @param ResolvesToString|non-empty-string $array Can be any valid expression as long as it resolves to an array. + * If the array expression resolves to a value of null or refers to a field that is missing, $indexOfArray returns null. + * If the array expression does not resolve to an array or null nor refers to a missing field, $indexOfArray returns an error. + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $search + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public function __construct( + ResolvesToString|string $array, + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $search, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ) { + $this->array = $array; + $this->search = $search; + $this->start = $start; + $this->end = $end; + } +} diff --git a/src/Builder/Expression/IndexOfBytesOperator.php b/src/Builder/Expression/IndexOfBytesOperator.php new file mode 100644 index 000000000..01b1d8cdd --- /dev/null +++ b/src/Builder/Expression/IndexOfBytesOperator.php @@ -0,0 +1,65 @@ + index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public Optional|ResolvesToInt|int $end; + + /** + * @param ResolvesToString|non-empty-string $string Can be any valid expression as long as it resolves to a string. + * If the string expression resolves to a value of null or refers to a field that is missing, $indexOfBytes returns null. + * If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfBytes returns an error. + * @param ResolvesToString|non-empty-string $substring Can be any valid expression as long as it resolves to a string. + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public function __construct( + ResolvesToString|string $string, + ResolvesToString|string $substring, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ) { + $this->string = $string; + $this->substring = $substring; + $this->start = $start; + $this->end = $end; + } +} diff --git a/src/Builder/Expression/IndexOfCPOperator.php b/src/Builder/Expression/IndexOfCPOperator.php new file mode 100644 index 000000000..3fb9d6305 --- /dev/null +++ b/src/Builder/Expression/IndexOfCPOperator.php @@ -0,0 +1,65 @@ + index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public Optional|ResolvesToInt|int $end; + + /** + * @param ResolvesToString|non-empty-string $string Can be any valid expression as long as it resolves to a string. + * If the string expression resolves to a value of null or refers to a field that is missing, $indexOfCP returns null. + * If the string expression does not resolve to a string or null nor refers to a missing field, $indexOfCP returns an error. + * @param ResolvesToString|non-empty-string $substring Can be any valid expression as long as it resolves to a string. + * @param Optional|ResolvesToInt|int $start An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. + * If unspecified, the starting index position for the search is the beginning of the string. + * @param Optional|ResolvesToInt|int $end An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a index value, you should also specify a index value; otherwise, $indexOfArray uses the value as the index value instead of the value. + * If unspecified, the ending index position for the search is the end of the string. + */ + public function __construct( + ResolvesToString|string $string, + ResolvesToString|string $substring, + Optional|ResolvesToInt|int $start = Optional::Undefined, + Optional|ResolvesToInt|int $end = Optional::Undefined, + ) { + $this->string = $string; + $this->substring = $substring; + $this->start = $start; + $this->end = $end; + } +} diff --git a/src/Builder/Expression/IntFieldPath.php b/src/Builder/Expression/IntFieldPath.php index f2242ffb2..e87d294bd 100644 --- a/src/Builder/Expression/IntFieldPath.php +++ b/src/Builder/Expression/IntFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class IntFieldPath extends FieldPath implements ResolvesToInt +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class IntFieldPath implements FieldPathInterface, ResolvesToInt { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/IntegralOperator.php b/src/Builder/Expression/IntegralOperator.php new file mode 100644 index 000000000..259b489fa --- /dev/null +++ b/src/Builder/Expression/IntegralOperator.php @@ -0,0 +1,47 @@ +input = $input; + $this->unit = $unit; + } +} diff --git a/src/Builder/Expression/IsArrayOperator.php b/src/Builder/Expression/IsArrayOperator.php new file mode 100644 index 000000000..790f55345 --- /dev/null +++ b/src/Builder/Expression/IsArrayOperator.php @@ -0,0 +1,44 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/IsNumberOperator.php b/src/Builder/Expression/IsNumberOperator.php new file mode 100644 index 000000000..6020eeb9a --- /dev/null +++ b/src/Builder/Expression/IsNumberOperator.php @@ -0,0 +1,46 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/IsoDayOfWeekOperator.php b/src/Builder/Expression/IsoDayOfWeekOperator.php new file mode 100644 index 000000000..fb3a1f21c --- /dev/null +++ b/src/Builder/Expression/IsoDayOfWeekOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/IsoWeekOperator.php b/src/Builder/Expression/IsoWeekOperator.php new file mode 100644 index 000000000..c8e4650c2 --- /dev/null +++ b/src/Builder/Expression/IsoWeekOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/IsoWeekYearOperator.php b/src/Builder/Expression/IsoWeekYearOperator.php new file mode 100644 index 000000000..33676b436 --- /dev/null +++ b/src/Builder/Expression/IsoWeekYearOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/JavascriptFieldPath.php b/src/Builder/Expression/JavascriptFieldPath.php new file mode 100644 index 000000000..8708191b1 --- /dev/null +++ b/src/Builder/Expression/JavascriptFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/LastNOperator.php b/src/Builder/Expression/LastNOperator.php new file mode 100644 index 000000000..e4eeb4a75 --- /dev/null +++ b/src/Builder/Expression/LastNOperator.php @@ -0,0 +1,47 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Expression/LastOperator.php b/src/Builder/Expression/LastOperator.php new file mode 100644 index 000000000..2f8191750 --- /dev/null +++ b/src/Builder/Expression/LastOperator.php @@ -0,0 +1,48 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/LetOperator.php b/src/Builder/Expression/LetOperator.php new file mode 100644 index 000000000..587011cf4 --- /dev/null +++ b/src/Builder/Expression/LetOperator.php @@ -0,0 +1,48 @@ +vars = $vars; + $this->in = $in; + } +} diff --git a/src/Builder/Expression/LinearFillOperator.php b/src/Builder/Expression/LinearFillOperator.php new file mode 100644 index 000000000..d10407412 --- /dev/null +++ b/src/Builder/Expression/LinearFillOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/Literal.php b/src/Builder/Expression/Literal.php deleted file mode 100644 index 0222123ba..000000000 --- a/src/Builder/Expression/Literal.php +++ /dev/null @@ -1,17 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Expression/LiteralOperator.php b/src/Builder/Expression/LiteralOperator.php new file mode 100644 index 000000000..78cce28c2 --- /dev/null +++ b/src/Builder/Expression/LiteralOperator.php @@ -0,0 +1,33 @@ +value = $value; + } +} diff --git a/src/Builder/Expression/LnOperator.php b/src/Builder/Expression/LnOperator.php new file mode 100644 index 000000000..648cf4bf5 --- /dev/null +++ b/src/Builder/Expression/LnOperator.php @@ -0,0 +1,34 @@ +, Math.E ] expression, where Math.E is a JavaScript representation for Euler's number e. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ln/ + */ +readonly class LnOperator implements ResolvesToDouble +{ + public const NAME = '$ln'; + public const ENCODE = Encode::Single; + + /** @param Decimal128|Int64|ResolvesToNumber|float|int $number Any valid expression as long as it resolves to a non-negative number. For more information on expressions, see Expressions. */ + public Decimal128|Int64|ResolvesToNumber|float|int $number; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int $number Any valid expression as long as it resolves to a non-negative number. For more information on expressions, see Expressions. + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int $number) + { + $this->number = $number; + } +} diff --git a/src/Builder/Expression/LocfOperator.php b/src/Builder/Expression/LocfOperator.php new file mode 100644 index 000000000..8e1078a8c --- /dev/null +++ b/src/Builder/Expression/LocfOperator.php @@ -0,0 +1,36 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/Log10Operator.php b/src/Builder/Expression/Log10Operator.php new file mode 100644 index 000000000..f8e2d427e --- /dev/null +++ b/src/Builder/Expression/Log10Operator.php @@ -0,0 +1,33 @@ +number = $number; + } +} diff --git a/src/Builder/Expression/LogOperator.php b/src/Builder/Expression/LogOperator.php new file mode 100644 index 000000000..7e8c98bab --- /dev/null +++ b/src/Builder/Expression/LogOperator.php @@ -0,0 +1,40 @@ +number = $number; + $this->base = $base; + } +} diff --git a/src/Builder/Expression/LongFieldPath.php b/src/Builder/Expression/LongFieldPath.php new file mode 100644 index 000000000..7079394d5 --- /dev/null +++ b/src/Builder/Expression/LongFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/LtOperator.php b/src/Builder/Expression/LtOperator.php new file mode 100644 index 000000000..1dc510cd0 --- /dev/null +++ b/src/Builder/Expression/LtOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/LteOperator.php b/src/Builder/Expression/LteOperator.php new file mode 100644 index 000000000..d568a894c --- /dev/null +++ b/src/Builder/Expression/LteOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/LtrimOperator.php b/src/Builder/Expression/LtrimOperator.php new file mode 100644 index 000000000..ffc8f8395 --- /dev/null +++ b/src/Builder/Expression/LtrimOperator.php @@ -0,0 +1,46 @@ +input = $input; + $this->chars = $chars; + } +} diff --git a/src/Builder/Expression/MapOperator.php b/src/Builder/Expression/MapOperator.php new file mode 100644 index 000000000..ed6db35b5 --- /dev/null +++ b/src/Builder/Expression/MapOperator.php @@ -0,0 +1,58 @@ +input = $input; + $this->in = $in; + $this->as = $as; + } +} diff --git a/src/Builder/Expression/MaxNOperator.php b/src/Builder/Expression/MaxNOperator.php new file mode 100644 index 000000000..3b2e37e9b --- /dev/null +++ b/src/Builder/Expression/MaxNOperator.php @@ -0,0 +1,46 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Expression/MaxOperator.php b/src/Builder/Expression/MaxOperator.php new file mode 100644 index 000000000..b0dcd988e --- /dev/null +++ b/src/Builder/Expression/MaxOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/MedianOperator.php b/src/Builder/Expression/MedianOperator.php new file mode 100644 index 000000000..c6713305e --- /dev/null +++ b/src/Builder/Expression/MedianOperator.php @@ -0,0 +1,43 @@ +input = $input; + $this->method = $method; + } +} diff --git a/src/Builder/Expression/MergeObjectsOperator.php b/src/Builder/Expression/MergeObjectsOperator.php new file mode 100644 index 000000000..364b5020c --- /dev/null +++ b/src/Builder/Expression/MergeObjectsOperator.php @@ -0,0 +1,45 @@ + ...$document Any valid expression that resolves to a document. */ + public array $document; + + /** + * @param Document|ResolvesToObject|Serializable|array|stdClass ...$document Any valid expression that resolves to a document. + * @no-named-arguments + */ + public function __construct(Document|Serializable|ResolvesToObject|stdClass|array ...$document) + { + if (\count($document) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $document, got %d.', 1, \count($document))); + } + if (! array_is_list($document)) { + throw new InvalidArgumentException('Expected $document arguments to be a list (array), named arguments are not supported'); + } + $this->document = $document; + } +} diff --git a/src/Builder/Expression/MetaOperator.php b/src/Builder/Expression/MetaOperator.php new file mode 100644 index 000000000..5929c4f7a --- /dev/null +++ b/src/Builder/Expression/MetaOperator.php @@ -0,0 +1,31 @@ +keyword = $keyword; + } +} diff --git a/src/Builder/Expression/MillisecondOperator.php b/src/Builder/Expression/MillisecondOperator.php new file mode 100644 index 000000000..98b80e60c --- /dev/null +++ b/src/Builder/Expression/MillisecondOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/MinNOperator.php b/src/Builder/Expression/MinNOperator.php new file mode 100644 index 000000000..56cdd0cc4 --- /dev/null +++ b/src/Builder/Expression/MinNOperator.php @@ -0,0 +1,46 @@ +input = $input; + $this->n = $n; + } +} diff --git a/src/Builder/Expression/MinOperator.php b/src/Builder/Expression/MinOperator.php new file mode 100644 index 000000000..f883a86af --- /dev/null +++ b/src/Builder/Expression/MinOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/MinuteOperator.php b/src/Builder/Expression/MinuteOperator.php new file mode 100644 index 000000000..7bbf7d482 --- /dev/null +++ b/src/Builder/Expression/MinuteOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/ModOperator.php b/src/Builder/Expression/ModOperator.php new file mode 100644 index 000000000..807f520cf --- /dev/null +++ b/src/Builder/Expression/ModOperator.php @@ -0,0 +1,40 @@ +dividend = $dividend; + $this->divisor = $divisor; + } +} diff --git a/src/Builder/Expression/MonthOperator.php b/src/Builder/Expression/MonthOperator.php new file mode 100644 index 000000000..e2517869d --- /dev/null +++ b/src/Builder/Expression/MonthOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/MultiplyOperator.php b/src/Builder/Expression/MultiplyOperator.php new file mode 100644 index 000000000..ab4626566 --- /dev/null +++ b/src/Builder/Expression/MultiplyOperator.php @@ -0,0 +1,47 @@ + ...$expression The arguments can be any valid expression as long as they resolve to numbers. + * Starting in MongoDB 6.1 you can optimize the $multiply operation. To improve performance, group references at the end of the argument list. + */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression The arguments can be any valid expression as long as they resolve to numbers. + * Starting in MongoDB 6.1 you can optimize the $multiply operation. To improve performance, group references at the end of the argument list. + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/NeOperator.php b/src/Builder/Expression/NeOperator.php new file mode 100644 index 000000000..e85b24085 --- /dev/null +++ b/src/Builder/Expression/NeOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/NotOperator.php b/src/Builder/Expression/NotOperator.php new file mode 100644 index 000000000..7444f6e76 --- /dev/null +++ b/src/Builder/Expression/NotOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/NullFieldPath.php b/src/Builder/Expression/NullFieldPath.php index 05dc835c9..eee866779 100644 --- a/src/Builder/Expression/NullFieldPath.php +++ b/src/Builder/Expression/NullFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class NullFieldPath extends FieldPath implements ResolvesToNull +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class NullFieldPath implements FieldPathInterface, ResolvesToNull { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/NumberFieldPath.php b/src/Builder/Expression/NumberFieldPath.php index 98177457c..bd48a8a95 100644 --- a/src/Builder/Expression/NumberFieldPath.php +++ b/src/Builder/Expression/NumberFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class NumberFieldPath extends FieldPath implements ResolvesToNumber +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class NumberFieldPath implements FieldPathInterface, ResolvesToNumber { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/ObjectFieldPath.php b/src/Builder/Expression/ObjectFieldPath.php index 70f69c134..50da0970c 100644 --- a/src/Builder/Expression/ObjectFieldPath.php +++ b/src/Builder/Expression/ObjectFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class ObjectFieldPath extends FieldPath implements ResolvesToObject +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class ObjectFieldPath implements FieldPathInterface, ResolvesToObject { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/ObjectIdFieldPath.php b/src/Builder/Expression/ObjectIdFieldPath.php new file mode 100644 index 000000000..0ea7b4d5e --- /dev/null +++ b/src/Builder/Expression/ObjectIdFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/ObjectToArrayOperator.php b/src/Builder/Expression/ObjectToArrayOperator.php new file mode 100644 index 000000000..0557bdba3 --- /dev/null +++ b/src/Builder/Expression/ObjectToArrayOperator.php @@ -0,0 +1,34 @@ +object = $object; + } +} diff --git a/src/Builder/Expression/OrOperator.php b/src/Builder/Expression/OrOperator.php new file mode 100644 index 000000000..0f6d0ac03 --- /dev/null +++ b/src/Builder/Expression/OrOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param ExpressionInterface|ResolvesToBool|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression + * @no-named-arguments + */ + public function __construct( + Type|ResolvesToBool|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression, + ) { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/PercentileOperator.php b/src/Builder/Expression/PercentileOperator.php new file mode 100644 index 000000000..070ff8f1e --- /dev/null +++ b/src/Builder/Expression/PercentileOperator.php @@ -0,0 +1,68 @@ +input = $input; + if (is_array($p) && ! array_is_list($p)) { + throw new InvalidArgumentException('Expected $p argument to be a list, got an associative array.'); + } + + $this->p = $p; + $this->method = $method; + } +} diff --git a/src/Builder/Expression/PowOperator.php b/src/Builder/Expression/PowOperator.php new file mode 100644 index 000000000..a4fb1266b --- /dev/null +++ b/src/Builder/Expression/PowOperator.php @@ -0,0 +1,40 @@ +number = $number; + $this->exponent = $exponent; + } +} diff --git a/src/Builder/Expression/PushOperator.php b/src/Builder/Expression/PushOperator.php new file mode 100644 index 000000000..d74b8d102 --- /dev/null +++ b/src/Builder/Expression/PushOperator.php @@ -0,0 +1,48 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/RadiansToDegreesOperator.php b/src/Builder/Expression/RadiansToDegreesOperator.php new file mode 100644 index 000000000..d709fd913 --- /dev/null +++ b/src/Builder/Expression/RadiansToDegreesOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/RandOperator.php b/src/Builder/Expression/RandOperator.php new file mode 100644 index 000000000..8ec9e26a5 --- /dev/null +++ b/src/Builder/Expression/RandOperator.php @@ -0,0 +1,24 @@ +start = $start; + $this->end = $end; + $this->step = $step; + } +} diff --git a/src/Builder/Expression/RankOperator.php b/src/Builder/Expression/RankOperator.php new file mode 100644 index 000000000..fc06f6cdc --- /dev/null +++ b/src/Builder/Expression/RankOperator.php @@ -0,0 +1,25 @@ +input = $input; + $this->initialValue = $initialValue; + $this->in = $in; + } +} diff --git a/src/Builder/Expression/RegexFieldPath.php b/src/Builder/Expression/RegexFieldPath.php new file mode 100644 index 000000000..273f1292d --- /dev/null +++ b/src/Builder/Expression/RegexFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/RegexFindAllOperator.php b/src/Builder/Expression/RegexFindAllOperator.php new file mode 100644 index 000000000..d50875083 --- /dev/null +++ b/src/Builder/Expression/RegexFindAllOperator.php @@ -0,0 +1,47 @@ +/. When using the regex //, you can also specify the regex options i and m (but not the s or x options) */ + public Regex|ResolvesToString|string $regex; + + /** @param Optional|non-empty-string $options */ + public Optional|string $options; + + /** + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public function __construct( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ) { + $this->input = $input; + $this->regex = $regex; + $this->options = $options; + } +} diff --git a/src/Builder/Expression/RegexFindOperator.php b/src/Builder/Expression/RegexFindOperator.php new file mode 100644 index 000000000..4319fcaff --- /dev/null +++ b/src/Builder/Expression/RegexFindOperator.php @@ -0,0 +1,47 @@ +/. When using the regex //, you can also specify the regex options i and m (but not the s or x options) */ + public Regex|ResolvesToString|string $regex; + + /** @param Optional|non-empty-string $options */ + public Optional|string $options; + + /** + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public function __construct( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ) { + $this->input = $input; + $this->regex = $regex; + $this->options = $options; + } +} diff --git a/src/Builder/Expression/RegexMatchOperator.php b/src/Builder/Expression/RegexMatchOperator.php new file mode 100644 index 000000000..136e57b3e --- /dev/null +++ b/src/Builder/Expression/RegexMatchOperator.php @@ -0,0 +1,47 @@ +/. When using the regex //, you can also specify the regex options i and m (but not the s or x options) */ + public Regex|ResolvesToString|string $regex; + + /** @param Optional|non-empty-string $options */ + public Optional|string $options; + + /** + * @param ResolvesToString|non-empty-string $input The string on which you wish to apply the regex pattern. Can be a string or any valid expression that resolves to a string. + * @param Regex|ResolvesToString|non-empty-string $regex The regex pattern to apply. Can be any valid expression that resolves to either a string or regex pattern //. When using the regex //, you can also specify the regex options i and m (but not the s or x options) + * @param Optional|non-empty-string $options + */ + public function __construct( + ResolvesToString|string $input, + Regex|ResolvesToString|string $regex, + Optional|string $options = Optional::Undefined, + ) { + $this->input = $input; + $this->regex = $regex; + $this->options = $options; + } +} diff --git a/src/Builder/Expression/ReplaceAllOperator.php b/src/Builder/Expression/ReplaceAllOperator.php new file mode 100644 index 000000000..71925219f --- /dev/null +++ b/src/Builder/Expression/ReplaceAllOperator.php @@ -0,0 +1,46 @@ +input = $input; + $this->find = $find; + $this->replacement = $replacement; + } +} diff --git a/src/Builder/Expression/ReplaceOneOperator.php b/src/Builder/Expression/ReplaceOneOperator.php new file mode 100644 index 000000000..9e085d4dc --- /dev/null +++ b/src/Builder/Expression/ReplaceOneOperator.php @@ -0,0 +1,45 @@ +input = $input; + $this->find = $find; + $this->replacement = $replacement; + } +} diff --git a/src/Builder/Expression/ResolvesToAny.php b/src/Builder/Expression/ResolvesToAny.php new file mode 100644 index 000000000..1f65dac7e --- /dev/null +++ b/src/Builder/Expression/ResolvesToAny.php @@ -0,0 +1,11 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/RoundOperator.php b/src/Builder/Expression/RoundOperator.php new file mode 100644 index 000000000..47650a5f3 --- /dev/null +++ b/src/Builder/Expression/RoundOperator.php @@ -0,0 +1,45 @@ +number = $number; + $this->place = $place; + } +} diff --git a/src/Builder/Expression/RtrimOperator.php b/src/Builder/Expression/RtrimOperator.php new file mode 100644 index 000000000..353b12402 --- /dev/null +++ b/src/Builder/Expression/RtrimOperator.php @@ -0,0 +1,45 @@ +input = $input; + $this->chars = $chars; + } +} diff --git a/src/Builder/Expression/SampleRateOperator.php b/src/Builder/Expression/SampleRateOperator.php new file mode 100644 index 000000000..6703e2142 --- /dev/null +++ b/src/Builder/Expression/SampleRateOperator.php @@ -0,0 +1,36 @@ +rate = $rate; + } +} diff --git a/src/Builder/Expression/SecondOperator.php b/src/Builder/Expression/SecondOperator.php new file mode 100644 index 000000000..0199e4556 --- /dev/null +++ b/src/Builder/Expression/SecondOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/SetDifferenceOperator.php b/src/Builder/Expression/SetDifferenceOperator.php new file mode 100644 index 000000000..2861a3bb5 --- /dev/null +++ b/src/Builder/Expression/SetDifferenceOperator.php @@ -0,0 +1,52 @@ +expression1 = $expression1; + if (is_array($expression2) && ! array_is_list($expression2)) { + throw new InvalidArgumentException('Expected $expression2 argument to be a list, got an associative array.'); + } + + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/SetEqualsOperator.php b/src/Builder/Expression/SetEqualsOperator.php new file mode 100644 index 000000000..3afb4e052 --- /dev/null +++ b/src/Builder/Expression/SetEqualsOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + * @no-named-arguments + */ + public function __construct(PackedArray|ResolvesToArray|BSONArray|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/SetFieldOperator.php b/src/Builder/Expression/SetFieldOperator.php new file mode 100644 index 000000000..68b4e53ff --- /dev/null +++ b/src/Builder/Expression/SetFieldOperator.php @@ -0,0 +1,54 @@ +field = $field; + $this->input = $input; + $this->value = $value; + } +} diff --git a/src/Builder/Expression/SetIntersectionOperator.php b/src/Builder/Expression/SetIntersectionOperator.php new file mode 100644 index 000000000..01a8d43ae --- /dev/null +++ b/src/Builder/Expression/SetIntersectionOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + * @no-named-arguments + */ + public function __construct(PackedArray|ResolvesToArray|BSONArray|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/SetIsSubsetOperator.php b/src/Builder/Expression/SetIsSubsetOperator.php new file mode 100644 index 000000000..c120def28 --- /dev/null +++ b/src/Builder/Expression/SetIsSubsetOperator.php @@ -0,0 +1,52 @@ +expression1 = $expression1; + if (is_array($expression2) && ! array_is_list($expression2)) { + throw new InvalidArgumentException('Expected $expression2 argument to be a list, got an associative array.'); + } + + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/SetUnionOperator.php b/src/Builder/Expression/SetUnionOperator.php new file mode 100644 index 000000000..6ca53cb7b --- /dev/null +++ b/src/Builder/Expression/SetUnionOperator.php @@ -0,0 +1,43 @@ + ...$expression */ + public array $expression; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array ...$expression + * @no-named-arguments + */ + public function __construct(PackedArray|ResolvesToArray|BSONArray|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/ShiftOperator.php b/src/Builder/Expression/ShiftOperator.php new file mode 100644 index 000000000..4eb1d5549 --- /dev/null +++ b/src/Builder/Expression/ShiftOperator.php @@ -0,0 +1,75 @@ +output = $output; + $this->by = $by; + $this->default = $default; + } +} diff --git a/src/Builder/Expression/SinOperator.php b/src/Builder/Expression/SinOperator.php new file mode 100644 index 000000000..4148ae77e --- /dev/null +++ b/src/Builder/Expression/SinOperator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/SinhOperator.php b/src/Builder/Expression/SinhOperator.php new file mode 100644 index 000000000..ce01b3a6d --- /dev/null +++ b/src/Builder/Expression/SinhOperator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/SizeOperator.php b/src/Builder/Expression/SizeOperator.php new file mode 100644 index 000000000..947afc220 --- /dev/null +++ b/src/Builder/Expression/SizeOperator.php @@ -0,0 +1,41 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/SliceOperator.php b/src/Builder/Expression/SliceOperator.php new file mode 100644 index 000000000..05886e862 --- /dev/null +++ b/src/Builder/Expression/SliceOperator.php @@ -0,0 +1,68 @@ + is specified. + */ + public ResolvesToInt|int $n; + + /** + * @param Optional|ResolvesToInt|int $position Any valid expression as long as it resolves to an integer. + * If positive, $slice determines the starting position from the start of the array. If position is greater than the number of elements, the $slice returns an empty array. + * If negative, $slice determines the starting position from the end of the array. If the absolute value of the is greater than the number of elements, the starting position is the start of the array. + */ + public Optional|ResolvesToInt|int $position; + + /** + * @param BSONArray|PackedArray|ResolvesToArray|array $expression Any valid expression as long as it resolves to an array. + * @param ResolvesToInt|int $n Any valid expression as long as it resolves to an integer. If position is specified, n must resolve to a positive integer. + * If positive, $slice returns up to the first n elements in the array. If the position is specified, $slice returns the first n elements starting from the position. + * If negative, $slice returns up to the last n elements in the array. n cannot resolve to a negative number if is specified. + * @param Optional|ResolvesToInt|int $position Any valid expression as long as it resolves to an integer. + * If positive, $slice determines the starting position from the start of the array. If position is greater than the number of elements, the $slice returns an empty array. + * If negative, $slice determines the starting position from the end of the array. If the absolute value of the is greater than the number of elements, the starting position is the start of the array. + */ + public function __construct( + PackedArray|ResolvesToArray|BSONArray|array $expression, + ResolvesToInt|int $n, + Optional|ResolvesToInt|int $position = Optional::Undefined, + ) { + if (is_array($expression) && ! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression argument to be a list, got an associative array.'); + } + + $this->expression = $expression; + $this->n = $n; + $this->position = $position; + } +} diff --git a/src/Builder/Expression/SortArrayOperator.php b/src/Builder/Expression/SortArrayOperator.php new file mode 100644 index 000000000..8da79d1e5 --- /dev/null +++ b/src/Builder/Expression/SortArrayOperator.php @@ -0,0 +1,57 @@ +input = $input; + $this->sortBy = $sortBy; + } +} diff --git a/src/Builder/Expression/SplitOperator.php b/src/Builder/Expression/SplitOperator.php new file mode 100644 index 000000000..1462e79c7 --- /dev/null +++ b/src/Builder/Expression/SplitOperator.php @@ -0,0 +1,36 @@ +string = $string; + $this->delimiter = $delimiter; + } +} diff --git a/src/Builder/Expression/SqrtOperator.php b/src/Builder/Expression/SqrtOperator.php new file mode 100644 index 000000000..409df2550 --- /dev/null +++ b/src/Builder/Expression/SqrtOperator.php @@ -0,0 +1,33 @@ +number = $number; + } +} diff --git a/src/Builder/Expression/StdDevPopOperator.php b/src/Builder/Expression/StdDevPopOperator.php new file mode 100644 index 000000000..4913b425d --- /dev/null +++ b/src/Builder/Expression/StdDevPopOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/StdDevSampOperator.php b/src/Builder/Expression/StdDevSampOperator.php new file mode 100644 index 000000000..355c333e5 --- /dev/null +++ b/src/Builder/Expression/StdDevSampOperator.php @@ -0,0 +1,44 @@ + ...$expression */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/StrLenBytesOperator.php b/src/Builder/Expression/StrLenBytesOperator.php new file mode 100644 index 000000000..7b046f82f --- /dev/null +++ b/src/Builder/Expression/StrLenBytesOperator.php @@ -0,0 +1,31 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/StrLenCPOperator.php b/src/Builder/Expression/StrLenCPOperator.php new file mode 100644 index 000000000..85a402440 --- /dev/null +++ b/src/Builder/Expression/StrLenCPOperator.php @@ -0,0 +1,31 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/StrcasecmpOperator.php b/src/Builder/Expression/StrcasecmpOperator.php new file mode 100644 index 000000000..91cd66320 --- /dev/null +++ b/src/Builder/Expression/StrcasecmpOperator.php @@ -0,0 +1,36 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/StringFieldPath.php b/src/Builder/Expression/StringFieldPath.php index c667f3065..5eea2dd92 100644 --- a/src/Builder/Expression/StringFieldPath.php +++ b/src/Builder/Expression/StringFieldPath.php @@ -6,12 +6,14 @@ namespace MongoDB\Builder\Expression; -class StringFieldPath extends FieldPath implements ResolvesToString +use MongoDB\Builder\Type\FieldPathInterface; + +readonly class StringFieldPath implements FieldPathInterface, ResolvesToString { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/SubstrBytesOperator.php b/src/Builder/Expression/SubstrBytesOperator.php new file mode 100644 index 000000000..b9581d529 --- /dev/null +++ b/src/Builder/Expression/SubstrBytesOperator.php @@ -0,0 +1,41 @@ +string = $string; + $this->start = $start; + $this->length = $length; + } +} diff --git a/src/Builder/Expression/SubstrCPOperator.php b/src/Builder/Expression/SubstrCPOperator.php new file mode 100644 index 000000000..15957d79b --- /dev/null +++ b/src/Builder/Expression/SubstrCPOperator.php @@ -0,0 +1,41 @@ +string = $string; + $this->start = $start; + $this->length = $length; + } +} diff --git a/src/Builder/Expression/SubstrOperator.php b/src/Builder/Expression/SubstrOperator.php new file mode 100644 index 000000000..d7b1d841d --- /dev/null +++ b/src/Builder/Expression/SubstrOperator.php @@ -0,0 +1,41 @@ +string = $string; + $this->start = $start; + $this->length = $length; + } +} diff --git a/src/Builder/Expression/SubtractOperator.php b/src/Builder/Expression/SubtractOperator.php new file mode 100644 index 000000000..3e8374a06 --- /dev/null +++ b/src/Builder/Expression/SubtractOperator.php @@ -0,0 +1,41 @@ +expression1 = $expression1; + $this->expression2 = $expression2; + } +} diff --git a/src/Builder/Expression/SumOperator.php b/src/Builder/Expression/SumOperator.php new file mode 100644 index 000000000..b4520a580 --- /dev/null +++ b/src/Builder/Expression/SumOperator.php @@ -0,0 +1,44 @@ + ...$expression */ + public array $expression; + + /** + * @param Decimal128|Int64|ResolvesToNumber|float|int ...$expression + * @no-named-arguments + */ + public function __construct(Decimal128|Int64|ResolvesToNumber|float|int ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Expression/SwitchOperator.php b/src/Builder/Expression/SwitchOperator.php new file mode 100644 index 000000000..8505eac00 --- /dev/null +++ b/src/Builder/Expression/SwitchOperator.php @@ -0,0 +1,64 @@ +branches = $branches; + $this->default = $default; + } +} diff --git a/src/Builder/Expression/TanOperator.php b/src/Builder/Expression/TanOperator.php new file mode 100644 index 000000000..125b3de59 --- /dev/null +++ b/src/Builder/Expression/TanOperator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/TanhOperator.php b/src/Builder/Expression/TanhOperator.php new file mode 100644 index 000000000..e337d6569 --- /dev/null +++ b/src/Builder/Expression/TanhOperator.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/TimestampFieldPath.php b/src/Builder/Expression/TimestampFieldPath.php new file mode 100644 index 000000000..76e488232 --- /dev/null +++ b/src/Builder/Expression/TimestampFieldPath.php @@ -0,0 +1,19 @@ +name = $name; + } +} diff --git a/src/Builder/Expression/ToBoolOperator.php b/src/Builder/Expression/ToBoolOperator.php new file mode 100644 index 000000000..fdd9d0125 --- /dev/null +++ b/src/Builder/Expression/ToBoolOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToDateOperator.php b/src/Builder/Expression/ToDateOperator.php new file mode 100644 index 000000000..f13cbc80a --- /dev/null +++ b/src/Builder/Expression/ToDateOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToDecimalOperator.php b/src/Builder/Expression/ToDecimalOperator.php new file mode 100644 index 000000000..00c125194 --- /dev/null +++ b/src/Builder/Expression/ToDecimalOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToDoubleOperator.php b/src/Builder/Expression/ToDoubleOperator.php new file mode 100644 index 000000000..f68bf0504 --- /dev/null +++ b/src/Builder/Expression/ToDoubleOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToIntOperator.php b/src/Builder/Expression/ToIntOperator.php new file mode 100644 index 000000000..c0390a408 --- /dev/null +++ b/src/Builder/Expression/ToIntOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToLongOperator.php b/src/Builder/Expression/ToLongOperator.php new file mode 100644 index 000000000..6edccc124 --- /dev/null +++ b/src/Builder/Expression/ToLongOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToLowerOperator.php b/src/Builder/Expression/ToLowerOperator.php new file mode 100644 index 000000000..29f70151b --- /dev/null +++ b/src/Builder/Expression/ToLowerOperator.php @@ -0,0 +1,31 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToObjectIdOperator.php b/src/Builder/Expression/ToObjectIdOperator.php new file mode 100644 index 000000000..331ea8c32 --- /dev/null +++ b/src/Builder/Expression/ToObjectIdOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToStringOperator.php b/src/Builder/Expression/ToStringOperator.php new file mode 100644 index 000000000..74c11b08c --- /dev/null +++ b/src/Builder/Expression/ToStringOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/ToUpperOperator.php b/src/Builder/Expression/ToUpperOperator.php new file mode 100644 index 000000000..3ebbe7463 --- /dev/null +++ b/src/Builder/Expression/ToUpperOperator.php @@ -0,0 +1,31 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/TopNOperator.php b/src/Builder/Expression/TopNOperator.php new file mode 100644 index 000000000..bd4b87e6e --- /dev/null +++ b/src/Builder/Expression/TopNOperator.php @@ -0,0 +1,61 @@ +n = $n; + $this->sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Expression/TopOperator.php b/src/Builder/Expression/TopOperator.php new file mode 100644 index 000000000..2613e451d --- /dev/null +++ b/src/Builder/Expression/TopOperator.php @@ -0,0 +1,55 @@ +sortBy = $sortBy; + $this->output = $output; + } +} diff --git a/src/Builder/Expression/TrimOperator.php b/src/Builder/Expression/TrimOperator.php new file mode 100644 index 000000000..dc2d18dd1 --- /dev/null +++ b/src/Builder/Expression/TrimOperator.php @@ -0,0 +1,46 @@ +input = $input; + $this->chars = $chars; + } +} diff --git a/src/Builder/Expression/TruncOperator.php b/src/Builder/Expression/TruncOperator.php new file mode 100644 index 000000000..46bdcd71e --- /dev/null +++ b/src/Builder/Expression/TruncOperator.php @@ -0,0 +1,45 @@ +number = $number; + $this->place = $place; + } +} diff --git a/src/Builder/Expression/TsIncrementOperator.php b/src/Builder/Expression/TsIncrementOperator.php new file mode 100644 index 000000000..eaa3f1bcf --- /dev/null +++ b/src/Builder/Expression/TsIncrementOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/TsSecondOperator.php b/src/Builder/Expression/TsSecondOperator.php new file mode 100644 index 000000000..712046e6a --- /dev/null +++ b/src/Builder/Expression/TsSecondOperator.php @@ -0,0 +1,33 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/TypeOperator.php b/src/Builder/Expression/TypeOperator.php new file mode 100644 index 000000000..a28c708c0 --- /dev/null +++ b/src/Builder/Expression/TypeOperator.php @@ -0,0 +1,34 @@ +expression = $expression; + } +} diff --git a/src/Builder/Expression/UnsetFieldOperator.php b/src/Builder/Expression/UnsetFieldOperator.php new file mode 100644 index 000000000..fc7c26adb --- /dev/null +++ b/src/Builder/Expression/UnsetFieldOperator.php @@ -0,0 +1,42 @@ +field = $field; + $this->input = $input; + } +} diff --git a/src/Builder/Expression/Variable.php b/src/Builder/Expression/Variable.php index f2919254d..3bcf965a2 100644 --- a/src/Builder/Expression/Variable.php +++ b/src/Builder/Expression/Variable.php @@ -6,12 +6,12 @@ namespace MongoDB\Builder\Expression; -class Variable implements ExpressionInterface +readonly class Variable implements ResolvesToAny { - public string $expression; + public string $name; - public function __construct(string $expression) + public function __construct(string $name) { - $this->expression = $expression; + $this->name = $name; } } diff --git a/src/Builder/Expression/WeekOperator.php b/src/Builder/Expression/WeekOperator.php new file mode 100644 index 000000000..5cb0787a5 --- /dev/null +++ b/src/Builder/Expression/WeekOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/YearOperator.php b/src/Builder/Expression/YearOperator.php new file mode 100644 index 000000000..947f7fb60 --- /dev/null +++ b/src/Builder/Expression/YearOperator.php @@ -0,0 +1,42 @@ +date = $date; + $this->timezone = $timezone; + } +} diff --git a/src/Builder/Expression/ZipOperator.php b/src/Builder/Expression/ZipOperator.php new file mode 100644 index 000000000..f4ba42449 --- /dev/null +++ b/src/Builder/Expression/ZipOperator.php @@ -0,0 +1,74 @@ +inputs = $inputs; + $this->useLongestLength = $useLongestLength; + if (is_array($defaults) && ! array_is_list($defaults)) { + throw new InvalidArgumentException('Expected $defaults argument to be a list, got an associative array.'); + } + + $this->defaults = $defaults; + } +} diff --git a/src/Builder/Pipeline.php b/src/Builder/Pipeline.php index 19f400eb0..7597b5033 100644 --- a/src/Builder/Pipeline.php +++ b/src/Builder/Pipeline.php @@ -4,34 +4,48 @@ use ArrayIterator; use IteratorAggregate; -use MongoDB\Builder\Stage\StageInterface; +use MongoDB\Builder\Type\StageInterface; use MongoDB\Exception\InvalidArgumentException; use Traversable; use function array_is_list; use function array_merge; -/** @template-implements IteratorAggregate */ -class Pipeline implements IteratorAggregate +/** + * An aggregation pipeline consists of one or more stages that process documents. + * + * @see https://www.mongodb.com/docs/manual/core/aggregation-pipeline/ + * + * @psalm-immutable + * @template-implements IteratorAggregate + */ +readonly class Pipeline implements IteratorAggregate { /** @var StageInterface[] */ - private array $stages = []; + private array $stages; - public function __construct(StageInterface ...$stages) + /** @no-named-arguments */ + public function __construct(StageInterface|Pipeline ...$stagesOrPipelines) { - $this->add(...$stages); - } + if (! array_is_list($stagesOrPipelines)) { + throw new InvalidArgumentException('Named arguments are not supported for pipelines'); + } - /** @return $this */ - public function add(StageInterface ...$stages): static - { - if (! array_is_list($stages)) { - throw new InvalidArgumentException('Expected $stages argument to be a list, got an associative array.'); + if (empty($stagesOrPipelines)) { + throw new InvalidArgumentException('At least one stage must be provided'); } - $this->stages = array_merge($this->stages, $stages); + $stages = []; + + foreach ($stagesOrPipelines as $stageOrPipeline) { + if ($stageOrPipeline instanceof Pipeline) { + $stages = array_merge($stages, $stageOrPipeline->stages); + } else { + $stages[] = $stageOrPipeline; + } + } - return $this; + $this->stages = $stages; } public function getIterator(): Traversable diff --git a/src/Builder/Projection.php b/src/Builder/Projection.php new file mode 100644 index 000000000..cc1b34de5 --- /dev/null +++ b/src/Builder/Projection.php @@ -0,0 +1,15 @@ +query = $query; + } +} diff --git a/src/Builder/Projection/FactoryTrait.php b/src/Builder/Projection/FactoryTrait.php new file mode 100644 index 000000000..01ab11f3c --- /dev/null +++ b/src/Builder/Projection/FactoryTrait.php @@ -0,0 +1,67 @@ +input = $input; + $this->cond = $cond; + $this->as = $as; + $this->limit = $limit; + } +} diff --git a/src/Builder/Projection/SliceOperator.php b/src/Builder/Projection/SliceOperator.php new file mode 100644 index 000000000..c61c3ba1e --- /dev/null +++ b/src/Builder/Projection/SliceOperator.php @@ -0,0 +1,37 @@ +limit = $limit; + $this->skip = $skip; + } +} diff --git a/src/Builder/Query.php b/src/Builder/Query.php index 4d829cd9d..25342cd89 100644 --- a/src/Builder/Query.php +++ b/src/Builder/Query.php @@ -1,74 +1,45 @@ ...$value */ + public array $value; + + /** + * @param Type|array|bool|float|int|non-empty-string|null|stdClass ...$value + * @no-named-arguments + */ + public function __construct(Type|stdClass|array|bool|float|int|null|string ...$value) + { + if (\count($value) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $value, got %d.', 1, \count($value))); + } + if (! array_is_list($value)) { + throw new InvalidArgumentException('Expected $value arguments to be a list (array), named arguments are not supported'); + } + $this->value = $value; + } +} diff --git a/src/Builder/Query/AndOperator.php b/src/Builder/Query/AndOperator.php new file mode 100644 index 000000000..eef0a9ba1 --- /dev/null +++ b/src/Builder/Query/AndOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param Document|QueryInterface|Serializable|array|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Document|Serializable|QueryInterface|stdClass|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Query/AndQuery.php b/src/Builder/Query/AndQuery.php deleted file mode 100644 index e572f7036..000000000 --- a/src/Builder/Query/AndQuery.php +++ /dev/null @@ -1,30 +0,0 @@ - ...$query */ - public array $query; - - /** - * @param ResolvesToBool|bool $query - */ - public function __construct(ResolvesToBool|bool ...$query) - { - if (\count($query) < 1) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', 1, \count($query))); - } - - $this->query = $query; - } -} diff --git a/src/Builder/Query/BitsAllClearOperator.php b/src/Builder/Query/BitsAllClearOperator.php new file mode 100644 index 000000000..511e895b0 --- /dev/null +++ b/src/Builder/Query/BitsAllClearOperator.php @@ -0,0 +1,43 @@ +bitmask = $bitmask; + } +} diff --git a/src/Builder/Query/BitsAllSetOperator.php b/src/Builder/Query/BitsAllSetOperator.php new file mode 100644 index 000000000..53a2939f3 --- /dev/null +++ b/src/Builder/Query/BitsAllSetOperator.php @@ -0,0 +1,43 @@ +bitmask = $bitmask; + } +} diff --git a/src/Builder/Query/BitsAnyClearOperator.php b/src/Builder/Query/BitsAnyClearOperator.php new file mode 100644 index 000000000..ba2c4aa4e --- /dev/null +++ b/src/Builder/Query/BitsAnyClearOperator.php @@ -0,0 +1,43 @@ +bitmask = $bitmask; + } +} diff --git a/src/Builder/Query/BitsAnySetOperator.php b/src/Builder/Query/BitsAnySetOperator.php new file mode 100644 index 000000000..f9509848f --- /dev/null +++ b/src/Builder/Query/BitsAnySetOperator.php @@ -0,0 +1,43 @@ +bitmask = $bitmask; + } +} diff --git a/src/Builder/Query/BoxOperator.php b/src/Builder/Query/BoxOperator.php new file mode 100644 index 000000000..44b0b628a --- /dev/null +++ b/src/Builder/Query/BoxOperator.php @@ -0,0 +1,42 @@ +value = $value; + } +} diff --git a/src/Builder/Query/CenterOperator.php b/src/Builder/Query/CenterOperator.php new file mode 100644 index 000000000..6d19751be --- /dev/null +++ b/src/Builder/Query/CenterOperator.php @@ -0,0 +1,42 @@ +value = $value; + } +} diff --git a/src/Builder/Query/CenterSphereOperator.php b/src/Builder/Query/CenterSphereOperator.php new file mode 100644 index 000000000..bd21f862b --- /dev/null +++ b/src/Builder/Query/CenterSphereOperator.php @@ -0,0 +1,42 @@ +value = $value; + } +} diff --git a/src/Builder/Query/CommentOperator.php b/src/Builder/Query/CommentOperator.php new file mode 100644 index 000000000..3b92258f6 --- /dev/null +++ b/src/Builder/Query/CommentOperator.php @@ -0,0 +1,32 @@ +comment = $comment; + } +} diff --git a/src/Builder/Query/ElemMatchOperator.php b/src/Builder/Query/ElemMatchOperator.php new file mode 100644 index 000000000..3ec6de87d --- /dev/null +++ b/src/Builder/Query/ElemMatchOperator.php @@ -0,0 +1,44 @@ +query = $query; + } +} diff --git a/src/Builder/Query/EqOperator.php b/src/Builder/Query/EqOperator.php new file mode 100644 index 000000000..7dc490f2a --- /dev/null +++ b/src/Builder/Query/EqOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/ExistsOperator.php b/src/Builder/Query/ExistsOperator.php new file mode 100644 index 000000000..65b26896c --- /dev/null +++ b/src/Builder/Query/ExistsOperator.php @@ -0,0 +1,32 @@ +exists = $exists; + } +} diff --git a/src/Builder/Query/ExprOperator.php b/src/Builder/Query/ExprOperator.php new file mode 100644 index 000000000..47dfaafa6 --- /dev/null +++ b/src/Builder/Query/ExprOperator.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Query/ExprQuery.php b/src/Builder/Query/ExprQuery.php deleted file mode 100644 index 810652b9c..000000000 --- a/src/Builder/Query/ExprQuery.php +++ /dev/null @@ -1,25 +0,0 @@ -expression = $expression; - } -} diff --git a/src/Builder/Query/FactoryTrait.php b/src/Builder/Query/FactoryTrait.php new file mode 100644 index 000000000..e5e85fdde --- /dev/null +++ b/src/Builder/Query/FactoryTrait.php @@ -0,0 +1,512 @@ +geometry = $geometry; + } +} diff --git a/src/Builder/Query/GeoWithinOperator.php b/src/Builder/Query/GeoWithinOperator.php new file mode 100644 index 000000000..2b69dee77 --- /dev/null +++ b/src/Builder/Query/GeoWithinOperator.php @@ -0,0 +1,36 @@ +geometry = $geometry; + } +} diff --git a/src/Builder/Query/GeometryOperator.php b/src/Builder/Query/GeometryOperator.php new file mode 100644 index 000000000..9c2026b6a --- /dev/null +++ b/src/Builder/Query/GeometryOperator.php @@ -0,0 +1,58 @@ +type = $type; + if (is_array($coordinates) && ! array_is_list($coordinates)) { + throw new InvalidArgumentException('Expected $coordinates argument to be a list, got an associative array.'); + } + + $this->coordinates = $coordinates; + $this->crs = $crs; + } +} diff --git a/src/Builder/Query/GtOperator.php b/src/Builder/Query/GtOperator.php new file mode 100644 index 000000000..7e1016f02 --- /dev/null +++ b/src/Builder/Query/GtOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/GtQuery.php b/src/Builder/Query/GtQuery.php deleted file mode 100644 index 58c558aed..000000000 --- a/src/Builder/Query/GtQuery.php +++ /dev/null @@ -1,26 +0,0 @@ -value = $value; - } -} diff --git a/src/Builder/Query/GteOperator.php b/src/Builder/Query/GteOperator.php new file mode 100644 index 000000000..ae0d4fc63 --- /dev/null +++ b/src/Builder/Query/GteOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/GteQuery.php b/src/Builder/Query/GteQuery.php deleted file mode 100644 index 130a56bd4..000000000 --- a/src/Builder/Query/GteQuery.php +++ /dev/null @@ -1,26 +0,0 @@ -value = $value; - } -} diff --git a/src/Builder/Query/InOperator.php b/src/Builder/Query/InOperator.php new file mode 100644 index 000000000..37fca9e46 --- /dev/null +++ b/src/Builder/Query/InOperator.php @@ -0,0 +1,42 @@ +value = $value; + } +} diff --git a/src/Builder/Query/JsonSchemaOperator.php b/src/Builder/Query/JsonSchemaOperator.php new file mode 100644 index 000000000..e8834921d --- /dev/null +++ b/src/Builder/Query/JsonSchemaOperator.php @@ -0,0 +1,35 @@ +schema = $schema; + } +} diff --git a/src/Builder/Query/LtOperator.php b/src/Builder/Query/LtOperator.php new file mode 100644 index 000000000..a2fa54fbe --- /dev/null +++ b/src/Builder/Query/LtOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/LtQuery.php b/src/Builder/Query/LtQuery.php deleted file mode 100644 index 621fd7d26..000000000 --- a/src/Builder/Query/LtQuery.php +++ /dev/null @@ -1,26 +0,0 @@ -value = $value; - } -} diff --git a/src/Builder/Query/LteOperator.php b/src/Builder/Query/LteOperator.php new file mode 100644 index 000000000..f74f35a8a --- /dev/null +++ b/src/Builder/Query/LteOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/MaxDistanceOperator.php b/src/Builder/Query/MaxDistanceOperator.php new file mode 100644 index 000000000..1590c3859 --- /dev/null +++ b/src/Builder/Query/MaxDistanceOperator.php @@ -0,0 +1,34 @@ +value = $value; + } +} diff --git a/src/Builder/Query/MinDistanceOperator.php b/src/Builder/Query/MinDistanceOperator.php new file mode 100644 index 000000000..1b11eab47 --- /dev/null +++ b/src/Builder/Query/MinDistanceOperator.php @@ -0,0 +1,33 @@ +value = $value; + } +} diff --git a/src/Builder/Query/ModOperator.php b/src/Builder/Query/ModOperator.php new file mode 100644 index 000000000..fe352b6e1 --- /dev/null +++ b/src/Builder/Query/ModOperator.php @@ -0,0 +1,37 @@ +divisor = $divisor; + $this->remainder = $remainder; + } +} diff --git a/src/Builder/Query/NaturalOperator.php b/src/Builder/Query/NaturalOperator.php new file mode 100644 index 000000000..c8ae85bd7 --- /dev/null +++ b/src/Builder/Query/NaturalOperator.php @@ -0,0 +1,25 @@ +value = $value; + } +} diff --git a/src/Builder/Query/NearOperator.php b/src/Builder/Query/NearOperator.php new file mode 100644 index 000000000..fefe75427 --- /dev/null +++ b/src/Builder/Query/NearOperator.php @@ -0,0 +1,50 @@ +geometry = $geometry; + $this->maxDistance = $maxDistance; + $this->minDistance = $minDistance; + } +} diff --git a/src/Builder/Query/NearSphereOperator.php b/src/Builder/Query/NearSphereOperator.php new file mode 100644 index 000000000..fbb897f4e --- /dev/null +++ b/src/Builder/Query/NearSphereOperator.php @@ -0,0 +1,50 @@ +geometry = $geometry; + $this->maxDistance = $maxDistance; + $this->minDistance = $minDistance; + } +} diff --git a/src/Builder/Query/NinOperator.php b/src/Builder/Query/NinOperator.php new file mode 100644 index 000000000..09f5e0519 --- /dev/null +++ b/src/Builder/Query/NinOperator.php @@ -0,0 +1,42 @@ +value = $value; + } +} diff --git a/src/Builder/Query/NorOperator.php b/src/Builder/Query/NorOperator.php new file mode 100644 index 000000000..2664e23e0 --- /dev/null +++ b/src/Builder/Query/NorOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param Document|QueryInterface|Serializable|array|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Document|Serializable|QueryInterface|stdClass|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Query/NotOperator.php b/src/Builder/Query/NotOperator.php new file mode 100644 index 000000000..9e2b686f3 --- /dev/null +++ b/src/Builder/Query/NotOperator.php @@ -0,0 +1,45 @@ +expression = $expression; + } +} diff --git a/src/Builder/Query/OrOperator.php b/src/Builder/Query/OrOperator.php new file mode 100644 index 000000000..ab1fe250b --- /dev/null +++ b/src/Builder/Query/OrOperator.php @@ -0,0 +1,45 @@ + ...$expression */ + public array $expression; + + /** + * @param Document|QueryInterface|Serializable|array|stdClass ...$expression + * @no-named-arguments + */ + public function __construct(Document|Serializable|QueryInterface|stdClass|array ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + if (! array_is_list($expression)) { + throw new InvalidArgumentException('Expected $expression arguments to be a list (array), named arguments are not supported'); + } + $this->expression = $expression; + } +} diff --git a/src/Builder/Query/OrQuery.php b/src/Builder/Query/OrQuery.php deleted file mode 100644 index 5149b7cbc..000000000 --- a/src/Builder/Query/OrQuery.php +++ /dev/null @@ -1,31 +0,0 @@ - ...$query */ - public array $query; - - /** - * @param ExpressionInterface|mixed $query - */ - public function __construct(mixed ...$query) - { - if (\count($query) < 1) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', 1, \count($query))); - } - - $this->query = $query; - } -} diff --git a/src/Builder/Query/PolygonOperator.php b/src/Builder/Query/PolygonOperator.php new file mode 100644 index 000000000..e008e2f4f --- /dev/null +++ b/src/Builder/Query/PolygonOperator.php @@ -0,0 +1,42 @@ +points = $points; + } +} diff --git a/src/Builder/Query/RandOperator.php b/src/Builder/Query/RandOperator.php new file mode 100644 index 000000000..0339fd419 --- /dev/null +++ b/src/Builder/Query/RandOperator.php @@ -0,0 +1,25 @@ +regex = $regex; + } +} diff --git a/src/Builder/Query/SizeOperator.php b/src/Builder/Query/SizeOperator.php new file mode 100644 index 000000000..465aa55ac --- /dev/null +++ b/src/Builder/Query/SizeOperator.php @@ -0,0 +1,32 @@ +value = $value; + } +} diff --git a/src/Builder/Query/TextOperator.php b/src/Builder/Query/TextOperator.php new file mode 100644 index 000000000..416c8476f --- /dev/null +++ b/src/Builder/Query/TextOperator.php @@ -0,0 +1,60 @@ +search = $search; + $this->language = $language; + $this->caseSensitive = $caseSensitive; + $this->diacriticSensitive = $diacriticSensitive; + } +} diff --git a/src/Builder/Query/TypeOperator.php b/src/Builder/Query/TypeOperator.php new file mode 100644 index 000000000..c1d8af42e --- /dev/null +++ b/src/Builder/Query/TypeOperator.php @@ -0,0 +1,42 @@ +type = $type; + } +} diff --git a/src/Builder/Query/WhereOperator.php b/src/Builder/Query/WhereOperator.php new file mode 100644 index 000000000..e77708dcb --- /dev/null +++ b/src/Builder/Query/WhereOperator.php @@ -0,0 +1,32 @@ +function = $function; + } +} diff --git a/src/Builder/Stage.php b/src/Builder/Stage.php index 7466925bd..86f796357 100644 --- a/src/Builder/Stage.php +++ b/src/Builder/Stage.php @@ -1,68 +1,29 @@ ...$expression Specify the name of each field to add and set its value to an aggregation expression or an empty object. */ + public stdClass $expression; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$expression Specify the name of each field to add and set its value to an aggregation expression or an empty object. + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$expression) + { + if (\count($expression) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $expression, got %d.', 1, \count($expression))); + } + foreach($expression as $key => $value) { + if (! is_string($key)) { + throw new InvalidArgumentException('Expected $expression arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + $expression = (object) $expression; + $this->expression = $expression; + } +} diff --git a/src/Builder/Stage/BucketAutoStage.php b/src/Builder/Stage/BucketAutoStage.php new file mode 100644 index 000000000..c4177fd09 --- /dev/null +++ b/src/Builder/Stage/BucketAutoStage.php @@ -0,0 +1,65 @@ +groupBy = $groupBy; + $this->buckets = $buckets; + $this->output = $output; + $this->granularity = $granularity; + } +} diff --git a/src/Builder/Stage/BucketStage.php b/src/Builder/Stage/BucketStage.php new file mode 100644 index 000000000..507a47d94 --- /dev/null +++ b/src/Builder/Stage/BucketStage.php @@ -0,0 +1,89 @@ +groupBy = $groupBy; + if (is_array($boundaries) && ! array_is_list($boundaries)) { + throw new InvalidArgumentException('Expected $boundaries argument to be a list, got an associative array.'); + } + + $this->boundaries = $boundaries; + $this->default = $default; + $this->output = $output; + } +} diff --git a/src/Builder/Stage/ChangeStreamSplitLargeEventStage.php b/src/Builder/Stage/ChangeStreamSplitLargeEventStage.php new file mode 100644 index 000000000..e457a06c3 --- /dev/null +++ b/src/Builder/Stage/ChangeStreamSplitLargeEventStage.php @@ -0,0 +1,26 @@ +allChangesForCluster = $allChangesForCluster; + $this->fullDocument = $fullDocument; + $this->fullDocumentBeforeChange = $fullDocumentBeforeChange; + $this->resumeAfter = $resumeAfter; + $this->showExpandedEvents = $showExpandedEvents; + $this->startAfter = $startAfter; + $this->startAtOperationTime = $startAtOperationTime; + } +} diff --git a/src/Builder/Stage/CollStatsStage.php b/src/Builder/Stage/CollStatsStage.php new file mode 100644 index 000000000..ee69fcc99 --- /dev/null +++ b/src/Builder/Stage/CollStatsStage.php @@ -0,0 +1,35 @@ +config = $config; + } +} diff --git a/src/Builder/Stage/CountStage.php b/src/Builder/Stage/CountStage.php new file mode 100644 index 000000000..b9ab8ca67 --- /dev/null +++ b/src/Builder/Stage/CountStage.php @@ -0,0 +1,33 @@ +field = $field; + } +} diff --git a/src/Builder/Stage/CurrentOpStage.php b/src/Builder/Stage/CurrentOpStage.php new file mode 100644 index 000000000..27ba4fdeb --- /dev/null +++ b/src/Builder/Stage/CurrentOpStage.php @@ -0,0 +1,25 @@ + in an embedded document or in an array, use dot notation. + */ + public string $field; + + /** @param Document|Serializable|array|stdClass $range Specification for range based densification. */ + public Document|Serializable|stdClass|array $range; + + /** @param Optional|BSONArray|PackedArray|array $partitionByFields The field(s) that will be used as the partition keys. */ + public Optional|PackedArray|BSONArray|array $partitionByFields; + + /** + * @param non-empty-string $field The field to densify. The values of the specified field must either be all numeric values or all dates. + * Documents that do not contain the specified field continue through the pipeline unmodified. + * To specify a in an embedded document or in an array, use dot notation. + * @param Document|Serializable|array|stdClass $range Specification for range based densification. + * @param Optional|BSONArray|PackedArray|array $partitionByFields The field(s) that will be used as the partition keys. + */ + public function __construct( + string $field, + Document|Serializable|stdClass|array $range, + Optional|PackedArray|BSONArray|array $partitionByFields = Optional::Undefined, + ) { + $this->field = $field; + $this->range = $range; + if (is_array($partitionByFields) && ! array_is_list($partitionByFields)) { + throw new InvalidArgumentException('Expected $partitionByFields argument to be a list, got an associative array.'); + } + + $this->partitionByFields = $partitionByFields; + } +} diff --git a/src/Builder/Stage/DocumentsStage.php b/src/Builder/Stage/DocumentsStage.php new file mode 100644 index 000000000..c9aeda32c --- /dev/null +++ b/src/Builder/Stage/DocumentsStage.php @@ -0,0 +1,53 @@ +documents = $documents; + } +} diff --git a/src/Builder/Stage/FacetStage.php b/src/Builder/Stage/FacetStage.php new file mode 100644 index 000000000..ac5315712 --- /dev/null +++ b/src/Builder/Stage/FacetStage.php @@ -0,0 +1,48 @@ + ...$facet */ + public stdClass $facet; + + /** + * @param BSONArray|PackedArray|Pipeline|array ...$facet + */ + public function __construct(PackedArray|Pipeline|BSONArray|array ...$facet) + { + if (\count($facet) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $facet, got %d.', 1, \count($facet))); + } + foreach($facet as $key => $value) { + if (! is_string($key)) { + throw new InvalidArgumentException('Expected $facet arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + $facet = (object) $facet; + $this->facet = $facet; + } +} diff --git a/src/Builder/Stage/FactoryTrait.php b/src/Builder/Stage/FactoryTrait.php new file mode 100644 index 000000000..07fc515aa --- /dev/null +++ b/src/Builder/Stage/FactoryTrait.php @@ -0,0 +1,692 @@ + in an embedded document or in an array, use dot notation. + * @param Document|Serializable|array|stdClass $range Specification for range based densification. + * @param Optional|BSONArray|PackedArray|array $partitionByFields The field(s) that will be used as the partition keys. + */ + public static function densify( + string $field, + Document|Serializable|stdClass|array $range, + Optional|PackedArray|BSONArray|array $partitionByFields = Optional::Undefined, + ): DensifyStage + { + return new DensifyStage($field, $range, $partitionByFields); + } + + /** + * Returns literal documents from input values. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/ + * @param BSONArray|PackedArray|ResolvesToArray|array $documents $documents accepts any valid expression that resolves to an array of objects. This includes: + * - system variables, such as $$NOW or $$SEARCH_META + * - $let expressions + * - variables in scope from $lookup expressions + * Expressions that do not resolve to a current document, like $myField or $$ROOT, will result in an error. + */ + public static function documents(PackedArray|ResolvesToArray|BSONArray|array $documents): DocumentsStage + { + return new DocumentsStage($documents); + } + + /** + * Processes multiple aggregation pipelines within a single stage on the same set of input documents. Enables the creation of multi-faceted aggregations capable of characterizing data across multiple dimensions, or facets, in a single stage. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/ + * @param BSONArray|PackedArray|Pipeline|array ...$facet + */ + public static function facet(PackedArray|Pipeline|BSONArray|array ...$facet): FacetStage + { + return new FacetStage(...$facet); + } + + /** + * Populates null and missing field values within documents. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/ + * @param Document|Serializable|array|stdClass $output Specifies an object containing each field for which to fill missing values. You can specify multiple fields in the output object. + * The object name is the name of the field to fill. The object value specifies how the field is filled. + * @param Optional|Document|Serializable|array|non-empty-string|stdClass $partitionBy Specifies an expression to group the documents. In the $fill stage, a group of documents is known as a partition. + * If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection. + * partitionBy and partitionByFields are mutually exclusive. + * @param Optional|BSONArray|PackedArray|array $partitionByFields Specifies an array of fields as the compound key to group the documents. In the $fill stage, each group of documents is known as a partition. + * If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection. + * partitionBy and partitionByFields are mutually exclusive. + * @param Optional|Document|Serializable|array|stdClass $sortBy Specifies the field or fields to sort the documents within each partition. Uses the same syntax as the $sort stage. + */ + public static function fill( + Document|Serializable|stdClass|array $output, + Optional|Document|Serializable|stdClass|array|string $partitionBy = Optional::Undefined, + Optional|PackedArray|BSONArray|array $partitionByFields = Optional::Undefined, + Optional|Document|Serializable|stdClass|array $sortBy = Optional::Undefined, + ): FillStage + { + return new FillStage($output, $partitionBy, $partitionByFields, $sortBy); + } + + /** + * Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/ + * @param non-empty-string $distanceField The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation. + * @param Document|Serializable|array|stdClass $near The point for which to find the closest documents. + * @param Optional|Decimal128|Int64|float|int $distanceMultiplier The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth. + * @param Optional|non-empty-string $includeLocs This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation. + * @param Optional|non-empty-string $key Specify the geospatial indexed field to use when calculating the distance. + * @param Optional|Decimal128|Int64|float|int $maxDistance The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point. + * Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs. + * @param Optional|Decimal128|Int64|float|int $minDistance The minimum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall outside the specified distance from the center point. + * Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs. + * @param Optional|Document|QueryInterface|Serializable|array|stdClass $query Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax. + * You cannot specify a $near predicate in the query field of the $geoNear stage. + * @param Optional|bool $spherical Determines how MongoDB calculates the distance between two points: + * - When true, MongoDB uses $nearSphere semantics and calculates distances using spherical geometry. + * - When false, MongoDB uses $near semantics: spherical geometry for 2dsphere indexes and planar geometry for 2d indexes. + * Default: false. + */ + public static function geoNear( + string $distanceField, + Document|Serializable|stdClass|array $near, + Optional|Decimal128|Int64|float|int $distanceMultiplier = Optional::Undefined, + Optional|string $includeLocs = Optional::Undefined, + Optional|string $key = Optional::Undefined, + Optional|Decimal128|Int64|float|int $maxDistance = Optional::Undefined, + Optional|Decimal128|Int64|float|int $minDistance = Optional::Undefined, + Optional|Document|Serializable|QueryInterface|stdClass|array $query = Optional::Undefined, + Optional|bool $spherical = Optional::Undefined, + ): GeoNearStage + { + return new GeoNearStage($distanceField, $near, $distanceMultiplier, $includeLocs, $key, $maxDistance, $minDistance, $query, $spherical); + } + + /** + * Performs a recursive search on a collection. To each output document, adds a new array field that contains the traversal results of the recursive search for that document. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/ + * @param non-empty-string $from Target collection for the $graphLookup operation to search, recursively matching the connectFromField to the connectToField. The from collection must be in the same database as any other collections used in the operation. + * Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded. + * @param BSONArray|ExpressionInterface|PackedArray|Type|array|bool|float|int|non-empty-string|null|stdClass $startWith Expression that specifies the value of the connectFromField with which to start the recursive search. Optionally, startWith may be array of values, each of which is individually followed through the traversal process. + * @param non-empty-string $connectFromField Field name whose value $graphLookup uses to recursively match against the connectToField of other documents in the collection. If the value is an array, each element is individually followed through the traversal process. + * @param non-empty-string $connectToField Field name in other documents against which to match the value of the field specified by the connectFromField parameter. + * @param non-empty-string $as Name of the array field added to each output document. Contains the documents traversed in the $graphLookup stage to reach the document. + * @param Optional|int $maxDepth Non-negative integral number specifying the maximum recursion depth. + * @param Optional|non-empty-string $depthField Name of the field to add to each traversed document in the search path. The value of this field is the recursion depth for the document, represented as a NumberLong. Recursion depth value starts at zero, so the first lookup corresponds to zero depth. + * @param Optional|Document|QueryInterface|Serializable|array|stdClass $restrictSearchWithMatch A document specifying additional conditions for the recursive search. The syntax is identical to query filter syntax. + */ + public static function graphLookup( + string $from, + PackedArray|Type|ExpressionInterface|BSONArray|stdClass|array|bool|float|int|null|string $startWith, + string $connectFromField, + string $connectToField, + string $as, + Optional|int $maxDepth = Optional::Undefined, + Optional|string $depthField = Optional::Undefined, + Optional|Document|Serializable|QueryInterface|stdClass|array $restrictSearchWithMatch = Optional::Undefined, + ): GraphLookupStage + { + return new GraphLookupStage($from, $startWith, $connectFromField, $connectToField, $as, $maxDepth, $depthField, $restrictSearchWithMatch); + } + + /** + * Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $_id The _id expression specifies the group key. If you specify an _id value of null, or any other constant value, the $group stage returns a single document that aggregates values across all of the input documents. + * @param AccumulatorInterface|Document|Serializable|array|stdClass ...$field Computed using the accumulator operators. + */ + public static function group( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $_id, + Document|Serializable|AccumulatorInterface|stdClass|array ...$field, + ): GroupStage + { + return new GroupStage($_id, ...$field); + } + + /** + * Returns statistics regarding the use of each index for the collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/ + */ + public static function indexStats(): IndexStatsStage + { + return new IndexStatsStage(); + } + + /** + * Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/ + * @param int $limit + */ + public static function limit(int $limit): LimitStage + { + return new LimitStage($limit); + } + + /** + * Lists all active sessions recently in use on the currently connected mongos or mongod instance. These sessions may have not yet propagated to the system.sessions collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/ + * @param Optional|BSONArray|PackedArray|array $users Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users. + * @param Optional|bool $allUsers Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster. + */ + public static function listLocalSessions( + Optional|PackedArray|BSONArray|array $users = Optional::Undefined, + Optional|bool $allUsers = Optional::Undefined, + ): ListLocalSessionsStage + { + return new ListLocalSessionsStage($users, $allUsers); + } + + /** + * Lists sampled queries for all collections or a specific collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/ + * @param Optional|non-empty-string $namespace + */ + public static function listSampledQueries( + Optional|string $namespace = Optional::Undefined, + ): ListSampledQueriesStage + { + return new ListSampledQueriesStage($namespace); + } + + /** + * Returns information about existing Atlas Search indexes on a specified collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/ + * @param Optional|non-empty-string $id The id of the index to return information about. + * @param Optional|non-empty-string $name The name of the index to return information about. + */ + public static function listSearchIndexes( + Optional|string $id = Optional::Undefined, + Optional|string $name = Optional::Undefined, + ): ListSearchIndexesStage + { + return new ListSearchIndexesStage($id, $name); + } + + /** + * Lists all sessions that have been active long enough to propagate to the system.sessions collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/ + * @param Optional|BSONArray|PackedArray|array $users Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users. + * @param Optional|bool $allUsers Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster. + */ + public static function listSessions( + Optional|PackedArray|BSONArray|array $users = Optional::Undefined, + Optional|bool $allUsers = Optional::Undefined, + ): ListSessionsStage + { + return new ListSessionsStage($users, $allUsers); + } + + /** + * Performs a left outer join to another collection in the same database to filter in documents from the "joined" collection for processing. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/ + * @param non-empty-string $as Specifies the name of the new array field to add to the input documents. The new array field contains the matching documents from the from collection. If the specified name already exists in the input document, the existing field is overwritten. + * @param Optional|non-empty-string $from Specifies the collection in the same database to perform the join with. + * from is optional, you can use a $documents stage in a $lookup stage instead. For an example, see Use a $documents Stage in a $lookup Stage. + * Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded. + * @param Optional|non-empty-string $localField Specifies the field from the documents input to the $lookup stage. $lookup performs an equality match on the localField to the foreignField from the documents of the from collection. If an input document does not contain the localField, the $lookup treats the field as having a value of null for matching purposes. + * @param Optional|non-empty-string $foreignField Specifies the field from the documents in the from collection. $lookup performs an equality match on the foreignField to the localField from the input documents. If a document in the from collection does not contain the foreignField, the $lookup treats the value as null for matching purposes. + * @param Optional|Document|Serializable|array|stdClass $let Specifies variables to use in the pipeline stages. Use the variable expressions to access the fields from the joined collection's documents that are input to the pipeline. + * @param Optional|BSONArray|PackedArray|Pipeline|array $pipeline Specifies the pipeline to run on the joined collection. The pipeline determines the resulting documents from the joined collection. To return all documents, specify an empty pipeline []. + * The pipeline cannot include the $out stage or the $mergestage. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline. + * The pipeline cannot directly access the joined document fields. Instead, define variables for the joined document fields using the let option and then reference the variables in the pipeline stages. + */ + public static function lookup( + string $as, + Optional|string $from = Optional::Undefined, + Optional|string $localField = Optional::Undefined, + Optional|string $foreignField = Optional::Undefined, + Optional|Document|Serializable|stdClass|array $let = Optional::Undefined, + Optional|PackedArray|Pipeline|BSONArray|array $pipeline = Optional::Undefined, + ): LookupStage + { + return new LookupStage($as, $from, $localField, $foreignField, $let, $pipeline); + } + + /** + * Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/ + * @param Document|QueryInterface|Serializable|array|stdClass $query + */ + public static function match(Document|Serializable|QueryInterface|stdClass|array $query): MatchStage + { + return new MatchStage($query); + } + + /** + * Writes the resulting documents of the aggregation pipeline to a collection. The stage can incorporate (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) the results into an output collection. To use the $merge stage, it must be the last stage in the pipeline. + * New in version 4.2. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/ + * @param non-empty-string $into The output collection. + * @param Optional|BSONArray|PackedArray|array|non-empty-string $on Field or fields that act as a unique identifier for a document. The identifier determines if a results document matches an existing document in the output collection. + * @param Optional|Document|Serializable|array|stdClass $let Specifies variables for use in the whenMatched pipeline. + * @param Optional|non-empty-string $whenMatched The behavior of $merge if a result document and an existing document in the collection have the same value for the specified on field(s). + * @param Optional|non-empty-string $whenNotMatched The behavior of $merge if a result document does not match an existing document in the out collection. + */ + public static function merge( + string $into, + Optional|PackedArray|BSONArray|array|string $on = Optional::Undefined, + Optional|Document|Serializable|stdClass|array $let = Optional::Undefined, + Optional|string $whenMatched = Optional::Undefined, + Optional|string $whenNotMatched = Optional::Undefined, + ): MergeStage + { + return new MergeStage($into, $on, $let, $whenMatched, $whenNotMatched); + } + + /** + * Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/ + * @param non-empty-string $db Target collection name to write documents from $out to. + * @param non-empty-string $coll Target database name to write documents from $out to. + * @param Optional|Document|Serializable|array|stdClass $timeseries If set, the aggregation stage will use these options to create or replace a time-series collection in the given namespace. + */ + public static function out( + string $db, + string $coll, + Optional|Document|Serializable|stdClass|array $timeseries = Optional::Undefined, + ): OutStage + { + return new OutStage($db, $coll, $timeseries); + } + + /** + * Returns plan cache information for a collection. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/ + */ + public static function planCacheStats(): PlanCacheStatsStage + { + return new PlanCacheStatsStage(); + } + + /** + * Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/ + * @param Document|ProjectionInterface|ResolvesToBool|Serializable|array|bool|int|stdClass ...$specification + */ + public static function project( + Document|Serializable|ResolvesToBool|ProjectionInterface|stdClass|array|bool|int ...$specification, + ): ProjectStage + { + return new ProjectStage(...$specification); + } + + /** + * Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero documents. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function redact( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): RedactStage + { + return new RedactStage($expression); + } + + /** + * Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/ + * @param Document|ResolvesToObject|Serializable|array|stdClass $newRoot + */ + public static function replaceRoot( + Document|Serializable|ResolvesToObject|stdClass|array $newRoot, + ): ReplaceRootStage + { + return new ReplaceRootStage($newRoot); + } + + /** + * Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. + * Alias for $replaceRoot. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/ + * @param Document|ResolvesToObject|Serializable|array|stdClass $expression + */ + public static function replaceWith( + Document|Serializable|ResolvesToObject|stdClass|array $expression, + ): ReplaceWithStage + { + return new ReplaceWithStage($expression); + } + + /** + * Randomly selects the specified number of documents from its input. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/ + * @param int $size The number of documents to randomly select. + */ + public static function sample(int $size): SampleStage + { + return new SampleStage($size); + } + + /** + * Performs a full-text search of the field or fields in an Atlas collection. + * NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/search/ + * @param Document|Serializable|array|stdClass $search + */ + public static function search(Document|Serializable|stdClass|array $search): SearchStage + { + return new SearchStage($search); + } + + /** + * Returns different types of metadata result documents for the Atlas Search query against an Atlas collection. + * NOTE: $searchMeta is only available for MongoDB Atlas clusters running MongoDB v4.4.9 or higher, and is not available for self-managed deployments. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/searchMeta/ + * @param Document|Serializable|array|stdClass $meta + */ + public static function searchMeta(Document|Serializable|stdClass|array $meta): SearchMetaStage + { + return new SearchMetaStage($meta); + } + + /** + * Adds new fields to documents. Outputs documents that contain all existing fields from the input documents and newly added fields. + * Alias for $addFields. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$field + */ + public static function set(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$field): SetStage + { + return new SetStage(...$field); + } + + /** + * Groups documents into windows and applies one or more operators to the documents in each window. + * New in version 5.0. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $partitionBy Specifies an expression to group the documents. In the $setWindowFields stage, the group of documents is known as a partition. Default is one partition for the entire collection. + * @param Document|Serializable|array|stdClass $sortBy Specifies the field(s) to sort the documents by in the partition. Uses the same syntax as the $sort stage. Default is no sorting. + * @param Document|Serializable|array|stdClass $output Specifies the field(s) to append to the documents in the output returned by the $setWindowFields stage. Each field is set to the result returned by the window operator. + * A field can contain dots to specify embedded document fields and array fields. The semantics for the embedded document dotted notation in the $setWindowFields stage are the same as the $addFields and $set stages. + * @param Optional|Document|Serializable|array|stdClass $window Specifies the window boundaries and parameters. Window boundaries are inclusive. Default is an unbounded window, which includes all documents in the partition. + */ + public static function setWindowFields( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $partitionBy, + Document|Serializable|stdClass|array $sortBy, + Document|Serializable|stdClass|array $output, + Optional|Document|Serializable|stdClass|array $window = Optional::Undefined, + ): SetWindowFieldsStage + { + return new SetWindowFieldsStage($partitionBy, $sortBy, $output, $window); + } + + /** + * Provides data and size distribution information on sharded collections. + * New in version 6.0.3. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/ + */ + public static function shardedDataDistribution(): ShardedDataDistributionStage + { + return new ShardedDataDistributionStage(); + } + + /** + * Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/ + * @param int $skip + */ + public static function skip(int $skip): SkipStage + { + return new SkipStage($skip); + } + + /** + * Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/ + * @param Document|Serializable|array|stdClass $sort + */ + public static function sort(Document|Serializable|stdClass|array $sort): SortStage + { + return new SortStage($sort); + } + + /** + * Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/ + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $expression + */ + public static function sortByCount( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $expression, + ): SortByCountStage + { + return new SortByCountStage($expression); + } + + /** + * Performs a union of two collections; i.e. combines pipeline results from two collections into a single result set. + * New in version 4.4. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/ + * @param non-empty-string $coll The collection or view whose pipeline results you wish to include in the result set. + * @param Optional|BSONArray|PackedArray|Pipeline|array $pipeline An aggregation pipeline to apply to the specified coll. + * The pipeline cannot include the $out and $merge stages. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline. + */ + public static function unionWith( + string $coll, + Optional|PackedArray|Pipeline|BSONArray|array $pipeline = Optional::Undefined, + ): UnionWithStage + { + return new UnionWithStage($coll, $pipeline); + } + + /** + * Removes or excludes fields from documents. + * Alias for $project stage that removes or excludes fields. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/ + * @param FieldPath|non-empty-string ...$field + */ + public static function unset(FieldPath|string ...$field): UnsetStage + { + return new UnsetStage(...$field); + } + + /** + * Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/ + * @param ArrayFieldPath|non-empty-string $path Field path to an array field. + * @param Optional|non-empty-string $includeArrayIndex The name of a new field to hold the array index of the element. The name cannot start with a dollar sign $. + * @param Optional|bool $preserveNullAndEmptyArrays If true, if the path is null, missing, or an empty array, $unwind outputs the document. + * If false, if path is null, missing, or an empty array, $unwind does not output a document. + * The default value is false. + */ + public static function unwind( + ArrayFieldPath|string $path, + Optional|string $includeArrayIndex = Optional::Undefined, + Optional|bool $preserveNullAndEmptyArrays = Optional::Undefined, + ): UnwindStage + { + return new UnwindStage($path, $includeArrayIndex, $preserveNullAndEmptyArrays); + } +} diff --git a/src/Builder/Stage/FillStage.php b/src/Builder/Stage/FillStage.php new file mode 100644 index 000000000..49a2df8ad --- /dev/null +++ b/src/Builder/Stage/FillStage.php @@ -0,0 +1,81 @@ +output = $output; + $this->partitionBy = $partitionBy; + if (is_array($partitionByFields) && ! array_is_list($partitionByFields)) { + throw new InvalidArgumentException('Expected $partitionByFields argument to be a list, got an associative array.'); + } + + $this->partitionByFields = $partitionByFields; + $this->sortBy = $sortBy; + } +} diff --git a/src/Builder/Stage/GeoNearStage.php b/src/Builder/Stage/GeoNearStage.php new file mode 100644 index 000000000..ef7ad610b --- /dev/null +++ b/src/Builder/Stage/GeoNearStage.php @@ -0,0 +1,116 @@ +distanceField = $distanceField; + $this->near = $near; + $this->distanceMultiplier = $distanceMultiplier; + $this->includeLocs = $includeLocs; + $this->key = $key; + $this->maxDistance = $maxDistance; + $this->minDistance = $minDistance; + if (is_array($query) || is_object($query)) { + $query = QueryObject::create($query); + } + + $this->query = $query; + $this->spherical = $spherical; + } +} diff --git a/src/Builder/Stage/GraphLookupStage.php b/src/Builder/Stage/GraphLookupStage.php new file mode 100644 index 000000000..8cd1d111c --- /dev/null +++ b/src/Builder/Stage/GraphLookupStage.php @@ -0,0 +1,102 @@ +from = $from; + if (is_array($startWith) && ! array_is_list($startWith)) { + throw new InvalidArgumentException('Expected $startWith argument to be a list, got an associative array.'); + } + + $this->startWith = $startWith; + $this->connectFromField = $connectFromField; + $this->connectToField = $connectToField; + $this->as = $as; + $this->maxDepth = $maxDepth; + $this->depthField = $depthField; + if (is_array($restrictSearchWithMatch) || is_object($restrictSearchWithMatch)) { + $restrictSearchWithMatch = QueryObject::create($restrictSearchWithMatch); + } + + $this->restrictSearchWithMatch = $restrictSearchWithMatch; + } +} diff --git a/src/Builder/Stage/GroupStage.php b/src/Builder/Stage/GroupStage.php index 395dee6ed..1839e1664 100644 --- a/src/Builder/Stage/GroupStage.php +++ b/src/Builder/Stage/GroupStage.php @@ -6,25 +6,52 @@ namespace MongoDB\Builder\Stage; -use MongoDB\Builder\Expression\ExpressionInterface; +use MongoDB\BSON\Document; +use MongoDB\BSON\Serializable; +use MongoDB\BSON\Type; +use MongoDB\Builder\Type\AccumulatorInterface; +use MongoDB\Builder\Type\Encode; +use MongoDB\Builder\Type\ExpressionInterface; +use MongoDB\Builder\Type\StageInterface; +use MongoDB\Exception\InvalidArgumentException; +use stdClass; -class GroupStage implements StageInterface +use function is_string; + +/** + * Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/ + */ +readonly class GroupStage implements StageInterface { public const NAME = '$group'; - public const ENCODE = 'object'; + public const ENCODE = Encode::Group; - public mixed $_id; + /** @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $_id The _id expression specifies the group key. If you specify an _id value of null, or any other constant value, the $group stage returns a single document that aggregates values across all of the input documents. */ + public Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $_id; - /** @param list ...$fields */ - public array $fields; + /** @param stdClass ...$field Computed using the accumulator operators. */ + public stdClass $field; /** - * @param ExpressionInterface|mixed|null $_id - * @param ExpressionInterface|mixed $fields + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass $_id The _id expression specifies the group key. If you specify an _id value of null, or any other constant value, the $group stage returns a single document that aggregates values across all of the input documents. + * @param AccumulatorInterface|Document|Serializable|array|stdClass ...$field Computed using the accumulator operators. */ - public function __construct(mixed $_id, mixed ...$fields) - { + public function __construct( + Type|ExpressionInterface|stdClass|array|bool|float|int|null|string $_id, + Document|Serializable|AccumulatorInterface|stdClass|array ...$field, + ) { $this->_id = $_id; - $this->fields = $fields; + if (\count($field) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $field, got %d.', 1, \count($field))); + } + foreach($field as $key => $value) { + if (! is_string($key)) { + throw new InvalidArgumentException('Expected $field arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + $field = (object) $field; + $this->field = $field; } } diff --git a/src/Builder/Stage/IndexStatsStage.php b/src/Builder/Stage/IndexStatsStage.php new file mode 100644 index 000000000..2a57450bf --- /dev/null +++ b/src/Builder/Stage/IndexStatsStage.php @@ -0,0 +1,25 @@ +limit = $limit; } diff --git a/src/Builder/Stage/ListLocalSessionsStage.php b/src/Builder/Stage/ListLocalSessionsStage.php new file mode 100644 index 000000000..441642e5a --- /dev/null +++ b/src/Builder/Stage/ListLocalSessionsStage.php @@ -0,0 +1,50 @@ +users = $users; + $this->allUsers = $allUsers; + } +} diff --git a/src/Builder/Stage/ListSampledQueriesStage.php b/src/Builder/Stage/ListSampledQueriesStage.php new file mode 100644 index 000000000..000e3fb29 --- /dev/null +++ b/src/Builder/Stage/ListSampledQueriesStage.php @@ -0,0 +1,33 @@ +namespace = $namespace; + } +} diff --git a/src/Builder/Stage/ListSearchIndexesStage.php b/src/Builder/Stage/ListSearchIndexesStage.php new file mode 100644 index 000000000..42446ec8e --- /dev/null +++ b/src/Builder/Stage/ListSearchIndexesStage.php @@ -0,0 +1,40 @@ +id = $id; + $this->name = $name; + } +} diff --git a/src/Builder/Stage/ListSessionsStage.php b/src/Builder/Stage/ListSessionsStage.php new file mode 100644 index 000000000..ed9898c45 --- /dev/null +++ b/src/Builder/Stage/ListSessionsStage.php @@ -0,0 +1,50 @@ +users = $users; + $this->allUsers = $allUsers; + } +} diff --git a/src/Builder/Stage/LookupStage.php b/src/Builder/Stage/LookupStage.php new file mode 100644 index 000000000..98750a99b --- /dev/null +++ b/src/Builder/Stage/LookupStage.php @@ -0,0 +1,90 @@ +as = $as; + $this->from = $from; + $this->localField = $localField; + $this->foreignField = $foreignField; + $this->let = $let; + if (is_array($pipeline) && ! array_is_list($pipeline)) { + throw new InvalidArgumentException('Expected $pipeline argument to be a list, got an associative array.'); + } + + $this->pipeline = $pipeline; + } +} diff --git a/src/Builder/Stage/MatchStage.php b/src/Builder/Stage/MatchStage.php index b17041c11..2902ce407 100644 --- a/src/Builder/Stage/MatchStage.php +++ b/src/Builder/Stage/MatchStage.php @@ -6,20 +6,39 @@ namespace MongoDB\Builder\Stage; -use MongoDB\Builder\Expression\ExpressionInterface; +use MongoDB\BSON\Document; +use MongoDB\BSON\Serializable; +use MongoDB\Builder\Type\Encode; +use MongoDB\Builder\Type\QueryInterface; +use MongoDB\Builder\Type\QueryObject; +use MongoDB\Builder\Type\StageInterface; +use stdClass; -class MatchStage implements StageInterface +use function is_array; +use function is_object; + +/** + * Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match). + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/ + */ +readonly class MatchStage implements StageInterface { public const NAME = '$match'; - public const ENCODE = 'single'; + public const ENCODE = Encode::Single; - public mixed $query; + /** @param Document|QueryInterface|Serializable|array|stdClass $query */ + public Document|Serializable|QueryInterface|stdClass|array $query; /** - * @param ExpressionInterface|mixed $query + * @param Document|QueryInterface|Serializable|array|stdClass $query */ - public function __construct(mixed $query) + public function __construct(Document|Serializable|QueryInterface|stdClass|array $query) { + if (is_array($query) || is_object($query)) { + $query = QueryObject::create($query); + } + $this->query = $query; } } diff --git a/src/Builder/Stage/MergeStage.php b/src/Builder/Stage/MergeStage.php new file mode 100644 index 000000000..4481c58d9 --- /dev/null +++ b/src/Builder/Stage/MergeStage.php @@ -0,0 +1,72 @@ +into = $into; + if (is_array($on) && ! array_is_list($on)) { + throw new InvalidArgumentException('Expected $on argument to be a list, got an associative array.'); + } + + $this->on = $on; + $this->let = $let; + $this->whenMatched = $whenMatched; + $this->whenNotMatched = $whenNotMatched; + } +} diff --git a/src/Builder/Stage/OutStage.php b/src/Builder/Stage/OutStage.php new file mode 100644 index 000000000..d2c14a1b4 --- /dev/null +++ b/src/Builder/Stage/OutStage.php @@ -0,0 +1,49 @@ +db = $db; + $this->coll = $coll; + $this->timeseries = $timeseries; + } +} diff --git a/src/Builder/Stage/PlanCacheStatsStage.php b/src/Builder/Stage/PlanCacheStatsStage.php new file mode 100644 index 000000000..0dcd2f2ad --- /dev/null +++ b/src/Builder/Stage/PlanCacheStatsStage.php @@ -0,0 +1,25 @@ + ...$specifications */ - public array $specifications; + /** @param stdClass ...$specification */ + public stdClass $specification; /** - * @param ExpressionInterface|mixed $specifications + * @param Document|ProjectionInterface|ResolvesToBool|Serializable|array|bool|int|stdClass ...$specification */ - public function __construct(mixed ...$specifications) - { - if (\count($specifications) < 1) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', 1, \count($specifications))); + public function __construct( + Document|Serializable|ResolvesToBool|ProjectionInterface|stdClass|array|bool|int ...$specification, + ) { + if (\count($specification) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $specification, got %d.', 1, \count($specification))); } - - $this->specifications = $specifications; + foreach($specification as $key => $value) { + if (! is_string($key)) { + throw new InvalidArgumentException('Expected $specification arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + $specification = (object) $specification; + $this->specification = $specification; } } diff --git a/src/Builder/Stage/RedactStage.php b/src/Builder/Stage/RedactStage.php new file mode 100644 index 000000000..7f259df5d --- /dev/null +++ b/src/Builder/Stage/RedactStage.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Stage/ReplaceRootStage.php b/src/Builder/Stage/ReplaceRootStage.php new file mode 100644 index 000000000..13b0cdc1e --- /dev/null +++ b/src/Builder/Stage/ReplaceRootStage.php @@ -0,0 +1,36 @@ +newRoot = $newRoot; + } +} diff --git a/src/Builder/Stage/ReplaceWithStage.php b/src/Builder/Stage/ReplaceWithStage.php new file mode 100644 index 000000000..1872d43f8 --- /dev/null +++ b/src/Builder/Stage/ReplaceWithStage.php @@ -0,0 +1,37 @@ +expression = $expression; + } +} diff --git a/src/Builder/Stage/SampleStage.php b/src/Builder/Stage/SampleStage.php new file mode 100644 index 000000000..d11978582 --- /dev/null +++ b/src/Builder/Stage/SampleStage.php @@ -0,0 +1,32 @@ +size = $size; + } +} diff --git a/src/Builder/Stage/SearchMetaStage.php b/src/Builder/Stage/SearchMetaStage.php new file mode 100644 index 000000000..65534b00a --- /dev/null +++ b/src/Builder/Stage/SearchMetaStage.php @@ -0,0 +1,36 @@ +meta = $meta; + } +} diff --git a/src/Builder/Stage/SearchStage.php b/src/Builder/Stage/SearchStage.php new file mode 100644 index 000000000..2e1aedcad --- /dev/null +++ b/src/Builder/Stage/SearchStage.php @@ -0,0 +1,36 @@ +search = $search; + } +} diff --git a/src/Builder/Stage/SetStage.php b/src/Builder/Stage/SetStage.php new file mode 100644 index 000000000..fd92eef96 --- /dev/null +++ b/src/Builder/Stage/SetStage.php @@ -0,0 +1,48 @@ + ...$field */ + public stdClass $field; + + /** + * @param ExpressionInterface|Type|array|bool|float|int|non-empty-string|null|stdClass ...$field + */ + public function __construct(Type|ExpressionInterface|stdClass|array|bool|float|int|null|string ...$field) + { + if (\count($field) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $field, got %d.', 1, \count($field))); + } + foreach($field as $key => $value) { + if (! is_string($key)) { + throw new InvalidArgumentException('Expected $field arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used'); + } + } + $field = (object) $field; + $this->field = $field; + } +} diff --git a/src/Builder/Stage/SetWindowFieldsStage.php b/src/Builder/Stage/SetWindowFieldsStage.php new file mode 100644 index 000000000..e65ee51e4 --- /dev/null +++ b/src/Builder/Stage/SetWindowFieldsStage.php @@ -0,0 +1,62 @@ +partitionBy = $partitionBy; + $this->sortBy = $sortBy; + $this->output = $output; + $this->window = $window; + } +} diff --git a/src/Builder/Stage/ShardedDataDistributionStage.php b/src/Builder/Stage/ShardedDataDistributionStage.php new file mode 100644 index 000000000..f5f39b725 --- /dev/null +++ b/src/Builder/Stage/ShardedDataDistributionStage.php @@ -0,0 +1,26 @@ +skip = $skip; + } +} diff --git a/src/Builder/Stage/SortByCountStage.php b/src/Builder/Stage/SortByCountStage.php new file mode 100644 index 000000000..cc8e02fea --- /dev/null +++ b/src/Builder/Stage/SortByCountStage.php @@ -0,0 +1,35 @@ +expression = $expression; + } +} diff --git a/src/Builder/Stage/SortStage.php b/src/Builder/Stage/SortStage.php index 814d5cf3c..53a8d85d4 100644 --- a/src/Builder/Stage/SortStage.php +++ b/src/Builder/Stage/SortStage.php @@ -7,26 +7,29 @@ namespace MongoDB\Builder\Stage; use MongoDB\BSON\Document; -use MongoDB\BSON\Int64; use MongoDB\BSON\Serializable; +use MongoDB\Builder\Type\Encode; +use MongoDB\Builder\Type\StageInterface; +use stdClass; -class SortStage implements StageInterface +/** + * Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document. + * + * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/ + */ +readonly class SortStage implements StageInterface { public const NAME = '$sort'; - public const ENCODE = 'single'; + public const ENCODE = Encode::Single; - /** @param list ...$sortSpecification */ - public array $sortSpecification; + /** @param Document|Serializable|array|stdClass $sort */ + public Document|Serializable|stdClass|array $sort; /** - * @param Document|Int64|Serializable|array|int|object $sortSpecification + * @param Document|Serializable|array|stdClass $sort */ - public function __construct(array|int|object ...$sortSpecification) + public function __construct(Document|Serializable|stdClass|array $sort) { - if (\count($sortSpecification) < 1) { - throw new \InvalidArgumentException(\sprintf('Expected at least %d values, got %d.', 1, \count($sortSpecification))); - } - - $this->sortSpecification = $sortSpecification; + $this->sort = $sort; } } diff --git a/src/Builder/Stage/StageInterface.php b/src/Builder/Stage/StageInterface.php deleted file mode 100644 index 2e7524f26..000000000 --- a/src/Builder/Stage/StageInterface.php +++ /dev/null @@ -1,7 +0,0 @@ -coll = $coll; + if (is_array($pipeline) && ! array_is_list($pipeline)) { + throw new InvalidArgumentException('Expected $pipeline argument to be a list, got an associative array.'); + } + + $this->pipeline = $pipeline; + } +} diff --git a/src/Builder/Stage/UnsetStage.php b/src/Builder/Stage/UnsetStage.php new file mode 100644 index 000000000..1268b1857 --- /dev/null +++ b/src/Builder/Stage/UnsetStage.php @@ -0,0 +1,44 @@ + ...$field */ + public array $field; + + /** + * @param FieldPath|non-empty-string ...$field + * @no-named-arguments + */ + public function __construct(FieldPath|string ...$field) + { + if (\count($field) < 1) { + throw new \InvalidArgumentException(\sprintf('Expected at least %d values for $field, got %d.', 1, \count($field))); + } + if (! array_is_list($field)) { + throw new InvalidArgumentException('Expected $field arguments to be a list (array), named arguments are not supported'); + } + $this->field = $field; + } +} diff --git a/src/Builder/Stage/UnwindStage.php b/src/Builder/Stage/UnwindStage.php new file mode 100644 index 000000000..95c7272a5 --- /dev/null +++ b/src/Builder/Stage/UnwindStage.php @@ -0,0 +1,53 @@ +path = $path; + $this->includeArrayIndex = $includeArrayIndex; + $this->preserveNullAndEmptyArrays = $preserveNullAndEmptyArrays; + } +} diff --git a/src/Builder/Type/AccumulatorInterface.php b/src/Builder/Type/AccumulatorInterface.php new file mode 100644 index 000000000..be11325bb --- /dev/null +++ b/src/Builder/Type/AccumulatorInterface.php @@ -0,0 +1,12 @@ + $filters */ + public function __construct(public array $filters) + { + foreach ($filters as $filter) { + if (! $filter instanceof FieldQueryInterface && ! $filter instanceof Serializable && ! is_array($filter) && ! $filter instanceof stdClass) { + throw new InvalidArgumentException(sprintf('Expected filters to be a list of %s, %s, array or stdClass, %s given.', FieldQueryInterface::class, Document::class, get_debug_type($filter))); + } + } + } +} diff --git a/src/Builder/Type/Encode.php b/src/Builder/Type/Encode.php new file mode 100644 index 000000000..9f2d5075b --- /dev/null +++ b/src/Builder/Type/Encode.php @@ -0,0 +1,17 @@ +operator = $operator; + + $window = null; + if ($documents !== Optional::Undefined) { + if (! array_is_list($documents) || ! count($documents) === 2) { + throw new InvalidArgumentException('Expected $documents argument to be a list of 2 string or int.'); + } + + $window ??= new stdClass(); + $window->documents = $documents; + } + + if ($range !== Optional::Undefined) { + if (! array_is_list($range) || ! count($range) === 2) { + throw new InvalidArgumentException('Expected $range argument to be a list of 2 string or numeric.'); + } + + $window ??= new stdClass(); + $window->range = $range; + } + + if ($unit !== Optional::Undefined) { + $window ??= new stdClass(); + $window->unit = $unit; + } + + $this->window = $window ?? Optional::Undefined; + } +} diff --git a/src/Builder/Type/ProjectionInterface.php b/src/Builder/Type/ProjectionInterface.php new file mode 100644 index 000000000..b7d0dc6ef --- /dev/null +++ b/src/Builder/Type/ProjectionInterface.php @@ -0,0 +1,12 @@ + $query) { + if ($query instanceof QueryInterface) { + if (! is_numeric($fieldPath)) { + throw new InvalidArgumentException(sprintf('Query operator "%s" cannot be used with a field path. Got "%s".', $query::NAME, $fieldPath)); + } + + if (! $query instanceof self) { + if (isset($seenQueryOperators[$query::NAME])) { + throw new InvalidArgumentException(sprintf('Query operator "%s" cannot be used multiple times in the same query.', $query::NAME)); + } + + $seenQueryOperators[$query::NAME] = true; + } + + $this->queries[] = $query; + continue; + } + + // Convert list of filters into $and + if (self::isListOfFilters($query)) { + if (count($query) === 1) { + $query = $query[0]; + } else { + $query = new CombinedFieldQuery($query); + } + } + + // Numbers are valid field paths, nothing to validate. + $this->queries[$fieldPath] = $query; + } + } + + private static function isListOfFilters(mixed $values): bool + { + if (! is_array($values) || ! array_is_list($values)) { + return false; + } + + foreach ($values as $value) { + if ($value instanceof FieldQueryInterface) { + return true; + } + } + + return false; + } +} diff --git a/src/Builder/Type/StageInterface.php b/src/Builder/Type/StageInterface.php new file mode 100644 index 000000000..bc19f280c --- /dev/null +++ b/src/Builder/Type/StageInterface.php @@ -0,0 +1,12 @@ +` interface that is implemented by the corresponding expression operators, +and a `FieldName` class that is used to build field paths assuming the field is of the given type. + +### Object + +Object expression doesn't accept any PHP `object`, but only `stdClass` and BSON serializable objects. `array` are accepted +because that's the most common way to represent maps in PHP. But we recommend to use `object(... $fields)` helper to +create `stdClass`. It ensures the type is correct for empty arrays or list that would be converted to array instead of +object. + +BSONTypes are skipped when encoding. + +### Type hierarchy + +The most specific interface implements the less specific one. For example, `resolvesToInt` implements `resolvesToLong`, +which implements `resolvesToNumber`, which implements `expression`. + +The type hierarchy is designed with two aspects in mind: the operator parameters and the operator results. + +#### Number + +If an operator resolves to a `number`, we don't know if it is an `int`, a `float`, a `decimal`, or a `long`. +But if it resolves to an `int`, we know it is a `long`, a `number`, and an `expression`. + +If an operator accepts a `number`, it also accepts an `int`, a `float`, a `decimal`, or a `long`. +So we use the `resolvesToNumber` type. As `resolvesToInt` implements `resolvesToNumber`, it is also accepted. + +### Any + +The `resolvesToAny` type means that we don't know the type of the expression. This interface implements all the other +`ResovesTo` interfaces because we can't restrict the expression from being used as parameter for parameters +that requires more specific types. +`resolvesToAny` is only used as result type (as interface for operators class). For parameters, we use the generic +`expression` interface, otherwise only operator resulting in `any` would be eligible, the operators with more specific +result types would be rejected. + +We rely on the server will reject the query if the expression is not of the expected type. + +### Field Path + +FieldPath satisfies any types (implements resolvesToAny interface) because we don't know the type of the field. +Create a FieldPathInterface for encoding needs. + +## Query & Field Query + +The `query` are used in a `$match`, `$geoNear` or `$graphLookup` stages and `$elemMatch` operator. +The `fieldQuery` are used compose query. A query is a map of field name to fieldQuery and/or a list of other queries. + +Queries can be created with `$and`, `$or`, `$nor`, `$jsonSchema`, `$text`, `$comment` operators or with the `QueryObject` +class when composed with `fieldQuery`. +The factory function `Query::query()` accepts variadic arguments which can be named (for `fieldQuery` with field +path) or sequential (for `query` without field path). This function is used by stages that accept a `query` as parameter +to create the `QueryObject`. The encoder handle this object specifically to merge all the queries in a single object. + +We customize the `Stage::match()` factory function to shortcut the `Query::query()` function. +```php +$or = Query::or(...); +$and = Query::and(...); + +['eq' => $eq, 'and' => $and] = Query::functions(); + +Stage::match( + // $or, $and, $nor, $comment, $jsonSchema, $text can't have a field name + // An exception will be thrown if a field name is used + Query::or( + Query::query(foo: Query::eq(...)), + Query::and( + Query::query(bar: Query::eq(...)), + Query::query(baz: Query::eq(...)), + ) + ), + Query::comment('...'), + // Equality query on a field + foo: '...', + // Negate a query with $not + bar: Query::no Query🚬::gt(...)), + // Use array unpacking for complex field path + ...['foo.$.baz' => Query::eq(...)], + // Multiple fieldQueries on the same field + baz: Query::lt(...), Query::gt(...)], +) +``` + +Without the custom factory function for `$match` stage, the queries would be written with a single root query object. +```php +Stage::match(Query::or(Query::query(...), Query::query(...))); +Stage::match(Query::query(...)); +``` + +**Notes:** +- Before PHP 8.1, we cannot combine named arguments and argument unpacking +- Arguments must be provided in this order: sequential arguments, array unpacking positional, array unpacking named, named arguments. +```php +variadic('positional', ...['unpacked positional'], ...['key' => 'unpacked named'], name: 'named'); +``` +- PHP triggers a fatal error if an unpacked named argument conflicts with an other named argument. +```php +variadic(...['name' => 'unpacked named'], name: 'named'); +// Uncaught Error: Named parameter $name overwrites previous argument +``` + +## Projection + +Projection operators have a dedicated namespace and interface to not be confused expression operators with the same +name. + +# Specificities + +Some operators have specificities that are not covered by the generic builder. + +## `$group` stage: required and variadic parameters in the same object + +To encode, the required `_id` parameter is rendered at the same level of the list for fields. + +**Implementation:** The `GroupStage` has a special `Encode::Group` value exploited by the encoder. + +## `$slice` expression operator and `$slice` projection operator: optional values in an array + +These operators are encoded as an array of values. The meaning of the values depends on the number of values. + +https://www.mongodb.com/docs/v7.0/reference/operator/projection/slice/ +https://www.mongodb.com/docs/v7.0/reference/operator/aggregation/slice/ + +## Date Expression Operators + +Concerned operators are: `$dayOfMonth`, `$dayOfWeek`, `$dayOfYear`, `$hour`, `$isoDayOfWeek`, `$isoWeek`, `$isoWeekYear`, +`$millisecond`, `$minute`, `$month`, `$second`, `$week`, `$year`. + +These date expression operators accept have a "date expression" as parameter or an object with +a `date` and an optional `timezone` properties. + +``` +{ : } +{ : { date: } } +{ : { date: , timezone: } } +``` + +In order to normalize encoding, we always use an object with `date` and `timezone` properties and never the short form +even if the timezone is not specified. + +Date Expression can be `ResolveToDate`, `ResolveToTimestamp` or `ResolveToObjectId`. But we don't introduce a new +meta type like `number` or `any` as we can list this types directly in the Yaml config. + +## `$setWindowFields` stage's output + +The output parameter of the `$setWindowFields` stage is an object which mixes a "window operator" and the optional `window` +parameter at the same level. + +Window operators implement the `WindowInterface` interface and are encoded like other operators. + +``` +output: { + : { + : , + window: { + documents: [ , ], + range: [ , ], + unit: