数据模型

导入

通过如下方式导入数据模型api

import dw from "svr-api/dw";

方法

/**
 * 模型相关API
 */

/**
 * 获取指定的模型。
 * 
 * @param resIdOrPath 模型的路径或者资源id
 * @param throwIfNotExist 不存在时是否抛出异常，默认为false
 * @returns 返回模型表的信息对象，不存在时返回`null`。
 */
export function getDwTable(resIdOrPath: string, throwIfNotExist?: boolean): DwTableInfo;
/**
 * 打开模型表的数据，可以对数据进行增删改查操作。
 * 
 * @param path 元数据路径，可以是如下形式：
 *  1. 完整的绝对路径，如`/ProjectName/data/path/to/yourfile.tbl`
 *  2. 相对路径，相对于当前执行的脚本文件，如 `yourfile.tbl`、`../folder/yourfile.tbl`
 *  3. 没有后缀时默认使用`.tbl`
 * @param throwIfNotExist 不存在时是否抛出异常，默认为false
 * @returns 返回模型表的数据对象，不存在时返回`null`。
 */
export function openDwTableData(path: string, throwIfNotExist?: boolean): DwTableData;

/**
 * 执行一个对数据仓库的query，与直接执行sql不同，此函数支持一致性维度关联、表达式函数（非数据库函数），权限过滤等功能。
 *
 * @param queryInfo Query的元数据结构信息
 * @returns 返回查询结果，结果为空时返回空数组`[]`。
 */
export function queryDwTableData(queryInfo: QueryInfo): Array<Array<any>>;

/**
 * 执行一个对数据仓库的query，与直接执行sql不同，此函数支持一致性维度关联、表达式函数（非数据库函数），权限过滤等功能。
 * 
 * @param queryInfo Query的元数据结构信息
 * @returns 计算结果返回标准的query json结构数据，具体参考queryData-查询数据.md
 */
export function queryData(queryInfo: QueryInfo): QueryDataResultInfo;

/**
 * 将query翻译为对应的查询SQL
 *
 * @param queryInfo Query的元数据结构信息
 * @returns 返回查询SQL
 */
export function getQuerySql(queryInfo: QueryInfo): string;

/**
 * 根据传入的数据包，修改模型表的数据。
 *
 * @param resIdOrPath 模型的路径或者资源id
 * @param data 要更新的数据包
 * @param con 可以传入一个外部的数据库连接，此时此函数将不自动提交数据，交给外部调用者自己处理，方便实现在一个事务中进行多个表的修改。
 */
export function updateDwTableData(resIdOrPath: string, data: CommonTableSubmitDataPackage, con?: Connection): void;

/**
 * 保存指标库
 * @param labelLibInfo 
 */
export function saveLabelLib(labelLibInfo: DwDataLabelLib): void;

/**
 * 执行回放服务
 * @param args 
 * @param args.schedule 推送计划，将执行属于该计划的所有正常通道
 * @param [args.parallel] 并发数，默认为4
 * 
 */
export function pushData(args: { schedule: string, parallel?: number }): void;

/**
 * 刷新一个数据表的状态。
 * 数据发生变化，需要调用此方法，更新总行数等。
 * @param resIdOrPath 模型的路径或者资源id
 * @param refreshRowCount 是否刷新总行数和总空间
 */
export function refreshState(resIdOrPath: string, refreshRowCount?: boolean): void;

/**
 * 更新目标模型的父子维层次信息。
 * 
 * @param resIdOrPath 模型的路径或者资源id
 * @param ids 主键列表，不传时，刷新整个模型，传递时，只刷新传入主键对应的这些数据行
 */
export function refreshTableParentHierarchy(resIdOrPath: string, ids?: string[]): void;

对象

/**
 * 此文件定义数据模型相关的后端脚本接口。
 * 
 * 1. 目前有很对对象都是前后端公用的，比如`DwTableInfo`、`DwTableFieldInfo`。
 * 2. 可能前端以后会发生修改，接口发生变化，此时后端接口也可以跟着变化，但是实现类继续支持一下以前的接口返回就好了。
 */

/**
 * 一个模型表的数据对象，提供比较方便的查询和修改模型表的数据的工具函数。
 * 说明：
 * 1、大多数情况下直接调用本方法的增删改查方法即可访问数据库，不需要调用commit、rollback
 * 2、如果操作数据库需要关心事务，多个增删改操作必须在一个事务中执行，那么需要先调用`setAutoCommit(false)`，禁用自动提交。
 *    然后在操作的最后调用commit()，在try-catch中调用rollback，下面是一个示例：
 * @example
 *  import dw from "svr-api/dw";
 *  let data = dw.openDwTableData("XXXXXX");
 *  try{
 *      data.setAutoCommit(false); //禁止自动提交，整个事务在commit时提交
 *      data.insert({ID_:"A100", CAPTION_:"渔业"});
 *      data.delete({ID_:"A200"});
 *      data.commit();
 *  }catch(e){
 *      data.rollback();
 *  }
 */
