MongoPlus

https://mongoplus.com/
Admin
MongoPlus is a MongoDB operation tool that enables elegant MongoDB operations using...
Tokens:16,486
Snippets:192
Trust Score:5.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Console Output of User Data

Source: https://mongoplus.com/docs/noEntity.html

Example console output showing the retrieved user data, where each record is represented as a User object.

```log
User(id=1, name=Jone, age=18, email=test1@mongoplus.com)
User(id=2, name=Jack, age=20, email=test2@mongoplus.com)
User(id=3, name=Tom, age=28, email=test3@mongoplus.com)
User(id=4, name=Sandy, age=21, email=test4@mongoplus.com)
User(id=5, name=Billie, age=24, email=test5@mongoplus.com)
```

--------------------------------

### Ignore Logic Deletion for Document Example (Java)

Source: https://mongoplus.com/docs/logic.html

Example showing how to use the @IgnoreLogic annotation on a document class to prevent it from participating in global logic deletion configurations.

```java
@CollectionName(value = "mongoTest")
// 标记该文档不进行逻辑删除操作
@IgnoreLogic
public class MongoTest {

    @ID(type = IdTypeEnum.AUTO)
    private String id;

    private String userName;
    
    private String logic;

}
```

--------------------------------

### Ignore Logic Deletion for Method Example (Java)

Source: https://mongoplus.com/docs/logic.html

Example demonstrating how to use the @IgnoreLogic annotation on a method to exclude its operations from logic deletion.

```java
// 此方法,忽略逻辑删除
@IgnoreLogic
public void ignore() {
  List<Object> result = mapper.list();
}
```

--------------------------------

### Build OR Conditions with Lambda

Source: https://mongoplus.com/docs/conditionBuild.html

Example of building an OR condition using a lambda function. This constructs a query with multiple OR clauses.

```java
or(wrapper -> wrapper.eq(User::getUserName,"张三").like(User::getUserName,"1"))
```

--------------------------------

### Build OR Conditions with Combine

Source: https://mongoplus.com/docs/conditionBuild.html

Example of building an OR condition using the combine method. This groups conditions within a single object.

```java
or(wrapper ->
    wrapper.combine(combineWrapper ->
      combineWrapper.eq(User::getUserName,"张三").like(User::getUserName,"1")
    )
  )
```

--------------------------------

### Custom Logic Deletion Field Example (Java)

Source: https://mongoplus.com/docs/logic.html

Example demonstrating how to use the @CollectionLogic annotation to define a custom logic deletion field named 'logic' with specific delete and non-delete values.

```java
@CollectionName(value = "mongoTest")
public class MongoTest {

    @ID(type = IdTypeEnum.AUTO)
    private String id;

    private String userName;

    /**
     * 标记该文档不适用全局配置的 logicDel
     * 使用 logic 作为逻辑删除字段，true=逻辑删除，false=逻辑未删除
     */
    @CollectionLogic(value = "true", delval = "false")
    private String logic;

}
```

--------------------------------

### Programmatic Logic Deletion Exclusion (Java)

Source: https://mongoplus.com/docs/logic.html

Example illustrating how to programmatically ignore logic deletion for specific operations within a block of code using LogicManager.withoutLogic.

```java
public void ignore() {
  List<Object> result1 = mapper.list();
  // 细粒度忽略逻辑删除
  LogicManager.withoutLogic(() -> {
    List<Object> result2 = mapper.list();
  });
}
```

--------------------------------

### Like Condition (like)

Source: https://mongoplus.com/docs/conditionBuild.html

Performs a LIKE query with a wildcard at both ends. Example: like("name", "王") results in name LIKE '%王%'.

