一个小小的商业智能引擎。
Nerium的Python项目详细描述
橙
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<厘米厘米厘米厘米D2D62696379636C652D736D2E6A7067" /><<<<<<<<<<<<<<<一个轻量级的基于响应程序的微服务,它向数据库提交查询并返回机器可读的序列化结果(通常是json)。与静态站点生成器类似,nerium从存储在文件系统上的本地文件读取其查询和序列化格式。这个想法是,报表分析师应该能够在他们首选的本地编辑器中编写查询,并在nerium可以使用它们的地方上传或挂载它们。
OAO使用Nerium轻松快速地向JSONAPI提供PostgreSQL数据仓库的报告结果。
Nerium具有可扩展的体系结构,允许支持多种查询类型和输出格式。
当前支持使用优秀的记录库进行SQL查询。为了与记录的使用保持一致,可以用key=value
格式指定查询参数,并且(安全地!)以格式插入到查询中:键
格式。
理论上,可以为非SQL查询语言添加其他查询类型(在nerium/resultset
下)。这是一个有前途的未来发展领域。
默认json输出将数据
表示为一个对象数组,每个结果行一个,数据库列名作为键。因此,默认方案为name
、元数据
和参数
提供顶级节点(详细信息如下)。也可以请求compact
json输出格式,使用单独的列
(列名数组)和数据
(行值数组数组)节点来实现紧凑性。通过将"棉花糖"模式定义添加到文件格式中,可以添加其他格式。
nerium支持sqlalchemy可以支持的任何后端,但由于这些都不是硬依赖项,因此pipfile中不包含驱动程序,dockerfile只支持postgresql。如果您希望nerium与其他数据库协同工作,可以在virtualenv中安装带有 然后将 必须在环境中(或在本地 因为web服务使用响应程序,所以如果在环境中设置,它也会尊重 默认情况下,nerium在启动服务的当前工作目录中的 如果要从单个nerium安装中查询多个数据库,任何单个查询文件都可以将其自己的数据库url定义为yaml front matter中的键(请参见下文)。 或者,要处理具有相同连接的多个文件,请在 注意:特定文件前面的设置将覆盖环境中的子目录级别 如上所述,查询只是放置在local 请注意,nerium在服务器启动时加载查询文件;添加其他查询脚本不需要任何代码或配置更改,但需要重新启动服务器才能使用它们。 查询文件可以选择性地包括ayaml前端内容块。前面的内容位于文件的顶部,由三条虚线隔开,如本例所示: 目前,Nerium的服务与前台的事情没有太大关系。如上所述,它可用于指定查询的数据库连接。对于其他键,默认的响应格式只是在 nerium支持查询中的模板语法。最典型的用例是向查询中添加可选的筛选子句,以便可以重用相同的 Jinja过滤器和其他逻辑也可以应用于输入。 警告! Jinja模板是在一个沙盒环境中呈现的,它应该防止服务器端模板注入和大多数SQL注入策略。然而,它不应该被认为是完全安全的。谨慎使用此功能,坚持使用sqlalchemy style 一个已知的危险情况是,如果您的整个查询文件只进行jinja变量扩展,而不进行其他操作: 对于除内置默认格式和 nerium 要传递到此模块的查询文件应使用与模块名称匹配的文件扩展名命名(例如, 传递到查询扩展名 代码:200 内容: 'default': 当然,数据库查询可能不返回任何结果。在这种情况下,无论指定的格式如何,nerium都将使用空的json数组响应。这不被视为错误,客户应做好适当处理的准备。 代码:200 内容: 代码:400 内容: (无特殊顺序)pip
的python连接器,也可以使用oaodev/nerium中的创建自己的dockerfile。(为了便于安装,可以选择
nerium[mysql]
和nerium[pg]
在setup.py中提供
安装/运行
使用Docker
$ docker run -d --name=nerium \
--envfile=.env \
-v /local/path/to/query_files:/app/query_files \
-v /local/path/to/format_files:/app/format_files \
-p 5000:5000 oaodev/nerium
$ curl http://localhost:5000/v1/<query_name>?<params>
本地安装
pipenv install nerium[pg] --pre
query_files
(以及可选的format_files
)目录添加到项目中,编写查询,并按照下一节中的说明配置应用程序。命令nerium启动运行应用程序的本地uvicorn服务器,监听端口5042。配置
.env
文件中)设置查询连接的数据库URL
。这是最简单的配置选项。端口
。脚本文件路径
query_files
和format_files
中分别查找查询和格式架构文件。查询路径
和格式化路径
可以选择设置环境变量,以便使用文件系统上其他位置的文件。数据源
$query_path
下为每个数据库创建一个子目录,将相关文件放在它们各自的目录下,并在每个子目录中包含一个单独的db.yaml
文件,该文件定义了数据库。ase_url
键。db.yaml
设置和数据库URL
。用法
查询文件
query_files
目录中的文本文件,或环境中由query_path
指定的另一个任意文件系统位置。文件的基本名称(pythonpathlib
parlance中的stem
将确定匹配api端点的{query-name}
部分;文件扩展名(或suffix
)映射到查询类型(字面上是nerium.resultset
模块的名称这将处理查询)。前题
---Author:Joelle van DyneDescription:Returns all active usernames in the system---select username from user;
元数据
对象中传递键和值。(compact
格式化程序只是忽略元数据。)理论上,此机制可用于将查询的相关信息传递给服务的任何客户端:例如,结果中列的数据类型或您拥有的内容。可能包括报告服务和前端开发人员想要协调的任何内容。在尚未设计的格式化程序中,也可以更详细地使用前端内容。Jinja模板
select
语句,而不必在多个文件中重复,例如::key
用于绑定值替换的命名参数,并仔细测试您的特定查询。不管用户是否使用jinja语法,都应该严格限制向用户nerium connects授予的数据库权限。{{{my_whole_query}}
。这将允许执行任意sql,您应该永远不要使用这样的模板。自定义格式文件
compact
之外的序列化格式,可以使用pythonmarshmallow库将模式定义添加到格式文件
目录中。与查询文件类似,应用程序将查找与端点url中指定的{format}
匹配的格式模块名称。应用程序需要一个名为resultschema
的marshmallow.schema子类。传递给此架构的可用属性都是添加了附加
result
和params
属性的原始query
object中的所有属性。(有关如何通过内置格式完成此操作的示例,请参见nerium/schema
。查询类型扩展
resultset
模块应该有一个result
方法,该方法接受一个query
对象和可选的关键字参数(kwargs
)字典,连接到数据源,并以可序列化的python结构(通常是字典列表)返回表格结果。query
对象是amunchified字典,其元素位于getquery()
foo.sql
将被传递到resultset/sql.py
模块)。 API
网址
/v1/<;字符串:查询名称>;?<;query_params>;
/v1/<;string:查询名称>;/<;string:格式>;?<;query_params>;
查询名称
应与给定查询脚本文件的名称匹配,但不包括文件扩展名。url querystring参数传递给调用的数据源查询,与查询文件中指定的任何键匹配。如果缺少查询所需的任何参数,则将返回错误。额外的/无法识别的参数会被默默地忽略(这似乎令人惊讶,但这是用于参数替换的标准sqlalchemy行为)。format
路径可以作为可选的格式化程序名称包含,并且默认为"default"。下面的内容部分介绍了其他受支持的格式化程序选项。或
格式的未知值将自动返回默认值。
方法
获取
成功响应
{"name":"<;查询名称>;","数据":[{<;列名称>;:<;行值">;,等等…,},{etc..},],"元数据":{<;key>;:<;value>;,等等…,},"params":{<;随请求提交查询的名称-值对数组>;}
"压缩":{"列":[<;列名列表>;],"数据":[<;行值数组数组>;]}
/v1/<;字符串:查询名称>;/csv
方法
获取
成功响应
<;csv格式的字符串(带换行符)>;
错误响应
{"error":<;exception.repr from python>;}
粗略的路线图/待办事项
改进/成熟的插件架构
将基类与库分离
包中的实现子类
重构插件方法,使用具有接口标准的模块,而不是抽象类继承可配置/灵活的json输出格式化程序([通过棉花糖模式实现]affixformatter
可以使用较少的硬编码)运行状况检查/默认查询终结点将app.py转换为响应程序
推荐PyPI第三方库