Skip to content
This repository was archived by the owner on Nov 13, 2024. It is now read-only.

Commit 527dbec

Browse files
Celia18305cloud8little
Celia18305
and
cloud8little
authored
update filter description (#1317)
* update filter description * Update oracle.md * Update docs/en-us/advanced/oracle.md Co-authored-by: cloud8little <[email protected]> * Update docs/zh-cn/advanced/oracle.md Co-authored-by: cloud8little <[email protected]> * Update docs/zh-cn/advanced/oracle.md Co-authored-by: cloud8little <[email protected]> Co-authored-by: cloud8little <[email protected]>
1 parent 88d9f2f commit 527dbec

File tree

2 files changed

+146
-6
lines changed

2 files changed

+146
-6
lines changed

‎docs/en-us/advanced/oracle.md

Lines changed: 75 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -114,13 +114,13 @@ As shown above, there are two key functions in the contract:
114114

115115
The following fields are required for Oracle Request：
116116

117-
| Fields | Type | Desc |
117+
| Fields | Type | Description |
118118
| -------------- | --------- | ------------------------------------------------------------ |
119-
| Url | string | the resource path, with a maximum length of 256 bytes |
120-
| Filter | string | used to filter out useful information from the result returned from the data source. It is a JSONPath expression with a maximum length of 128 bytes. More information about JSONPath can be found [here](https://github.com/json-path/JsonPath) |
119+
| Url | string | The resource path, with a maximum length of 256 bytes |
120+
| Filter | string | Used to filter out useful information from the result returned from the data source. It is a JSONPath expression with a maximum length of 128 bytes. For the filters supported by Oracle, see the explanation below. |
121121
| CallbackMethod | string | method name of the callback function (cannot begin with "_"), with a maximum length of 32 bytes|
122-
| UserData | var bytes | the custom data |
123-
| GasForResponse | long | the fee paid in advance for the callback function to pay for executing the script in the Response transaction. The fee should not be less than 0.1 GAS and will be charged when creating the Oracle request transaction |
122+
| UserData | var bytes | The custom data |
123+
| GasForResponse | long | The fee paid in advance for the callback function to pay for executing the script in the Response transaction. The fee should not be less than 0.1 GAS and will be charged when creating the Oracle request transaction |
124124

125125
#### Url
126126

@@ -144,6 +144,76 @@ Command `header` can be used to get header of an object, it doesn't have any par
144144

145145
Command `hash` can be used to get SHA256 hash of an object or part of it, it has an optional range parameter with the same syntax as for `range` command. Example: Example: neofs://C3swfg8MiMJ9bXbeFG6dWJTCoHp9hAEZkHezvbSwK1Cc/3nQH1L8u3eM9jt2mZCs6MyjzdjerdSzBkXCYYj4M4Znk/hash.
146146

147+
#### Filter
148+
149+
Given the following Json example, the Oracle supported filters are illustrated in the table below.
150+
151+
```json
152+
{
153+
"store": {
154+
"book": [
155+
{
156+
"category": "reference",
157+
"author": "Nigel Rees",
158+
"title": "Sayings of the Century",
159+
"price": 8.95
160+
},
161+
{
162+
"category": "fiction",
163+
"author": "Evelyn Waugh",
164+
"title": "Sword of Honour",
165+
"price": 12.99
166+
},
167+
{
168+
"category": "fiction",
169+
"author": "Herman Melville",
170+
"title": "Moby Dick",
171+
"isbn": "0-553-21311-3",
172+
"price": 8.99
173+
},
174+
{
175+
"category": "fiction",
176+
"author": "J. R. R. Tolkien",
177+
"title": "The Lord of the Rings",
178+
"isbn": "0-395-19395-8",
179+
"price": 22.99
180+
}
181+
],
182+
"bicycle": {
183+
"color": "red",
184+
"price": 19.95
185+
}
186+
},
187+
"expensive": 10,
188+
"data": null
189+
}
190+
```
191+
192+
| Filter | Result |
193+
| ------------------------------------- | ------------------------------------------------------------ |
194+
| $.store.book[*].author | The authors of all books |
195+
| $..author | All authors |
196+
| $.store.* | All things, both books and bicycles |
197+
| $.store..price | The price of everything |
198+
| $..book[2] | The third book |
199+
| $..book[-2] | The second to last book |
200+
| $..book[0,1] | The first two books |
201+
| $..book[:2] | All books from index 0 (inclusive) until index 2 (exclusive) |
202+
| $..book[1:2] | All books from index 1 (inclusive) until index 2 (exclusive) |
203+
| $..book[-2:] | Last two books |
204+
| $..book[2:] | Book number two from tail |
205+
| $..book[?(@.isbn)] | Invalid Filter |
206+
| $.store.book[?(@.price < 10)] | Invalid Filter |
207+
| $..book[?(@.price <= $['expensive'])] | Invalid Filter |
208+
| $..book[?(@.author =~ /.*REES/i)] | Invalid Filter |
209+
| $..book[(@.length-1)] | Invalid Filter |
210+
| $..* | Invalid Filter |
211+
| $.. | Invalid Filter |
212+
| $.* | All store value and expensive,data value |
213+
| empty string | Give me the original result |
214+
215+
The returned result can be found at https://github.com/json-path/JsonPath.
216+
147217
### Callback function
148218

149219
The type and order of the parameters of the callback function should exactly be the same as below:

‎docs/zh-cn/advanced/oracle.md

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ Oracle Request 请求中需要指定以下字段：
117117
| 字段 | 字节数 | 描述 |
118118
| -------------- | --------- | ------------------------------------------------------------ |
119119
| Url | string | 访问资源路径。最大长度为256字节 |
120-
| Filter | string | 过滤器，用于在从数据源返回的结果中过滤出有用信息，其中 Filter 字段为 JSONPath 表达式，最大长度为128字节。更多关于 JSONPath 的信息，可查看 [此处 ](https://github.com/json-path/JsonPath)。 |
120+
| Filter | string | 过滤器，用于在从数据源返回的结果中过滤出有用信息，其中 Filter 字段为 JSONPath 表达式，最大长度为128字节。Oracle 支持的 Filter 规则请参见后文解释。 |
121121
| CallbackMethod | string | 回调函数方法名。最大长度为32字节，且不能以“_”开头 |
122122
| UserData | var bytes | 用户自定义数据 |
123123
| GasForResponse | long | 回调函数执行预付款，用于支付Response交易执行所需的费用。预付款应不小于 0.1 GAS，否则无法发起 Oracle 请求。预付款会在Request构建时自动扣除。 |
@@ -162,6 +162,76 @@ neofs://C3swfg8MiMJ9bXbeFG6dWJTCoHp9hAEZkHezvbSwK1Cc/3nQH1L8u3eM9jt2mZCs6Myjzdje
162162
neofs://C3swfg8MiMJ9bXbeFG6dWJTCoHp9hAEZkHezvbSwK1Cc/3nQH1L8u3eM9jt2mZCs6MyjzdjerdSzBkXCYYj4M4Znk/hash
163163
```
164164

165+
#### Filter
166+
167+
这里通过如下 Json 示例来说明 Oracle 支持的 Filter 规则。
168+
169+
```json
170+
{
171+
"store": {
172+
"book": [
173+
{
174+
"category": "reference",
175+
"author": "Nigel Rees",
176+
"title": "Sayings of the Century",
177+
"price": 8.95
178+
},
179+
{
180+
"category": "fiction",
181+
"author": "Evelyn Waugh",
182+
"title": "Sword of Honour",
183+
"price": 12.99
184+
},
185+
{
186+
"category": "fiction",
187+
"author": "Herman Melville",
188+
"title": "Moby Dick",
189+
"isbn": "0-553-21311-3",
190+
"price": 8.99
191+
},
192+
{
193+
"category": "fiction",
194+
"author": "J. R. R. Tolkien",
195+
"title": "The Lord of the Rings",
196+
"isbn": "0-395-19395-8",
197+
"price": 22.99
198+
}
199+
],
200+
"bicycle": {
201+
"color": "red",
202+
"price": 19.95
203+
}
204+
},
205+
"expensive": 10,
206+
"data": null
207+
}
208+
```
209+
210+
| Filter | 返回结果 |
211+
| ------------------------------------- | ------------------------------------------ |
212+
| $.store.book[*].author | 所有图书的作者 |
213+
| $..author | 所有作者 |
214+
| $.store.* | 所有信息，包括书和自行车 |
215+
| $.store..price | 所有东西的价格 |
216+
| $..book[2] | 第三本书 |
217+
| $..book[-2] | 倒数第二本书 |
218+
| $..book[0,1] | 前两本书 |
219+
| $..book[:2] | 从索引0（包含）到索引2（不包含）的所有图书 |
220+
| $..book[1:2] | 从索引1（包含）到索引2（不包含）的所有图书 |
221+
| $..book[-2:] | 最后两本书 |
222+
| $..book[2:] | 从尾部开始的第二本书 |
223+
| $..book[?(@.isbn)] | 无效 Filter |
224+
| $.store.book[?(@.price < 10)] | 无效 Filter |
225+
| $..book[?(@.price <= $['expensive'])] | 无效 Filter |
226+
| $..book[?(@.author =~ /.*REES/i)] | 无效 Filter |
227+
| $..book[(@.length-1)] | 无效 Filter |
228+
| $..* | 无效 Filter |
229+
| $.. | 无效 Filter |
230+
| $.* | 所有 store 数据和 expensive 数据 |
231+
| empty string | 源json数据 |
232+
233+
返回结果可在 https://github.com/json-path/JsonPath 查询获得。
234+
165235
### Callback 回调函数
166236

167237
回调函数的形参的参数类型和顺序被严格限定，必须遵守以下规则顺序：

0 commit comments

Comments
 (0)