查询数据源

在卡拉云应用中,你可以通过使用查询(query)来向数据源中读取或者向数据源中写入数据。

👍
请先接入数据源
如果你还没有接入数据源,请先参考接入数据源,只有在接入数据源后,才能在应用中使用查询

查询编辑界面

在进入应用编辑器后,导航栏上方,我们看到有两个分开的区域。第一个是“界面编辑”,即用于拖拽生成组件的画布。另一个是“查询编辑”,即管理应用内的查询的编辑器。

query-editor

点击查询编辑,界面如下

查询编辑面板

上图中,查询编辑器被分为大致三个区域,左侧是查询列表,你可以添加或删除查询。点击某个查询后,右侧上方为一个查询的设置面板。在右侧中间,你可以调整查询对应的数据源。注意,查询面板的设置项会因为数据源的类型不同而不同,比如说一个 REST API 查询需要设置端点,而一个 MySQL 查询需要设置对应的 SQL 语句,设置的选项显然是不一样的。

管理查询

在左侧的查询列表顶端,可以看到 新建查询 按钮。如果需要删除查询,点击查询列表中的查询后的选项按钮,点击删除即可。

删除查询

如果需要更改查询的名称,点击查询的重命名区域,输入新的查询名即可。

重命名查询

👍
查询的命名
与组件一样,查询的命名也必须唯一,且必须以字母开头,仅包含下划线和数字。我们建议将查询名命名为有意义的名称,以增加开发效率减少出错。

查询的触发方式

每个查询均有两种触发方式,即 自动触发手动触发

查询的触发方式

自动触发是指,如果查询中用花括号引用了其它组件或查询的属性,比如 {{textInput1.value}},那么这些属性变化时,查询就会自动执行。同时,当你刷新浏览器或应用最初加载时,也会自动执行一次。

最常见的自动查询包括,当用户输入一些字符时,根据这些字符重新查询 SQL。比如在创建第一个应用的例子中,我们用了一个 SQL 查询

  SELECT * FROM "oeddyo/demo"."orders" 
	WHERE username ILIKE {{"%" + usernameInput.value + "%"}}

那么这个查询就会因为 usernameInput.value 的变化,也即用户输入的文本框的值的变化,而重新查询 SQL 数据库。

什么时候需要自动触发呢?当你的查询为只读查询,且你希望它根据用户输入而变化时,就可以将查询设置为自动查询。

那么什么情况下需要将查询设置为 手动触发 呢?通常来说,任何会更改、删除或更新数据的非只读查询,都应该设置为 手动触发。设置为 手动触发 时,用户必须显示地触发(比如点击按钮)才会让查询开始执行。比如说,如果你有一个查询会删除选中的行,那么你不会希望用户在点击鼠标选中那一行时就直接执行这个查询,因为这样与用户预期可能相差很大。如果你把这个删除查询设置为手动触发,同时在旁边增加一个删除按钮用以触发它,则要符合直觉得多。

总结一下,如果一个查询是只读查询,就可以将其设置为自动触发。反之,设置为手动触发。

📘
何时自动触发何时手动触发?
在 SQL 查询中,任何 UPDATE, DELETE 和 INSERT 操作都应该设置为手动触发。而 SELECT 通常可以设置为自动触发。同理,在 REST API 中,GET 请求由于通常不更改数据,因此适宜于设置为自动触发。而 POST/PUT/DELETE 等操作由于可能更改数据,应该设置为手动触发

从 data 属性中读取数据

每个查询上均预设 data 这个属性。当查询成功时,这个属性中会包含查询到的数据内容。

因此,在使用查询时最常见的操作,莫过于将查询完的数据绑定到一个表格中。绑定时使用的语句即

{{query1.data}}

查询上的data属性

这样就可以将数据从查询中读取出来,并绑定到组件上了。

查询的保存和运行

查询在每次进行任何修改后,会进入”未保存“状态,只有显示地点击”保存“按钮,才会将查询同步到卡拉云的服务器。同时,只有同步好的查询,才可以被执行。

保存状态

如果一个查询需要其它组件触发,但它仍然是未保存状态,此时卡拉云也会报错并提示查询未保存。因此,在对查询进行修改后,请先将查询保存,以确保它可以被正确执行。正确执行后的数据才会更新到查询的 data 属性中。

在保存按钮左侧的云朵,会提示该查询是否已成功保存。

查询触发事件

一个查询执行完成后,可以触发其它事件,比如触发执行另一个查询。有时候,这样的触发机制很有用,我们用一个例子来说明。

假设你有一个查询 getOrders,这个查询的作用是获取所有订单,并绑定到一个表格中。同时,你有另一个查询叫 updateOrder,它可以更新你在表格中选定的行的数据。

那么,当用户更新了表格中的一行时,会期望表格中的数据被自动更新。此时,你就可以在 updateOrder 的执行事件中,添加触发 getOrders 的事件,这样,每当数据更新后,卡拉云会重新获取订单,并重新展示,给用户良好的体验。

常见问题 FAQ

我们列出来一些用户的常见问题和解决方案,供参考

如何只在组件有值时进行 SQL 过滤?

你可能有类似以下的需求:

运营使用一个下拉菜单(或其它组件)来过滤数据,当这个下拉菜单有值选中时,需要过滤选中的数据。如果没有选中时,需要返回全部数据。用一个具体的例子来说明问题,假设运营需要过滤已发货的用户和未发货的用户,那么你在下拉菜单中的设置可能为

发货状态下拉菜单

也即,数据库中如果已经发货,标记为 0 否则为 1。

查询中使用左边的下拉菜单中的值,来过滤数据库中的发货数据,同时右手边的表格中展示从查询中获得的过滤后数据。

我们需要实现:

当运营选择已发货(即 selectStatus.value 为 1)时,查询中需要过滤出你的数据库里发货状态为 1 的所有数据,反之如果运营选择未发货(即 selectStatus.value 为 0)时,查询中需要过滤所有发货状态为 0 的所有数据。而如果运营清空这个选择器,则需要将不管发没发货的数据展示出来。

我们可以用 SQL OR 来实现此需求

SELECT * 
  FROM YOUR_TABLE
  WHERE
    {{!selectStatus.value}} OR newyear_lottery.prize_status = {{selectStatus.value}}   

如何理解这个查询呢?

可以看到 WHERE 中 第一个条件是一个 JS 语句,表明如果下拉菜单 selectStatus.value 的值为非真时(包括 null, 0, 空字符串等),则整个过滤条件为真。也就是说,如果运营没有选择任何值,那么这个条件一定满足。注意如果你需要限定selectStatus.value 中的值是空 (null) 的话,则需要用 {{selectStatus.value===null}} OR newyear_lottery.prize_status = {{selectStatus.value}},以免非空值 0 或空字符串的干扰。

而 OR 中的第二个条件则限定了,当运营选择了一个值时,只有这个值与数据库中的列值匹配,才满足条件。所以总结一下这个 WHERE 语句的含义为

  1. 如果运营没选
  2. 或,如果运营选了但选的值为 selectStatus.value 中的值

综上,使用 OR 查询可以实现所述需求