# 1 接口说明
Algo相关接口定义和实现存在于bos-algo-1.0.jar中。在实际使用过程中主要使用DataSet的相关接口方法。
# 2 接口列表
**DataSet**
| 接口方法 | 说明 |
| - | - |
| join | join操作 |
| leftJoin | leftJoin操作 |
| rightJoin | rightJoin操作 |
| fullJoin | fullJoin操作 |
| hashJoin | hashJoin操作 |
| union | union操作 |
| top | 取top n个 |
| limit | 取部分行 |
| range | 取部分行，类似limit |
| copy | 拷贝自己 |
| count | 对field进行count计数，distinct消除重复 |
| cache | 将dataset缓存起来 |
| cacheBuilder | |
| print | 打印输出到console |
| close | 关闭 |
| select | 选择字段。类似:select a,b,c，a,b,c可以是表达式 |
| addField | 增加字段 |
| addNullField | 增加null字段，等价于addField("null",alias) |
| addBalanceField | 增加余额字段，该字段的值从上往下累加 |
| removeField | 删除字段 |
| filter | 过滤，类似where，expr中可以写变量，变量值通过params传递，比如”a>b”, params是map，key包含a和b |
| where | 过滤 |
| orderBy | 排序，field可以写成field asc,field desc |
| groupBy | groupBy操作 |
| executeSql | 执行sql |
# 3 select
+ **功能描述**
选择字段。类似:select a,b,c，a,b,c可以是表达式。
+ **方法**
```java
public DataSet select(String[] exprs)
public DataSet select(String exprs);
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| exprs | String[] | exprs可以是 字段field、Field as alias、表达式 as alias；Select是对源DataSet的重新选择，类似sql；DataSetA.Select(new String[]{“a”,”b+c as d”})等价于Select a,b+c as d from DataSetA。 |
| exprs | String | exprs可以是直接写多个字段，比如dataSetA.select(“fname, famount as amount,1+2 as c”); |
+ **返回值**
返回选择字段后的DataSet。
+ **示例代码**
```java
DataSet ds= dataSet.select(new String[]{
"famount",
"famount c1",
"famount + fqty c2",
"famount * fqty c3",
"null c4", "true c5",
"(famount + fqty) * 3 c6",
"famount >= fqty c7",
"famount >= fqty and fqty<100 c8",
"fname + 'abc' name"});
DataSet ds= dataSet.select(
"famount, famount c1,famount + fqty c2,famount * fqty c3 ,null c4,?true c5,(famount + fqty) * 3 c6,famount >= fqty c7,famount >= fqty and fqty<100 c8,fname + 'abc' name}");
```
# 4 addField
+ **功能描述**
添加字段。
+ **方法**
```java
// 在现有DataSet基础上添加字段，或者删除字段
public DataSet addField(String expr, String alias)
// 添加表达式expr字段，数据类型自动判断
public DataSet addField(String expr, String alias)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| expr | String | expr可以是字段field、Field as alias、表达式 as alias |
| alias | String | 字段别名 |
+ **返回值**
返回添加完字段后的DataSet。
# 5 addNullField
+ **功能描述**
添加值为null的字段，数据类型为NullType。
+ **方法**
```java
public DataSet addNullField(String alias)
public DataSet addNullField(String... aliases)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| alias | String | 别名 |
| aliases | String... | 别名数组 |
+ **返回值**
返回添加完字段后的DataSet。
# 6 addBalanceField
+ **功能描述**
添加余额字段，addBalanceField方法将字段的值从上往下累加。
+ **方法**
```java
public DataSet addBalanceField(String expr, String alias)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| expr | String | 表达式 |
| alias | String | 别名 |
+ **返回值**
返回添加完字段后的DataSet。
+ **代码示例**
```java
addBalanceField("amount", "balance")
addBalanceField("amount * 2", "balance2")
```
| Period | Amount | balance | balance2 |
| - | - | - | - |
| 201701 | 100 | 100 | 200 |
| 201702 | 200 | 300 | 600 |
| 201703 | 200 | 500 | 1000 |
# 7 removeField
+ **功能描述**
删除字段。
+ **方法**
```java
public DataSet removeField(String field)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| field | String | 字段名称 |
+ **返回值**
返回删除完字段后的DataSet。
# 8 where/filter
+ **功能描述**
过滤，类似where，expr中可以写变量，变量值通过params传递，比如”a>b”, params是map，key包含a和b。filter类似于sql的where条件。where和filter是完全等价的。
+ **方法**
```java
public DataSet where(String expr)
public DataSet where(String expr, Map<String, Object> params)
public DataSet filter(String expr)
public DataSet filter(String expr, Map<String, Object> params)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| expr | String | expr是计算表达式，必须为boolean |
| params | Map<String, Object> | params传递参数给expr。如expr为famount + var1 > 10000。params为：{var1: 100}等价于： famount+100>10000。 |
+ **返回值**
返回过滤后的DataSet。
+ **代码示例**
```java
DataSet ds= dataSet.where("famount>50 and (fqty-100)<5");
DataSet ds = dataSet.filter("famount>50 and (fqty-100)<5");
```
# 9 orderBy
+ **功能描述**
排序。
+ **方法**
```java
public DataSet orderBy(String[] exprs)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| expr | String[] | expr可以是:字段Fname，默认为asc排序。Fname asc、Fname desc、Expr不可以为表达式 |
+ **返回值**
返回排序后的DataSet。
+ **代码示例**
```java
DataSet dataSet2 = dataSet.orderBy(new String[]{"fname", "famount"});
DataSet dataSet2 = dataSet.orderBy(new String[]{"fname desc", "famount asc"});
```
# 10 groupBy
+ **功能描述**
groupBy操作与SQL中的类似。
***groupBy说明***
1. GroupBy结果集默认根据group fields排序，默认asc排序，可以对每个field的排序方向进行设置，即以下orderByDescs：
```java
GroupbyDataSet groupBy(String[] groupFields, boolean[] orderByDescs);
```
所以，对groupby结果进行orderBy，请考虑是否有必要。
2. SQL 92标准，group by结果是不保证排序的，上述API查询结果默认是排序的，是历史原因，目前无法简单去掉;现在没有sql的group by，结果就不保证排序
3. 当GroupBy字段为空时，如dataset.groupBy(null)，或者dataSet.groupBy(new String[0]);dataSet.groupBy(null).sum(a).max(b).finish()等价于没有groupby。
4. 有聚合函数的sql：Select sum(a),max(b) from t;如果用sql，可以简写： Select sum(a),max(b)， 不需要group by关键字。
+ **方法**
```java
GroupbyDataSet groupBy(String[] groupFields)
GroupbyDataSet groupBy(String[] groupFields, boolean[] orderByDescs)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| groupFields | String[] | groupBy字段 |
| orderByDescs | boolean[] | 是否desc排序|
+ **返回值**
返回GroupbyDataSet对象。
+ **代码示例**
**调用过程**
1. 获取构造器GroupByDataSet。
2. 构造器里设置sum，avg等聚合函数。
3. 构造器finish得到DataSet。
```java
GroupbyDataSet groupby = dataSet.groupBy(new String[]{"fname"}); //groupby是构造器
groupby = groupby.sum("(famount + fqty) * 2", "amount").count("countalias");
groupby = groupby.maxP("famount", "fqty", "amount").count();
DataSet dataSet2 = groupby.finish(); //构造完毕，返回DataSet
```
# 11 union
+ **功能描述**
union操作与SQL的union类似。两个DataSet叠加起来，不支持消除重复。
两个DataSet字段个数必须相同，且每个字段的类型必须互相兼。
***字段Fields合并规则***
1. 默认字段名取左边。
2. 数据类型取左边和右边的兼容类型。
***数据类型兼容规则***
1. Number类型，取最大精度如(Int,Long)取long，(BigDecimal,Long)取BigDecimal。
2. 含Null类型的，取非Null类型。
3. 含Unknown类型的，取非Unknown类型的。
如果两个DataSet字段个数不同，又需要Union，可以通过DataSet.addNullField()添加null字段，以满足相同个数。
+ **方法**
```java
public DataSet union(DataSet rightDataSet)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| rightDataSet | DataSet | 被union的DataSet |
+ **返回值**
返回union后的DataSet。
# 12 join
+ **功能描述**
适用于两个DataSet的join，跟sql的join类似，支持InnerJoin，LeftJoin，RightJoin，FullJoin，CrossJoin。
+ **方法**
```java
JoinDataSet join(DataSet rightDataSet)
JoinDataSet join(DataSet rightDataSet, JoinHint hint)
JoinDataSet join(DataSet rightDataSet, JoinType type)
JoinDataSet join(DataSet rightDataSet, JoinType type, JoinHint hint)
```
***Join便捷方法***
```java
JoinDataSet leftJoin(DataSet rightDataSet)
JoinDataSet leftJoin(DataSet rightDataSet, JoinHint hint)
JoinDataSet rightJoin(DataSet rightDataSet)
JoinDataSet rightJoin(DataSet rightDataSet, JoinHint hint)
JoinDataSet fullJoin(DataSet rightDataSet)
JoinDataSet fullJoin(DataSet rightDataSet, JoinHint hint)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| rightDataSet | DataSet | dataset |
| hint | JoinHint | JoinHint是一些特性指示器，目前只有一个；Join时，null值是否当做0,为true时，0=null;为false时，0!=null;默认值为false。 |
| type | JoinType | join类型 |
+ **返回值**
返回join后的JoinDateSet对象。
***JoinDataSet构造器接口***
1. JoinDataSet on(String leftField, String rightField); //类似于sql中的on left.leftField=right. rightField
2. JoinDataSet select(String[] leftFields, String[] rightFields);//类似于sql中的select，分别选择左右表字段
3. JoinDataSet hint(JoinHint hint);//设置hint
4. DataSet finish();//返回DataSet
+ **示例代码**
```java
JoinDataSet join = dataSet.join(productDataSet, JoinType.Left);
DataSet result = join.on("fproductid", "fid").select(new String[]{"fproductid", "famount amount", "fqty qty"}, new String[]{"fname productName"}).finish();
JoinDataSet join = dataSet.leftJoin(productDataSet);
DataSet result = join.on("fproductid", "fid").select(new String[]{"fproductid", "famount amount", "fqty qty"}, new String[]{"fname productName"}).finish();
```
# 13 hashJoin
+ **功能描述**
1. 适用于一个大表关联1至N个小表，如业务单据join基础资料。
2. hashJoin比普通Join性能更好，特别是同时关联多个小表时。
3. HashJoin性能比较好，消耗资源少，推荐使用，但也谨慎推荐，因为小表是否真的很小，需要判断，一般认为小表数据量小于10000即可。
4.
+ **使用示例**
1.小表DataSet转换为HashTable，其中keyField必须是唯一单字段，否则就不能是HashTable。
```java
public HashTable toHashTable(String keyField)
```
2.大表DataSet.hashJoin小表，得到HashJoinDataSet构造器，其中leftJoinKeyField为大表关联字段，hashTableSelectFields右边选择字段。
3.HashJoinDataSet构造器addHashTable，继续添加。
+ **调用过程**
1. 如果要关联N个小DataSet，分别转换为HashTabl
2. 通过hashJoin获得构造器HashJoinDataSet
3. 在构造器中添加HashTable，设置左表选择字段
4. Finish()返回DataSet
+ **代码示例**
```java
HashTable productLT = productDataSet.select(new String[]{"fid productId", "fname productName"}).toHashTable("productId");
HashTable orgLT = orgDataSet.select(new String[]{"fid orgId", "fname orgName"}).toHashTable("orgId");
DataSet joinDataSet = factDataSet.hashJoin(productLT, "fproductid", new String[]{"productName as pName"}, true)
.addHashTable(orgLT, "forgid", new String[]{"orgName"}, true)
.selectLeftFields(new String[]{"fproductid", "famount amount", "fqty qty"}).finish();
```
+ **说明**
HashJoin默认结果类似于InnerJoin，也可以实现Left Join的效果，即大表中有，小表中没有，通过includeNotExist，ncludeNotExist是作用于每个连接上，所以，每个连接可以includeNotExist值不同的。
1. 大表连接HashTable时，如left.faccountid=hashTable.fid, 如果left.faccountid在HashTable中不存在，默认是不会选择该行。
2. 如果传入includeNotExist=true，那么会选择该行，等价于left join，右表字段全部为null。
***crossJoin***
# 14 count
+ **功能描述**
类似sql，但不包括null值。DataSet执行count后，自动close。
+ **方法**
```java
int count(String field, boolean distinct)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| field | String | 计数字段 |
| distinct | boolean | 是否去重 |
+ **返回值**
返回数量。
# 15 print
+ **功能描述**
打印输出到console，copy表示是否copy dataset。调试时，可以调用print(true)打印；跟ORMUtil.dumpDataSet(dataSet.copy())类似。
+ **方法**
```java
void print(boolean copy)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| copy | boolean | 是否copy一个新的 |
+ **返回值**
无
# 16 copy
+ **功能描述**
Copy是有资源消耗的，默认DataSet只能被遍历一次，因为它可能是在线的，即底层可能是ResultSet，Copy后会变成离线的，占用内存。
***什么时候需要copy***
1. DataSet需要遍历多次。
2. DataSet既要被引用，又要遍历使用。
3. 调试打印时用，ORMUtil.dumpDataSet或DataSet.print。
***不该copy的场景***
1. dataset.copy().join() copy结果没有用到。
2. 调试时用了copy()，正式代码需要删除掉。
+ **方法**
```java
DataSet copy()
```
+ **返回值**
返回一个copy的DataSet。