interface DwTableData extends TableData {
    /**
     * 获取维表模型的某个维项。不存在时返回null。
     * @param id 维项id
     * @param time 缓慢变化维有效，不传递表示当前时间
     */
	getItem(id: string, time?: number): DwTableDataItem;

    /**
     * 根据文本找到维项，不存在时返回null。
     * @param txt 要查找的文本
     * @param time 缓慢变化维有效，不传递表示当前时间
     * @param synonymFieldName 同义词字段
     */
	getItemByText(txt: string, time?: number, synonymFieldName?: string): DwTableDataItem;

    /**
     * 查找某个层级的所有子节点。父节点不存在时返回null，父节点存在但是没有子节点时返回空数组。
     * 
     * @param pid 父维项代码
     * @param time 缓慢变化维有效，不传递表示当前时间
     */
	getChildItems(pid: string, time?: number): DwTableDataItem[];

    /**
     * 获取根维成员
     * 
     * @param time 缓慢变化维有效，不传递表示当前时间
     */
	getRootItems(time?: number): DwTableDataItem[];

    /**
     * 判断一个维项是否是另一个维项的父节点或父节点的父节点（祖先节点）……
     * @param pid 父维项代码
     * @param id 维项id
     * @param time 缓慢变化维有效，不传递表示当前时间
     */
	isAncestor(pid: string, id: string, time?: number): boolean;
}

/**维项信息 */
interface DwTableDataItem {
	/**层级 */
	_level: number,
	/**是否叶子节点 */
	_leaf: boolean,
	/**其它属性，通过字段名访问 */
	[fieldName: string]: any
}

interface CopyTablesArgs {
	projectName?: string,
	taskId?: string,
	srcDataSource: string,
	srcSchema?: string,
	destDataSource: string,
	destSchema?: string,
	/**
	 * 复制时是否查询来源表的数据行数，用于输出复制结果判断复制时是否存在数据丢失.
	 * 查询数据行数十分耗时的情况，可以不查询来源数据表行数
	 */
	queryTableRowcount?: boolean,
	/**默认同步，是否异步，异步时函数调用直接返回，任务在线程堆栈之行，否则是同步等待迁移完成才返回函数 */
	async?: boolean,
	/**default is 4，默认多少个表一起并行迁移，系统会自动启动2*parallel个线程，一半用于读一半用于写 */
	parallel?: number,
	csv?: {
		/**迁移过程中的csv分隔符，默认为换行符 */
		separator: string,
		/**迁移过程的csv引号，默认为双引号 */
		quote: string,
		/**迁移过程中的csv转义字符，默认为斜杠 */
		escape: string
	},
	/**设置管道缓存大小 */
	pipeSize?: number,
	/**1:创建新表,2：覆盖表，4：清空表，8：追加记录，10：更新记录， */
	importMode?: CopyTablesMode,
	/**跳过多少条记录，如csv导出时，会导出数据时会包含注释等信息，可以把该行忽略掉 */
	skip?: number,
	/**当源表是空表时，自动忽略，不进行数据拷贝，默认为true */
	ignoreBlankTable?: boolean,
	/**支持传递sql作为生成目标数据表的依据 */
	tables: Array<CopyTableInfo>
}

/**
 * 复制数据表返回结果
 */
interface CopyTablesResult {
	/** 复制的目标数据源 */
	destDataSource: string,
	destSchema: string,
	/** 复制的目标数据表*/
	tables: {
		targetTableName: string,//复制后的表名
		success?: boolean,//复制成功
		droped?: boolean,//删除了目标表后再复制
		ignore?: boolean,//复制成功，但是存在部分数据缺失
		error?: boolean,//复制失败
		importRowcount: number,//目标表导入行数
		finalRowcount: number,//目的表最终行数
		exportRowcount: number,//原始表导出行数
		originalRowcount: number,//目的表最初有多少行数据
		time: number//耗时
	}[]
}

/**
 * 复制表重名解决策略
 */
declare const enum CopyTablesMode{
	/**
	 * 创建新表
	 */
	createNewTable = 1,
	/**
	 * 覆盖表
	 */
	overwrite = 2,
	/**
	 * 清空表
	 */
	clearTable = 4,
	/**
	 * 追加记录
	 */
	append = 8,
	/**
	 * 更新记录
	 */
	update = 10
}

interface CopyTableInfo {
	tableDatasource?: string,//支持指定来源表的数据源，该参数优先级高于整体设置
	tableName: string,//这里的tableName既可以是表名也可以是sql，如果是表名需要带上schema，即`schema.tableName`的形式
	desc?: string,//支持传递表备注
	filter?: string,
	/**是否创建目标表结构，默认为true */
	createTargetTable?: boolean,
	/**是否清理目标表 */
	dropTargetTable?: boolean,
	targetTableName: string,//需要带上schema，即`schema.tableName`的形式
	importMode?: CopyTablesMode
}