# LogORM使用文档
> 日志单据是平台提供的用于开发业务日志的一种单据类型，业务日志可以保存在传统数据库（以下简称DB）或者Elasticsearch（二者只能选其一）。
LogORM是日志单据查询与写入的接口，使用该接口，开发者无需关心日志单据底层存储实现，根据客户环境部署需求，在MC进行简单配置，就可以将日志写入DB（MySQL/PostgreSQL/Oracle等）或者Elasticsearch（以下简称Elastic）。
### 开始使用
写入日志：
```java
// 根据实体名构建元数据并创建DynamicObject
MainEntityType entityType = EntityMetadataCache.getDataEntityType("entityName");
DynamicObject dynamicObject = new DynamicObject(entityType);
dynamicObject.getDataEntityType().getPrimaryKey().setValueFast(dynamicObject, ID.genLongId());
dynamicObject.set("xx1","hello world");
// 批量插入，需要保证objects中为同一个单据类型的DynamicObject
List<DynamicObject> objects = new ArrayList<>();
objects.add(dynamicObject);
// 初始化LogORM实例
LogORM logORM = LogORM.create();
// 批量插入
logORM.insert(objects);
```
查询日志：
```java
LogORM logORM = LogORM.create();
QFilter qFilter = QFilter.of("xx1 = ?", "hello world");
DataSet ds = logORM.queryDataSet("entityName", "id,xx1", new QFilter[]{qFilter}, 100, 0);
while (ds.hasNext()) {
Row row = ds.next();
System.out.println("LogORM-QueryDataSet:" + row.get(0));
}
```
### 接口列表
1. 插入接口
```java
/**
* 批量插入
*
* @param objects DynamicObject
* @return 插入数据的主键数组
*/
long[] insert(List<DynamicObject> objects);
```
2. 查询接口
```java
/**
* 查询DynamicObjectCollection
*
* @param entityName 单据标识
* @param selectFields 查询字段
* @param filters 过滤条件
* @param limit limit
* @param offset offset
* @return DynamicObjectCollection
*/
DynamicObjectCollection query(String entityName, String selectFields, QFilter[] filters, int limit, int offset);
/**
* 查询DataSet
*
* @param entityName 单据标识
* @param selectFields 查询字段
* @param filters 过滤条件
* @param limit limit
* @param offset offset
* @return DataSet
*/
DataSet queryDataSet(String entityName, String selectFields, QFilter[] filters, int limit, int offset);
/**
* 执行简单聚集函数(目前只支持count函数)
*
* @param entityName 单据标识
* @param func 函数名称 例如：count(id)
* @param filters 过滤条件
* @return 条数
*/
long aggregate(String entityName, String func, QFilter[] filters);
```
3. 更新及删除
```java
/**
* 批量更新
*
* @param objects DynamicObject
* @return 返回影响的条数
*/
int update(List<DynamicObject> objects);
/**
* 按条件删除
*
* @param entityName 单据标识
* @param where 筛选条件
* @return 删除的记录数量
*/
int delete(String entityName, QFilter[] where);
```
### 数据类型
为了统一Elastic及DB存储，不同于其它单据，日志框架仅支持以下类型：
1. 文本/长文本/大文本
对应Java的String类型，文本及长文本最多支持2000字符，请**尽量不要使用大文本字段**，使用大文本字段时，对大文本字段检索存在限制，**ES只能检索前2000字符**，部分数据库不支持在TEXT字段上进行模糊查询。
2. 整数
对应Integer类型。
3. 长日期
可使用java.sql.Date及java.sql.Timestamp类型。
4. 小数
可使用float,double及BigDecimal类型，**最多只支持15位长度精度。**
### 使用限制
受限于Elastic存储以及系统稳定考虑，使用时存在以下限制：
##### QFilter
1. 操作符不支持`match`，`exists`，`not exists`。
2. property只支持属性，不支持复杂表达式。
3. value不支持复杂表达式。
4. like查询时，value值长度不能超过500个字符，ftlike查询时单个值长度也不能超过500个字符。
5. 不支持在like及ftlike中查询带有`*`的字符串。
##### 其它
1. 查询字段不支持复杂表达式
### 常见问题
1. 支持运行时切换DB及Elastic存储吗？
不支持，该操作可能会造成部分数据存入DB及Elastic，后续无法进行数据合并。
2. 出现`Not found ElasticSearch data source`异常
请检查MC是否启用了`启用ES日志存储`按钮，但是没有配置Elastic数据源。
3. 在Elastic数据源时，同样的查询条件，查询返回的数据不一致
请检查是否正确配置了Elastic集群；MC配置Elastic集群时，支持配置多个地址，但是没有对这些地址是否属于同一集群检测。
4. 出现`Archive route dataSource not found`或者`Not found elastic archive data source`异常
请检查是否正确配置了Elastic的归档配置及归档数据源。
5. 出现`Unknown column [xxxx], did you mean any of [xxxx]`
请检查是否正确配置了Elastic集群；MC配置Elastic集群时，支持配置多个地址，但是没有对这些地址是否属于同一集群检测。
6. 出现`Cannot use field [xxxx] due to ambiguities being mapped as [xxx] incompatible type: xxx`
请检查是否正确配置了Elastic集群；MC配置Elastic集群时，支持配置多个地址，但是没有对这些地址是否属于同一集群检测。
### 统一日志框架参考文档
[统一日志框架基本介绍](https://vip.kingdee.com/article/252103318804381440)
[统一日志框架特性介绍](https://vip.kingdee.com/article/252068701972294656)