```java
like(SFunction<T,Object> column, Object val)
like(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Like Left Condition (likeLeft)

Source: https://mongoplus.com/docs/conditionBuild.html

Performs a LIKE query with a wildcard at the beginning. Example: likeLeft("name", "^王") results in name LIKE '%王'.

```java
likeLeft(SFunction<T,Object> column, Object val)
likeLeft(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Like Right Condition (likeRight)

Source: https://mongoplus.com/docs/conditionBuild.html

Performs a LIKE query with a wildcard at the end. Example: likeRight("name", "王$") results in name LIKE '王%'.

```java
likeRight(SFunction<T,Object> column, Object val)
likeRight(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Equality Condition (eq)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks for equality between a column and a value. Example: eq("name", "老王") results in name = '老王'.

```java
eq(SFunction<T,Object> column, Object val)
eq(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Get Field Names with FunctionUtil

Source: https://mongoplus.com/docs/nestedField.html

FunctionUtil can retrieve field names for both top-level and nested fields. Use `getFieldName` for standard names and `getFieldNameOption` to prepend a '$'.

```java
public class User {
    private String userName;
}

public static void main(String[] args) {
    // 调用获取字段名方法,如@CollectionField注解指定了字段名，则返回注解值
    String fieldName = FunctionUtil.getFieldName(User::getUserName)
    // 打印为：userName
    System.out.println(fieldName);

    // -------------------------------------------------------------------

    // 调用获取字段名方法,如@CollectionField注解指定了字段名，则返回注解值
    String fieldName = FunctionUtil.getFieldNameOption(User::getUserName)
    // 打印为：$userName
    System.out.println(fieldName);
}
```

--------------------------------

### Custom Condition with BasicDBObject

Source: https://mongoplus.com/docs/conditionBuild.html

Use BasicDBObject for custom query conditions. Example: new BasicDBObject("$eq", new BasicDBObject("_id","1"))

```java
custom(BasicDBObject basicDBObject);
custom(BSON bson);
```

--------------------------------

### Order By Ascending

Source: https://mongoplus.com/docs/conditionBuild.html

Sorts results in ascending order by specified columns. Example: orderByAsc("id", "name") results in ORDER BY id ASC, name ASC.

```java
orderByAsc(SFunction<T,Object> columns)
orderByAsc(boolean condition, SFunction<T,Object> columns)
```

--------------------------------

### In Condition with Collection

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is present in a collection. Example: in("age", {1,2,3}) results in age IN (1,2,3).

```java
in(SFunction<T,Object> column, Collection<?> value)
in(boolean condition, SFunction<T,Object> column, Collection<?> value)
```

--------------------------------

### Inequality Condition (ne)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks for inequality between a column and a value. Example: ne("name", "老王") results in name <> '老王'.

```java
ne(SFunction<T,Object> column, Object val)
ne(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Not In Condition (nin)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is NOT present in a collection. Example: notIn("age", {1,2,3}) results in age NOT IN (1,2,3).

```java
nin(SFunction<T,Object> column , Collection<Object> valueList)
nin(boolean condition , String column , Collection<Object> valueList)
```

--------------------------------

### Order By Descending

Source: https://mongoplus.com/docs/conditionBuild.html

Sorts results in descending order by specified columns. Example: orderByDesc("id", "name") results in ORDER BY id DESC, name DESC.

```java
orderByDesc(SFunction<T,Object> columns)
orderByDesc(boolean condition, SFunction<T,Object>... columns)
```

--------------------------------

### Less Than Condition (lt)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is less than a specified value. Example: lt("age", 18) results in age < 18.

```java
lt(SFunction<T,Object> column, Object val)
lt(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Less Than or Equal To Condition (lte)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is less than or equal to a specified value. Example: lte("age", 18) results in age <= 18.

```java
lte(SFunction<T,Object> column, Object val)
lte(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### In Condition with Varargs

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is present in a list of values. Example: in("age", 1, 2, 3) results in age IN (1,2,3).

```java
in(SFunction<T,Object> column, Object... values)
in(boolean condition, SFunction<T,Object> column, Object... values)
```

--------------------------------

### Greater Than Condition (gt)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is greater than a specified value. Example: gt("age", 18) results in age > 18.

```java
gt(SFunction<T,Object> column, Object val)
gt(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Greater Than or Equal To Condition (gte)

Source: https://mongoplus.com/docs/conditionBuild.html

Checks if a column's value is greater than or equal to a specified value. Example: gte("age", 18) results in age >= 18.

```java
gte(SFunction<T,Object> column, Object val)
gte(boolean condition, SFunction<T,Object> column, Object val)
```

--------------------------------

### Add MongoPlus and Spring Boot Dependencies

Source: https://mongoplus.com/docs/started.html

Incorporate the necessary MongoPlus and Spring Boot starter dependencies, along with the BOM for version management.

```xml
<dependencyManagement>
    <dependencies>
        <!-- mongoplus-bom -->
        <dependency>
            <groupId>com.mongoplus</groupId>
            <artifactId>mongo-plus-bom</artifactId>
            <version>2.1.9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- mongoplus依赖 -->
    <dependency>
        <groupId>com.mongoplus</groupId>
        <artifactId>mongo-plus-boot-starter</artifactId>
    </dependency>
</dependencies>
```

--------------------------------

### Add MongoPlus Dependencies

Source: https://mongoplus.com/

Include the MongoPlus BOM for dependency management and the appropriate starter for your framework (e.g., Spring Boot or Solon).

```xml
<dependencyManagement>
    <dependencies>
        <!-- mongoplus-bom -->
        <dependency>
            <groupId>com.mongoplus</groupId>
            <artifactId>mongo-plus-bom</artifactId>
            <version>2.1.9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- springboot -->
<dependency>
    <groupId>com.mongoplus</groupId>
    <artifactId>mongo-plus-boot-starter</artifactId>
</dependency>
<!-- solon -->
<dependency>
    <groupId>com.mongoplus</groupId>
    <artifactId>mongo-plus-solon-plugin</artifactId>
</dependency>
```

--------------------------------

### Configure MongoDB Connection in application.yml

Source: https://mongoplus.com/docs/started.html

Set up your MongoDB connection details, including host, port, database name, and authentication credentials, in the application.yml file.

```yaml
#DataSource Config
mongo-plus:
  data:
    mongodb:
      host: 127.0.0.1   #ip
      port: 27017   #端口
      database: test    #数据库名
      username: test    #用户名，没有可不填（若账号中出现@,!等等符号，不需要再进行转码！！！）
      password: test    #密码，同上（若密码中出现@,!等等符号，不需要再进行转码！！！）
      authenticationDatabase: admin     #验证数据库
      connectTimeoutMS: 50000   #在超时之前等待连接打开的最长时间（以毫秒为单位）
```

--------------------------------

### Banner Display Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Control the display of the MongoPlus banner on startup. Includes an option to enable a special 'ikun' mode.

```yaml
mongo-plus:
  configuration:
    banner: false
    ikun: true
```

--------------------------------

### Encryption Global Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Set up global encryption keys for asymmetric (private/public keys) and symmetric (key) encryption.

```yaml
mongo-plus:
  encryptor:
    privateKey: XXX
    publicKey: XXX
    key: XXX
```

--------------------------------

### Configure MongoDB Connection with MongoPlus

Source: https://mongoplus.com/docs/noEntity.html

Set up the MongoDB connection details in the application.yml file, including host, port, database name, and authentication credentials.

```yaml
#DataSource Config
mongo-plus:
  data:
    mongodb:
      host: 127.0.0.1   #ip
      port: 27017   #端口
      database: test    #数据库名
      username: test    #用户名，没有可不填
      password: test    #密码，同上
      authenticationDatabase: admin     #验证数据库
      connectTimeoutMS: 50000   #在超时之前等待连接打开的最长时间（以毫秒为单位）
```

--------------------------------

### Implement User Service

Source: https://mongoplus.com/docs/started.html

Implement the UserService by extending MongoPlus's ServiceImpl, similar to MyBatis-Plus.

```java
public class UserServiceImpl extends ServiceImpl<User> implements UserService {
    
}
```

--------------------------------

### Basic MongoDB Connection Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Configure essential MongoDB connection details such as host, port, username, password, and database. Includes options for connection timeout and authentication database.

```yaml
mongo-plus:
  data:
    mongodb:
      host: 127.0.0.1
      port: 27017
      username: root
      password: root
      database: mp
      connectTimeoutMS: 50000
      authenticationDatabase: admin
  log: true
```

--------------------------------

### Logging Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Enable and configure logging for MongoPlus. Options include enabling general log output, specifying log order, formatting logs, and pretty-printing commands.

```yaml
mongo-plus:
  log: true
  format: true
  pretty: true
```

--------------------------------

### Add Core Spring Boot and MongoPlus Dependencies

Source: https://mongoplus.com/docs/noEntity.html

Incorporate the necessary dependencies for a Spring Boot application, including testing support and the MongoPlus starter for MongoDB integration.

```xml
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.gitee.anwena</groupId>
        <artifactId>mongo-plus-boot-starter</artifactId>
        <version>最新版本</version>
    </dependency>
</dependencies>
```

--------------------------------

### Add Spring Boot Starter Parent Dependency

Source: https://mongoplus.com/docs/noEntity.html

Include the Spring Boot Starter parent POM to manage dependencies and configurations for your Spring Boot application.

```xml
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6+ 版本</version>
    <relativePath/>
</parent>
```

--------------------------------

### Perform Local Data Backup and Import with BackupManager

Source: https://mongoplus.com/docs/dataBackup.html

Utilize the `BackupManager` class to perform local backups of MongoDB collections by exporting documents to JSON files, which are then zipped. It also supports importing data from these zip archives, including deleting existing collections before import.

```java
import org.springframework.stereotype.Component;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import javax.annotation.Resource;

import com.mongodb.MongoNamespace;
import com.mongodb.client.MongoPlusClient;
import com.mongodb.client.model.BackupManager;
import com.mongodb.client.model.User;
import com.mongodb.client.model.Role;

import lombok.extern.slf4j.Slf4j;

@Component
@Slf4j
public class Backup {
    @Resource
    private MongoPlusClient mongoPlusClient;

    public void backupTest() {
        String path = "/usr/local/backup/";
        //BackupManager backupManager = new BackupManager(path, Arrays.asList("user", "role"), mongoPlusClient);
        BackupManager backupManager = new BackupManager(mongoPlusClient);
        // 设置每页行数
        backupManager.setLimit(1000);
        // 设置需要备份的集合，可以通过构建BackupManager的构造参数传递List<String>
        backupManager.setCollectionNames(Arrays.asList(User.class, Role.class));
        // 设置需要备份的数据源，默认当前数据源
        backupManager.setDataSourceName("master");
        // 设置备份监听器，每条数据都会回调该方法
        backupManager.setBackupListeners((targetPath, collectionName, document) -> 
                log.info("path: {},collectionName: {},document: {}", 
                        targetPath,
                        collectionName,
                        document.toJson()
                )
        );
        // 执行备份
        Map<String,String> backupResult = backupManager.export();
        backupResult.forEach((key, value) -> System.out.println("collectionName: "+key+"| path: "+value));
        // 执行导入
        backupManager.imports(".zip");
    }

}
```

--------------------------------

### Collection Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Configure collection naming strategies and enable protection against full collection updates or deletions.

```yaml
mongo-plus:
  configuration:
    collection:
      mappingStrategy: CLASS_NAME
      block-attack-inner: true
```

--------------------------------

### Create User Service Interface

Source: https://mongoplus.com/docs/started.html

Define a UserService interface that extends MongoPlus's IService for basic CRUD operations.

```java
public interface UserService extends IService<User> {
        
}
```

--------------------------------

### Auto Time-Series Collection Creation Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Enable or disable the automatic creation of time-series collections.

```yaml
mongo-plus:
  configuration:
    autoCreateTimeSeries: true
```

--------------------------------

### Field Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Customize field mapping strategies. Enable camel case to underscore conversion and control whether null fields are ignored during operations.

```yaml
mongo-plus:
  configuration:
    field:
      camelToUnderline: true
      ignoringNull: false
```

--------------------------------

### Configure Global Logic Deletion Settings (YAML)

Source: https://mongoplus.com/docs/logic.html

Configure global logic deletion settings in the application's YAML configuration file. This enables the feature and allows customization of the delete field, values, and data type.

```yaml
mongo-plus:
  configuration:
    logic:
      open: true                    # 开启逻辑删除功能
      auto-fill: true               # 开启拦截器自动填充逻辑删除字段（开启逻辑删除功能前提下生效，推荐使用数据库默认字段以及实体默认字段，减少对文档的拦截修改）
      logic-delete-field: logicDel  # 全局逻辑删除字段（默认string 类型）
      logic-delete-value: 1         # 标记逻辑删除值
      logic-not-delete-value: 0     # 标记逻辑未删除值
      logic-data-type: integer      # 重新指定数据类型为Integer
```

--------------------------------

### MongoDB URL Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Configure the MongoDB connection using a full URL, which overrides individual host and port settings. This is useful for SSL connections.

```yaml
mongo-plus:
  data:
    mongodb:
      url: mongodb://test:test@127.0.0.1:27017/admin?connectTimeoutMS=50000
      database: mp
```

--------------------------------

### Configure OptimisticLockerInterceptor

Source: https://mongoplus.com/docs/optimisticLocker.html

Configure the OptimisticLockerInterceptor bean with custom exceptions for update failures and missing version fields, set auto-increment value, and enable retry strategy.

```java
import com.mongoplus.exception.MongoPlusException;
import com.mongoplus.interceptor.OptimisticLockerInterceptor;
import com.mongoplus.retry.Retry;
import org.springframework.context.annotation.Bean;

public class MongoPlusConfig {

    @Bean
    public OptimisticLockerInterceptor optimisticLockerInterceptor(){
        OptimisticLockerInterceptor optimisticLockerInterceptor = new OptimisticLockerInterceptor();
        // 修改失败后是否抛出异常抛出异常
        optimisticLockerInterceptor.setUpdateFailException(new RuntimeException("修改失败"));
        // 未获取到乐观锁字段是否抛出异常
        optimisticLockerInterceptor.setVersionIsNullException(new MongoPlusException("未获取到乐观锁字段"));
        // 设置乐观锁自增值
        optimisticLockerInterceptor.setAutoInc(1);
        // 是否开启重试
        optimisticLockerInterceptor.enableRetry(getRetryStrategy());
        return optimisticLockerInterceptor;
    }

    /**
     * 获取重试策略
     */
    Retry getRetryStrategy() {
        return Retry.builder()
                // 最大重试次数
                .maxRetryNum(10)
                // 首次命中回调
                .hitRetry(updateRetryResult -> System.out.println("首次命中: " + updateRetryResult))
                // 修改成功回调
                .onSuccess(object -> System.out.println("修改成功: " + object))
                // 修改失败回调
                .onFailure(object -> System.out.println("修改失败: " + object))
                // 达到最大重试次数失败后的备用逻辑
                .fallback(((updateRetryResult, invocation) -> {
                    try {
                        return invocation.proceed();
                    } catch (Throwable e) {
                        throw new RuntimeException(e);
                    }
                }))
                // 每次重试增加version值
                .autoVersionNum(1)
                // 重试是否继续执行后续拦截器，默认为true
                // 如果后续的执行器中，进行了某些操作，请将该属性设置为false。比如在后续拦截器中做了修改其他表的操作，在重试时则会修改多次
                .processIntercept(true)
                // 重试间隔时间
                .retryInterval(100L)
                // 开启异步重试
                // 启异步后，会立即返回当前更新失败的响应，并且异步的重试，不受事务控制。可以通过回调配置查看最终结果
                .asyncRetry(true)
                .build();
    }
}
```

--------------------------------

### Test MongoDB Operations with BaseMapper

Source: https://mongoplus.com/docs/noEntity.html

Demonstrates how to use BaseMapper to perform a 'list' operation on a MongoDB collection without an entity class, returning results as a list of Maps.

```java
@SpringBootTest
public class SampleTest {

    @Autowired
    //private MongoPlusMapMapper mongoPlusMapMapper;
    private BaseMapper baseMapper;

    @Test
    public void testSelect() {
        System.out.println(("----- selectAll method test ------"));
        // List<Map<String,Object>> userList = mongoPlusMapMapper.list("user");
        List<Map<String, Object>> userList = baseMapper.list("asd", new TypeReference<Map<String, Object>>() {});
        userList.forEach(System.out::println);

    }

}
```

--------------------------------

### Configure Async Multiple Write Interceptor in MongoPlus

Source: https://mongoplus.com/docs/dataBackup.html

Set up the `AsyncMultipleWriteInterceptor` to automatically write data to specified data sources based on operation types (SAVE, REMOVE, UPDATE, BULK_WRITE). This ensures data consistency across multiple databases.

```java
import org.springframework.context.annotation.Bean;

import java.util.Arrays;

import com.mongodb.client.MongoPlusClient;
import com.mongodb.client.model.MultipleWrite;
import com.mongodb.client.model.AsyncMultipleWriteInterceptor;

@Bean
public AsyncMultipleWriteInterceptor multipleWriteInterceptor(MongoPlusClient mongoPlusClient,
                                                                MongoMultipleWriteHandler multipleWriteHandler){
    // 添加策略
    // save时，向test1和test2写入
    multipleWriteHandler.addMultipleWriteStrategy(MultipleWrite.SAVE, Arrays.asList("test1","test2"));
    // remove时，向test1和test2写入
    multipleWriteHandler.addMultipleWriteStrategy(MultipleWrite.REMOVE, Arrays.asList("test1","test2"));
    // update时，向test1和test2写入
    multipleWriteHandler.addMultipleWriteStrategy(MultipleWrite.UPDATE, Arrays.asList("test1","test2"));
    // bulkWrite时，向test1和test2写入
    multipleWriteHandler.addMultipleWriteStrategy(MultipleWrite.BULK_WRITE, Arrays.asList("test1","test2"));
    return new AsyncMultipleWriteInterceptor(mongoPlusClient,multipleWriteHandler);
}
```

--------------------------------

### Logical Deletion Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Configure the logical deletion feature, including enabling it, auto-filling fields, and defining the field name and values for deleted/non-deleted states.

```yaml
mongo-plus:
  configuration:
    logic:
      open: true
      auto-fill: true
      logic-delete-field: logicDel
      logic-delete-value: 1
      logic-not-delete-value: 0
      logic-data-type: integer
```

--------------------------------

### Auto Index Creation Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Enable or disable the automatic creation of indexes for your MongoDB collections.

```yaml
mongo-plus:
  configuration:
    autoCreateIndex: true
```

--------------------------------

### Enable Auto Create Index Configuration

Source: https://mongoplus.com/docs/autoCreateIndex.html

Configure MongoPlus to automatically create indexes by setting 'auto-create-index' to true. For multi-module projects with different package names, specify the sub-package paths containing index entities in 'auto-scan-packages'.

```yaml
mongo-plus:
    configuration:
        auto-create-index: true #开启自动创建索引功能
        auto-scan-packages: # 多模块且包名不同,需要指定子包的包路径
          - com.xxxx.entity
          - com.xxxx.entity1
```

--------------------------------

### Create a Geo Index with @MongoGeoIndex

Source: https://mongoplus.com/docs/autoCreateIndex.html

Use the @MongoGeoIndex annotation to create a geospatial index, specifying either 'SPHERE' (2dsphere) or '2d' index type. This is essential for location-based queries.

```java
@CollectionName("user")
public class User {
    // 指定创建2dsphere索引
    @MongoGeoIndex(type = GeoType.SPHERE)
    private Geometry location;
}
```

--------------------------------

### Build Nested Field Names with FunctionUtil

Source: https://mongoplus.com/docs/nestedField.html

Use FunctionUtil's builder to construct nested field names. The `build(true)` option prepends a '$' to the field name.

```java
public class User {
    private Role role;
}
public class Role {
    private String roleName;
}

public static void main(String[] args) {
    //调用构建嵌套文档对象
    FunctionBuilder builder = FunctionUtil.builderFunction();
    //调用`add`方法添加字段到FunctionBuilder对象
    builder.add(User::getRole).add(Role::getRoleName);
    //调用build方法构建字段
    String fieldName = builder.build();
    // 打印为 role.roleName
    System.out.println(fieldName);

    // -------------------------------------------------------------------

    //调用build方法构建带$字段
    String fieldNameOption = builder.build(true);
    // 打印为 $role.roleName
    System.out.println(fieldNameOption);
}
```

--------------------------------

### Create a Hash Index with @MongoHashIndex

Source: https://mongoplus.com/docs/autoCreateIndex.html

Apply the @MongoHashIndex annotation to a field to create a hash-based index. This is suitable for equality queries.

```java
@CollectionName("user")
public class User {
    @MongoHashIndex
    private String userName;
}
```

--------------------------------

### User Service Test with Spring Boot

Source: https://mongoplus.com/docs/started.html

This Java test class uses Spring Boot's @SpringBootTest annotation to test the UserService. It demonstrates fetching all users from the database and printing them to the console. Ensure UserService is correctly configured and autowired.

```java
@SpringBootTest
public class SampleTest {

    @Autowired
    private UserService userService;

    @Test
    public void testSelect() {
        System.out.println(("----- selectAll method test ------"));
        List<User> userList = userService.list();
        userList.forEach(System.out::println);
    }

}
```

--------------------------------

### Create a Text Index with @MongoTextIndex

Source: https://mongoplus.com/docs/autoCreateIndex.html

Use the @MongoTextIndex annotation to create a text index on specified fields. This is useful for full-text search capabilities. Note the limitations of text indexes.

```java
@CollectionName("user")
public class User {

}
```

--------------------------------

### Build Nested Field Names with FieldChain

Source: https://mongoplus.com/docs/nestedField.html

Use FieldChain to construct nested field names like 'role.roleName'. The `build(true)` option prepends a '$' to the field name.

```java
public class User {
    private Role role;
}
public class Role {
    private String roleName;
}

public static void main(String[] args) {
    FieldChain fieldChain = FieldChain.of(User::getRole).then(Role::getUserName);
    //调用build方法构建字段
    String fieldName = fieldChain.build();
    // 打印为 role.roleName
    System.out.println(fieldName);

    // -------------------------------------------------------------------

    //调用build方法构建带$字段
    String fieldNameOption = fieldChain.build(true);
    // 打印为 $role.roleName
    System.out.println(fieldNameOption);
}
```

--------------------------------

### OR Condition

Source: https://mongoplus.com/docs/conditionBuild.html

Specifies an OR condition between criteria.

```java
or(SFunction<T,Object> column,Object value)
or(boolean condition,String column,Object value)
or(QueryChainWrapper<?,?> queryChainWrapper)
or(boolean condition,QueryChainWrapper<?,?> queryChainWrapper)
```

--------------------------------

### Create a Compound Index with @MongoCompoundIndex

Source: https://mongoplus.com/docs/autoCreateIndex.html

Define a compound index using the @MongoCompoundIndex annotation on the class. The 'value' attribute takes a JSON string specifying fields and their sort order (1 for ascending, -1 for descending). You can also specify 'unique', 'sparse', and 'background' options, and 'partialFilterExpression' for conditional indexing.

```java
@CollectionName("user")
@MongoCompoundIndex(
    value = "{'userName':1,'$userAge':-1}"
    unique = true
    partialFilterExpression = "{\"userAge\":{\"gt\",5}}"
)
public class User {

    public String userName;

    @CollectionField("user_age")
    private Integer userAge;

}
```

--------------------------------

### Combine Conditions with Lambda Functions

Source: https://mongoplus.com/docs/conditionBuild.html

Combine conditions within the same object, useful for logical operators like OR and AND. Ensure field names are consistent when using combine.

```java
combine(boolean condition,SFunction<QueryChainWrapper<T,?>,QueryChainWrapper<T,?>> function)
combine(SFunction<QueryChainWrapper<T,?>,QueryChainWrapper<T,?>> function)
combine(QueryChainWrapper<?,?> queryChainWrapper)
combine(boolean condition,QueryChainWrapper<?,?> queryChainWrapper)
```

--------------------------------

### Create Multiple Compound Indexes with @MongoCompoundIndexes

Source: https://mongoplus.com/docs/autoCreateIndex.html

Group multiple compound index definitions using the @MongoCompoundIndexes annotation. This allows for defining several compound indexes on a single entity.

```java
@CollectionName("user")
@MongoCompoundIndexes({
        @MongoCompoundIndex(value = "{'$userName':1,'userAge':1}"),
        @MongoCompoundIndex(value = "{'$userStatus':1,'userAddress':1}")
})
public class User {

    public String userName;

    @CollectionField("user_age")
    private Integer userAge;

    private String userAddress;

    private Integer userAge;

    @MongoHashIndex
    private Integer userStatus;

}
```

--------------------------------

### Create a Custom Write Handler for MongoPlus

Source: https://mongoplus.com/docs/dataBackup.html

Extend `MultipleWriteHandler` to define custom strategies for writing data to multiple data sources during modification operations. This is useful for implementing data replication or backup policies.

```java
import org.springframework.stereotype.Component;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import com.mongodb.MongoNamespace;
import com.mongodb.client.MongoPlusClient;
import com.mongodb.client.model.MultipleWrite;
import com.mongodb.client.model.MultipleWriteHandler;

@Component
public class MongoMultipleWriteHandler extends MultipleWriteHandler {

    public MongoMultipleWriteHandler(MongoPlusClient mongoPlusClient) {
        super(mongoPlusClient);
    }

    /**
     * 写入策略，返回需要写入数据的数据源名称，不存在则抛出异常
     * <p>如果该方法响应数据中存在元素，则直接使用该方法返回值进行写入</p>
     * @param currentDataSource 当前数据源名称
     * @param namespace 集合命名空间
     * @return {@code List<String>} 其他需要写入的数据源名称
     */
    @Override
    public List<String> multipleWrite(String currentDataSource, MongoNamespace namespace) {
        return super.multipleWrite(currentDataSource, namespace);
    }
}
```

--------------------------------

### Auto ObjectId Conversion Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Enable or disable the automatic conversion of String IDs to MongoDB ObjectId.

```yaml
mongo-plus:
  configuration:
    autoConvertObjectId: true
```

--------------------------------

### Custom Sensitive Word Loading

Source: https://mongoplus.com/docs/sensitiveWord.html

Implement the LoadExtraWord interface to provide custom lists of words to be denied or allowed by the sensitive word filter.

```java
// 注册为Bean
@Component
public class CustomLoadExtraWord implements LoadExtraWord {

    @Override
    public List<String> deny() {
        return List.of("拒绝出现的数据-返回的内容被当做是敏感词");
    }

    @Override
    public List<String> allow() {
        return List.of("允许的内容-返回的内容不被当做敏感词");
    }

}
```

--------------------------------

### min

Source: https://mongoplus.com/docs/conditionBuild.html

Updates a field's value only if the new value is less than the current value.

```APIDOC
## min

### Description
Updates a field's value only if the new value is less than the current value.

### Method Signatures
```java
min(boolean condition,SFunction<T,Object> column, Object value);
min(SFunction<T,Object> column, Object value);
min(boolean condition,String column, Object value);
min(String column, Object value);
```

### Example
```java
// Example: min(User::getSalt,100)
// Example: min(User::getCreateTime,LocalDateTime.now())
```
```

--------------------------------

### Create a Unique Index with @MongoIndex

Source: https://mongoplus.com/docs/autoCreateIndex.html

Use the @MongoIndex annotation on a field to create a unique index. Ensure the entity class is annotated with @CollectionName to specify the collection.

```java
@CollectionName("user")
public class User{
    //设置为唯一索引
    @MongoIndex(unique=true)
    private String userName;
}
```

--------------------------------

### Set Value on Insert

Source: https://mongoplus.com/docs/conditionBuild.html

Assigns a specified value to a field in a document only when the document is inserted. Use this to set default values for fields that do not exist.

```java
setOnInsert(boolean condition, SFunction<T,Object> column, Object value);
setOnInsert(SFunction<T,Object> column, Object value);
setOnInsert(boolean condition, String column, Object value);
setOnInsert(String column, Object value);
```

--------------------------------

### currentDate

Source: https://mongoplus.com/docs/conditionBuild.html

Sets the value of a field to the current date or timestamp.

```APIDOC
## currentDate

### Description
Sets the value of a field to the current date or timestamp.

### Method Signatures
```java
currentDate(boolean condition,SFunction<T,Object> column);
currentDate(SFunction<T,Object> column);
currentDate(boolean condition,String column);
currentDate(String column);
currentDate(boolean condition,SFunction<T,Object> column, CurrentDateType currentDateType);
currentDate(SFunction<T,Object> column, CurrentDateType currentDateType);
currentDate(boolean condition,String column, CurrentDateType currentDateType);
currentDate(String column, CurrentDateType currentDateType);
```

### Example
```java
// Example: currentDate(User::getCreateTime,CurrentDateType.DATE)
```
```

--------------------------------

### Auto Increment ID Collection Name Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Specify a custom name for the collection used to store auto-increment IDs.

```yaml
mongo-plus:
  configuration:
    autoIdCollectionName: xxxx
```

--------------------------------

### Dynamic Sensitive Word Management

Source: https://mongoplus.com/docs/sensitiveWord.html

Utilize the SensitiveWordManager to dynamically add or remove words from the blacklist and whitelist during runtime.

```java
// 注入SensitiveWordManager
@Resource
private SensitiveWordManager sensitiveWordManager;

// 黑名单

/** ==================添加================== */

/**
 * 添加敏感词
 * @param words 敏感词
 */
void addWordBlacklist(String... words);

/**
 * 添加敏感词
 * @param words 敏感词
 */
void addWordBlacklist(Collection:String words);

/**
 * 添加敏感词
 * @param wordFile 敏感词文件路径
 */
void addWordBlackList(Path wordFile);

/** ==================删除================== */

/**
 * 删除敏感词
 * @param words 敏感词
 */
void removeSensitiveWord(String... words);

/**
 * 删除敏感词
 * @param words 敏感词
 */
void removeSensitiveWord(Collection:String words);

/**
 * 删除敏感词
 * @param wordFile 敏感词文件路径
 */
void removeSensitiveWord(Path wordFile);

// 白名单

/** ==================添加================== */

/**
 * 添加敏感词白名单
 * @param words 敏感词
 */
void addSensitiveWordAllow(String... words);

/**
 * 添加敏感词白名单
 * @param words 敏感词
 */
void addSensitiveWordAllow(Collection<String> words);

/**
 * 添加敏感词白名单
 * @param wordFile 敏感词文件路径
 */
void addSensitiveWordAllow(Path wordFile);

/** ==================删除================== */

/**
 * 删除敏感词白名单
 * @param words 敏感词
 */
void removeSensitiveWordAllow(String... words);

/**
 * 删除敏感词白名单
 * @param words 敏感词
 */
void removeSensitiveWordAllow(Collection<String> words);

/**
 * 删除敏感词白名单
 * @param wordFile 敏感词文件路径
 */
void removeSensitiveWordAllow(Path wordFile);
```

--------------------------------

### rename

Source: https://mongoplus.com/docs/conditionBuild.html

Updates the name of a field.

```APIDOC
## rename

### Description
Updates the name of a field.

### Method Signatures
```java
rename(boolean condition, String oldFieldName,String newFieldName);
rename(String oldFieldName,String newFieldName);
rename(boolean condition, SFunction<O,Object> oldFieldName,String newFieldName);
rename(SFunction<O,Object> oldFieldName,String newFieldName);
rename(boolean condition, SFunction<O,Object> oldFieldName,SFunction<N,Object> newFieldName);
rename(SFunction<O,Object> oldFieldName,SFunction<N,Object> newFieldName);
```

### Example
```java
// Example: rename(User::getUserName,"user_name")
// Example: rename(User::getUserName,User::getUserName)
```
```

--------------------------------

### Configure Sensitive Word Filtering

Source: https://mongoplus.com/docs/sensitiveWord.html

Configure sensitive word filtering behavior using application properties. Options include filtering type, case sensitivity, and style normalization.

```yaml
mongo-plus:
  sensitive-word:
    # 敏感词校验类型,默认局部
    sensitive-type: LOCAL
    # 是否忽略大小写
    ignore-case: true
    # 是否忽略全角、半角
    ignore-width: true
    # 是否忽略数字样式
    ignore-num-style: true
    # 是否忽略中文样式
    ignore-chinese-style: true
    # 是否忽略英文样式
    ignore-english-style: true
    # 是否忽略重复字符
    ignore-repeat: false
    # 是否忽略特殊字符
    ignore-char: false
    # 启用连续数字检测
    enable-num-check: false
    # 启用邮箱检测
    enable-email-check: false
    # 启用 URL 检测
    enable-url-check: false
    # 启用 IPv4 检测
    enable-ipv4-check: false
```

--------------------------------

### AND Condition within OR

Source: https://mongoplus.com/docs/conditionBuild.html

Used within an OR clause to combine conditions with AND logic.

```java
and(LambdaQueryChainWrapper<T> lambdaQueryChainWrapper)
and(boolean condition,LambdaQueryChainWrapper<T> lambdaQueryChainWrapper)
```

--------------------------------

### push

Source: https://mongoplus.com/docs/conditionBuild.html

Pushes a specified value into an array field. This operation is useful for adding elements to lists or arrays within a document.

```APIDOC
## push

### Description
Pushes a specified value into an array field. This operation is useful for adding elements to lists or arrays within a document.

### Method Signatures
```java
push(boolean condition,SFunction<T,Object> column,Object value);
push(SFunction<T,Object> column,Object value);
push(boolean condition,String column,Object value);
push(String column,Object value);
push(boolean condition,SFunction<T,Object> column,Object ... value);
push(SFunction<T,Object> column,Object ... value);
push(boolean condition,String column,Object ... value);
push(String column,Object ... value);
push(boolean condition, SFunction<T,Object> column, List<?> value);
push(SFunction<T,Object> column, List<?> value);
push(boolean condition, String column, List<?> value);
push(String column, List<?> value);
```

### Example
```java
// Example: push(User::getRoleList,new ArrayList<>())
```
```

--------------------------------

### Define User Entity with @ID Annotation

Source: https://mongoplus.com/docs/started.html

Create a User entity class, mapping it to MongoDB documents. Use the @ID annotation to specify the primary key field.

```java
@Data
public class User {
    @ID     //使用ID注解，标注此字段为MongoDB的_id，或者继承BaseModelID类
    private String id;
    private String name;
    private Long age;
    private String email;
}
```

--------------------------------

### unset

Source: https://mongoplus.com/docs/conditionBuild.html

Deletes specific fields from a document.

```APIDOC
## unset

### Description
Deletes specific fields from a document.

### Method Signatures
```java
unset(SFunction<T,Object>... columns);
unset(boolean condition,SFunction<T,Object>... columns);
unset(String... columns);
unset(boolean condition,String... columns);
unset(List<String> columns);
unset(boolean condition,List<String> columns);
```

### Example
```java
// Example: unset(User::getUserName,User::getAge)
```
```

--------------------------------

### Add mongo-plus-sensitive-word Dependency

Source: https://mongoplus.com/docs/sensitiveWord.html

Include the mongo-plus-sensitive-word dependency in your project's pom.xml to enable keyword filtering.

```xml
<dependencyManagement>
    <dependencies>
        <!-- mongoplus-bom -->
        <dependency>
            <groupId>com.mongoplus</groupId>
            <artifactId>mongo-plus-bom</artifactId>
            <version>最新版本</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- mongoplus关键词依赖 -->
    <dependency>
        <groupId>com.mongoplus</groupId>
        <artifactId>mongo-plus-sensitive-word</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

--------------------------------

### Exclude MongoDB Driver for Older Spring Boot Versions

Source: https://mongoplus.com/docs/started.html

For older Spring Boot versions (e.g., 2.1, 2.2), exclude the default MongoDB driver and explicitly include compatible versions.

```xml
<dependency>
    <groupId>com.mongoplus</groupId>
    <artifactId>mongo-plus-boot-starter</artifactId>
    <version>最新版本</version>
    <exclusions>
        <exclusion>
            <artifactId>bson</artifactId>
            <groupId>org.mongodb</groupId>
        </exclusion>
        <exclusion>
            <artifactId>mongodb-driver-core</artifactId>
            <groupId>org.mongodb</groupId>
        </exclusion>
        <exclusion>
            <artifactId>mongodb-driver-sync</artifactId>
            <groupId>org.mongodb</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson</artifactId>
    <version>5.1.2</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-core</artifactId>
    <version>5.1.2</version>
</dependency>
<dependency>
    <artifactId>mongodb-driver-sync</artifactId>
    <groupId>org.mongodb</groupId>
    <version>5.1.2</version>
</dependency>
```

--------------------------------

### addToSet

Source: https://mongoplus.com/docs/conditionBuild.html

Adds a value to an array field, ensuring uniqueness of elements if `each` is true.

```APIDOC
## addToSet

### Description
Adds a value to an array field, ensuring uniqueness of elements if `each` is true.

### Method Signatures
```java
addToSet(boolean condition,SFunction<T,Object> column,Object value,boolean each);
addToSet(SFunction<T,Object> column,Object value,boolean each);
addToSet(boolean condition,String column,Object value,boolean each);
addToSet(String column,Object value,boolean each);
```

### Example
```java
// Example: addToSet(User::getRoleList,new ArrayList<>(),true)
```
```

--------------------------------

### Exclude Configuration for Older Spring Boot Versions

Source: https://mongoplus.com/docs/started.html

When using older Spring Boot versions, exclude the `OverrideMongoConfiguration` class from the application's main annotation to ensure compatibility.

```java
//排除OverrideMongoConfiguration配置类
@SpringBootApplication(exclude = OverrideMongoConfiguration.class)
// 如报错相关类为：MongoPropertyConfiguration.class，则需要将MongoPropertyConfiguration也一并排除
//@SpringBootApplication(exclude = {OverrideMongoConfiguration.class, MongoPropertyConfiguration.class})
public class MongoPlusDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(MongoPlusDemoApplication.class, args);
    }

}
```

--------------------------------

### Spring Transaction Configuration (YAML)

Source: https://mongoplus.com/docs/property.html

Enable or disable the use of Spring's @Transactional annotation for controlling MongoDB transactions.

```yaml
mongo-plus:
  spring:
    transaction: true
```

--------------------------------

### Unset Field

Source: https://mongoplus.com/docs/conditionBuild.html

Removes specific fields from a document. Can accept field names as strings or SFunction references, individually or as a list.

```java
unset(SFunction<T,Object>... columns);
unset(boolean condition,SFunction<T,Object>... columns);
unset(String... columns);
unset(boolean condition,String... columns);
unset(List<String> columns);
unset(boolean condition,List<String> columns);
```

--------------------------------

### pop

Source: https://mongoplus.com/docs/conditionBuild.html

Removes the first or last element from an array field.

```APIDOC
## pop

### Description
Removes the first or last element from an array field.

### Method Signatures
```java
pop(boolean condition,SFunction<T,Object> column, PopType popType);
pop(SFunction<T,Object> column, PopType popType);
pop(boolean condition,String column, PopType popType);
pop(String column, PopType popType);
```

### Example
```java
// Example: pop(User::getRoleList,PopType.FIRST)
```
```

--------------------------------

### Add to Set

Source: https://mongoplus.com/docs/conditionBuild.html

Adds a value to an array field, ensuring uniqueness if 'each' is true. If 'each' is false, it adds a single value. If the value already exists and 'each' is true, it is not added again.

```java
addToSet(boolean condition,SFunction<T,Object> column,Object value,boolean each);
addToSet(SFunction<T,Object> column,Object value,boolean each);
addToSet(boolean condition,String column,Object value,boolean each);
addToSet(String column,Object value,boolean each);
```
Tokens:
Raw