[#112] Add basic documentation for placement policies #116

ale64bit · 2023-07-11T12:26:46Z

ale64bit commented

2023-07-11 12:26:46 +00:00

Doc can be previewed e.g. here: https://git.frostfs.info/ale64bit/frostfs-sdk-go/src/branch/feature/112-policy-docs/doc/policy.md

Signed-off-by: Alejandro Lopez a.lopez@yadro.com

Doc can be previewed e.g. here: https://git.frostfs.info/ale64bit/frostfs-sdk-go/src/branch/feature/112-policy-docs/doc/policy.md Signed-off-by: Alejandro Lopez <a.lopez@yadro.com>

🚀 4

ale64bit requested review from storage-core-committers 2023-07-11 12:27:04 +00:00

ale64bit requested review from storage-core-developers 2023-07-11 12:27:04 +00:00

ale64bit force-pushed feature/112-policy-docs from 32a18b60d3 to 81bc661389

2023-07-11 12:31:12 +00:00

Compare

fyrchik requested review from anikeev-yadro 2023-07-11 12:49:15 +00:00

fyrchik requested review from storage-services-committers 2023-07-11 12:49:15 +00:00

fyrchik requested review from storage-services-developers 2023-07-11 12:49:15 +00:00

alexvanin commented

2023-07-12 06:52:51 +00:00

I really like the visualization!

dstepanov-yadro approved these changes 2023-07-12 07:11:03 +00:00

dkirillov reviewed 2023-07-12 10:00:33 +00:00

doc/policy.md Outdated

					
				@ -0,0 +75,4 @@

				```sql

				FILTER @RedNodes AND (City EQ 'Moscow') AS RedMoscowNodes

				```

				which would select those nodes for which the `Color` attribute equals `Red` and the `City` attribute equals `Moscow`. You can think of the `@` operator as embedding the referenced filter expression verbatim where it's used. This makes it easy to compose filters.

dkirillov commented

2023-07-12 10:00:33 +00:00

Can we explicitly mention that @ can be used only in FILTER section? I was confused a little why we don't use @ when refer to filter in SELECT section for example

Can we explicitly mention that `@` can be used only in `FILTER` section? I was confused a little why we don't use `@` when refer to filter in `SELECT` section for example

ale64bit commented

2023-07-13 07:51:35 +00:00

This is a good point. Done.

Perhaps we could consider removing the reference operator altogether? It's never ambiguous anyway within filter expressions. @fyrchik

This is a good point. Done. Perhaps we could consider removing the reference operator altogether? It's never ambiguous anyway within filter expressions. @fyrchik

fyrchik commented

2023-07-13 13:13:18 +00:00

@ is an operator which returns some expression (basically, a macro).
In SELECT we just need a name.
What do you mean by removing the reference operator? From the doc or from the grammar?

`@` is an operator which returns some expression (basically, a macro). In `SELECT` we just need a name. What do you mean by removing the reference operator? From the doc or from the grammar?

ale64bit commented

2023-07-13 13:33:05 +00:00

From the grammar. It doesn't resolve any ambiguity, so it can be removed.

@ is an operator which returns some expression (basically, a macro).

Sure, but this sublanguage is purely declarative, so it has referential transparency: a filter identifier is the filter.

It can be used only within filter expressions, and in such context, an identifier can only refer to other filters, so there's no real need to qualify those with @. If this is somehow not desirable, then we can enforce that it's also needed when used in SELECT so that its use is consistent.

From the grammar. It doesn't resolve any ambiguity, so it can be removed. > @ is an operator which returns some expression (basically, a macro). Sure, but this sublanguage is purely declarative, so it has referential transparency: a filter identifier *is* the filter. It can be used only within filter expressions, and in such context, an identifier can only refer to other filters, so there's no real need to qualify those with `@`. If this is somehow not desirable, then we can enforce that it's also needed when used in `SELECT` so that its use is consistent.

fyrchik commented

2023-07-13 13:38:57 +00:00

Ok, I see now. It wasn't part of this task, let's create a separate one.
To me @ looks immediately readable, consider

City EQ Moscow AND RedNodes
City EQ Moscow AND RedNodes EQ 2

The meaning depends on the context.
The reasons are historical, I believe, ANTLR should handle this now anyway.

Ok, I see now. It wasn't part of this task, let's create a separate one. To me `@` looks immediately readable, consider ``` City EQ Moscow AND RedNodes City EQ Moscow AND RedNodes EQ 2 ``` The meaning depends on the context. The reasons are historical, I believe, ANTLR should handle this now anyway.

ale64bit commented

2023-07-13 13:41:46 +00:00

Yes, it can be a different task.

To me they both look equally readable. The lack of readability might be from the example's choice of attribute name, e.g. a more natural/fair comparison would be

City EQ Moscow AND RedNodes
City EQ Moscow AND Color EQ Red

The meaning doesn't depend on the context at all. The syntax completely determines the type.

Yes, it can be a different task. To me they both look equally readable. The lack of readability might be from the example's choice of attribute name, e.g. a more natural/fair comparison would be ``` City EQ Moscow AND RedNodes City EQ Moscow AND Color EQ Red ``` The meaning doesn't depend on the context at all. The syntax completely determines the type.

fyrchik commented

2023-07-18 10:53:48 +00:00

Yes, but still, you lose in readability IMO (to parse something you need to look ahead)