Skip to content

Deprecate extended $out syntax #4986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Deprecate extended $out syntax #4986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4259bc8
Prepare issue branch.
christophstrobl May 28, 2025
e61dba0
Update $out stage rendering to new format.
christophstrobl May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

<groupId>org.springframework.data</groupId>
<artifactId>spring-data-mongodb-parent</artifactId>
<version>5.0.0-SNAPSHOT</version>
<version>5.0.x-GH-4969-SNAPSHOT</version>
<packaging>pom</packaging>

<name>Spring Data MongoDB</name>
Expand Down
2 changes: 1 addition & 1 deletion spring-data-mongodb-distribution/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
<parent>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-mongodb-parent</artifactId>
<version>5.0.0-SNAPSHOT</version>
<version>5.0.x-GH-4969-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>

Expand Down
2 changes: 1 addition & 1 deletion spring-data-mongodb/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<parent>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-mongodb-parent</artifactId>
<version>5.0.0-SNAPSHOT</version>
<version>5.0.x-GH-4969-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>

Expand Down
33 changes: 25 additions & 8 deletions ...mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/OutOperation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,13 +98,15 @@ public OutOperation in(@Nullable String database) {
* .uniqueKey("{ 'field-1' : 1, 'field-2' : 1}")
* </pre>
*
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @param key can be {@literal null}. Server uses {@literal _id} when {@literal null}.
* @return new instance of {@link OutOperation}.
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("_ -> new")
@Deprecated
public OutOperation uniqueKey(@Nullable String key) {

Document uniqueKey = key == null ? null : BsonUtils.toDocumentOrElse(key, it -> new Document(it, 1));
Expand All @@ -123,13 +125,15 @@ public OutOperation uniqueKey(@Nullable String key) {
* .uniqueKeyOf(Arrays.asList("field-1", "field-2"))
* </pre>
*
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @param fields must not be {@literal null}.
* @return new instance of {@link OutOperation}.
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("_ -> new")
@Deprecated
public OutOperation uniqueKeyOf(Iterable<String> fields) {

Assert.notNull(fields, "Fields must not be null");
Expand All @@ -142,13 +146,15 @@ public OutOperation uniqueKeyOf(Iterable<String> fields) {

/**
* Specify how to merge the aggregation output with the target collection. <br />
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @param mode must not be {@literal null}.
* @return new instance of {@link OutOperation}.
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("_ -> new")
@Deprecated
public OutOperation mode(OutMode mode) {

Assert.notNull(mode, "Mode must not be null");
Expand All @@ -157,39 +163,45 @@ public OutOperation mode(OutMode mode) {

/**
* Replace the target collection. <br />
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @return new instance of {@link OutOperation}.
* @see OutMode#REPLACE_COLLECTION
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("-> new")
@Deprecated
public OutOperation replaceCollection() {
return mode(OutMode.REPLACE_COLLECTION);
}

/**
* Replace/Upsert documents in the target collection. <br />
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @return new instance of {@link OutOperation}.
* @see OutMode#REPLACE
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("-> new")
@Deprecated
public OutOperation replaceDocuments() {
return mode(OutMode.REPLACE);
}

/**
* Insert documents to the target collection. <br />
* <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
* <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
*
* @return new instance of {@link OutOperation}.
* @see OutMode#INSERT
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Contract("-> new")
@Deprecated
public OutOperation insertDocuments() {
return mode(OutMode.INSERT);
}
Expand All @@ -198,7 +210,10 @@ public OutOperation insertDocuments() {
public Document toDocument(AggregationOperationContext context) {

if (!requiresMongoDb42Format()) {
return new Document("$out", collectionName);
if (!StringUtils.hasText(databaseName)) {
return new Document(getOperator(), collectionName);
}
return new Document(getOperator(), new Document("db", databaseName).append("coll", collectionName));
}

Assert.state(mode != null, "Mode must not be null");
Expand All @@ -223,15 +238,17 @@ public String getOperator() {
}

private boolean requiresMongoDb42Format() {
return StringUtils.hasText(databaseName) || mode != null || uniqueKey != null;
return mode != null || uniqueKey != null;
}

/**
* The mode for merging the aggregation pipeline output.
*
* @author Christoph Strobl
* @since 2.2
* @deprecated no longer applicable for MongoDB 5+
*/
@Deprecated
public enum OutMode {

/**
Expand Down
14 changes: 8 additions & 6 deletions ...src/test/java/org/springframework/data/mongodb/core/aggregation/OutOperationUnitTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@
*/
package org.springframework.data.mongodb.core.aggregation;

import static org.springframework.data.mongodb.core.aggregation.Aggregation.*;
import static org.springframework.data.mongodb.test.util.Assertions.*;
import static org.springframework.data.mongodb.core.aggregation.Aggregation.out;
import static org.springframework.data.mongodb.test.util.Assertions.assertThat;
import static org.springframework.data.mongodb.test.util.Assertions.assertThatIllegalArgumentException;

import java.util.Arrays;

Expand Down Expand Up @@ -84,11 +85,12 @@ public void shouldRenderExtendedFormatWithMultiFieldKey() {
.containsEntry("$out.uniqueKey", new Document("field-1", 1).append("field-2", 1));
}

@Test // DATAMONGO-2259
public void shouldErrorOnExtendedFormatWithoutMode() {
@Test // DATAMONGO-2259, GH-4969
public void shouldRenderNewExtendedFormatWithoutMode() {

assertThatThrownBy(() -> out("out-col").in("database-2").toDocument(Aggregation.DEFAULT_CONTEXT))
.isInstanceOf(IllegalStateException.class);
assertThat(out("out-col").in("database-2").toDocument(Aggregation.DEFAULT_CONTEXT))
.containsEntry("$out.coll", "out-col") //
.containsEntry("$out.db", "database-2");
}

}