Skip to content

Commit 87e7664

Browse files
kay-kimjyemin
kay-kim
authored and
jyemin
committed
DOCS-8718, DOCS-8762 3.4 collation and decimal128
1 parent 89d9515 commit 87e7664

File tree

1 file changed

+144
-11
lines changed

1 file changed

+144
-11
lines changed

‎docs/reference/content/whats-new.md‎

Lines changed: 144 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,152 @@ title = "What's New"
77
pre = "<i class='fa fa-level-up'></i>"
88
+++
99

10-
# What's New in 3.3
10+
# What's New
1111

12-
New features of the 3.3 driver include:
12+
Some key new features of the Java driver and Java Async driver include:
13+
14+
### Support for Decimal128 Format
15+
16+
``` java
17+
import org.bson.types.Decimal128;
18+
```
19+
20+
The `Decimal128` format supports numbers with up to 34 decimal digits
21+
(i.e. significant digits) and an exponent range of −6143 to +6144.
22+
23+
To create a `Decimal128` number, you can use
24+
25+
- [`Decimal128.parse()`] ({{<apiref "org/bson/types/Decimal128.html">}}) with a string:
26+
27+
```java
28+
Decimal128.parse("9.9900");
29+
```
30+
31+
- [`new Decimal128()`] ({{<apiref "org/bson/types/Decimal128.html">}}) with a long:
32+
33+
34+
```java
35+
new Decimal128(10L);
36+
```
37+
38+
- [`new Decimal128()`] ({{<apiref "org/bson/types/Decimal128.html">}}) with a `java.math.BigDecimal`:
39+
40+
```java
41+
new Decimal128(new BigDecimal("4.350000"));
42+
```
43+
44+
### Support for Collation
45+
46+
```java
47+
import com.mongodb.client.model.Collation;
48+
```
49+
50+
[Collation]({{<docsref "release-notes/3.3-dev-series-collation/">}}) allows users to specify language-specific rules for string
51+
comparison.
52+
Use the [`Collation.builder()`] ({{<apiref "com/mongodb/client/model/Collation.html">}})
53+
to create the `Collation` object. For example, the following example creates a `Collation` object with Primary level of comparison and [locale]({{<docsref "release-notes/3.3-dev-series-collation/#supported-languages-and-locales">}}) ``fr``.
54+
55+
```java
56+
Collation.builder().collationStrength(CollationStrength.PRIMARY).locale("fr").build()));
57+
```
58+
59+
You can specify collation at the collection level, at an index level, or at a collation-supported operation level:
60+
61+
#### Collection Level
62+
63+
To specify collation at the collection level, pass a `Collation` object as an option to the `createCollection()` method. To specify options to the `createCollection` method, use the [`CreateCollectionOptions`]({{<apiref "com/mongodb/client/model/CreateCollectionOptions.html">}}) class.
64+
65+
```java
66+
database.createCollection("myColl", new CreateCollectionOptions().collation(
67+
Collation.builder()
68+
.collationStrength(CollationStrength.PRIMARY)
69+
.locale("fr").build()));
70+
```
71+
72+
#### Index Level
73+
74+
To specify collation for an index, pass a `Collation` object as an option to the `createIndex()` method. To specify index options, use the [IndexOptions]({{<apiref "com/mongodb/client/model/IndexOptions.html">}}) class.
75+
76+
```java
77+
IndexOptions collationIndexOptions = new IndexOptions().name("collation-fr")
78+
.collation(Collation.builder()
79+
.collationStrength(CollationStrength.SECONDARY)
80+
.locale("fr").build());
81+
82+
collection.createIndex(
83+
Indexes.ascending("name"), collationIndexOptions);
84+
```
85+
86+
#### Operation Level
87+
88+
The following operations support collation by specifying the
89+
`Collation` object to their respective Iterable object.
90+
91+
- `MongoCollection.aggregate()`
92+
93+
- `MongoCollection.distinct()`
94+
95+
- `MongoCollection.find()`
96+
97+
- `MongoCollection.mapReduce()`
98+
99+
For example:
100+
101+
```java
102+
Collation collation = Collation.builder()
103+
.collationStrength(CollationStrength.SECONDARY)
104+
.locale("fr").build();
105+
106+
collection.find(Filters.eq("category", "cafe")).collation(collation);
107+
108+
collection.aggregate(Arrays.asList(
109+
Aggregates.group("$category", Accumulators.sum("count", 1))))
110+
.collation(collation);
111+
112+
```
113+
114+
The following operations support collation by specifying the
115+
`Collation` object as an option using the corresponding option class
116+
for the method:
117+
118+
- `MongoCollection.count()`
119+
- `MongoCollection.deleteOne()`
120+
- `MongoCollection.deleteMany()`
121+
- `MongoCollection.findOneAndDelete()`
122+
- `MongoCollection.findOneAndReplace()`
123+
- `MongoCollection.findOneAndUpdate()`
124+
- `MongoCollection.updateOne()`
125+
- `MongoCollection.updateMany()`
126+
- `MongoCollection.bulkWrite()` for:
127+
128+
- `DeleteManyModel` and `DeleteOneModel` using `DeleteOptions` to specify the collation
129+
- `ReplaceOneModel`, `UpdateManyModel`, and `UpdateOneModel` using `UpdateOptions` to specify the collation.
130+
131+
For example:
132+
133+
```java
134+
Collation collation = Collation.builder()
135+
.collationStrength(CollationStrength.SECONDARY)
136+
.locale("fr").build();
137+
138+
collection.count(Filters.eq("category", "cafe"), new CountOptions().collation(collation));
139+
140+
collection.updateOne(Filters.eq("category", "cafe"), set("stars", 1),
141+
new UpdateOptions().collation(collation));
142+
143+
collection.bulkWrite(Arrays.asList(
144+
new UpdateOneModel<>(new Document("category", "cafe"),
145+
new Document("$set", new Document("x", 0)),
146+
new UpdateOptions().collation(collation)),
147+
new DeleteOneModel<>(new Document("category", "cafe"),
148+
new DeleteOptions().collation(collation))));
149+
```
150+
151+
152+
For more information on collation, including the supported locales, refer to the
153+
[manual]({{<docsref "release-notes/3.3-dev-series-collation/">}}).
13154

14-
- [Cluster Monitoring]({{<ref "driver/reference/monitoring.md#cluster-monitoring">}}) in the synchronous and asynchronous
15-
drivers
16-
- [Command Monitoring]({{<ref "driver-async/reference/monitoring.md#command-monitoring">}}) in the asynchronous driver
17-
(support in the synchronous driver was added in a previous release)
18-
- Additional query parameters in the [connection string]({{<ref "driver/tutorials/connect-to-mongodb.md">}})
19-
- [GridFS]({{<ref "driver-async/tutorials/gridfs.md">}}) in the asynchronous driver
20-
- Additional configuration options for [GSSAPI authentication]({{<ref "driver/tutorials/authentication.md#gssapi">}}).
21-
- [JNDI]({{<ref "driver/tutorials/jndi.md">}}) ObjectFactory implementation
22155

23156
## Upgrading
24157

25-
See the [upgrading guide]({{<ref "upgrading.md">}}) on how to upgrade to 3.3.
158+
See the [upgrading guide]({{<ref "upgrading.md">}}) on how to upgrade to 3.4.

0 commit comments

Comments
 (0)