-
Notifications
You must be signed in to change notification settings - Fork 164
Extend computed columns docs with more examples, also rename to "computed fields" #368
Comments
Just noticed #355. I missed that. |
Also noted this comment:
This seems to be wrong - I use computed columns sucessfully in the extra-search-path schemas. This has the advantage, that they don't show up as RPCs in the OpenAPI output. |
I agree. Computed columns should have his own page. It shouldn't be part of API. We could also mention generated columns there. |
Hm. Where do you suggest they should go? When I was just looking for them, before creating this issue, I was intuitively looking in the API section (just not nested in the vertical filtering). I was expecting them somewhere there. |
I was thinking that computed columns were more about Custom Queries(or maybe "extending postgrest") and that the API page was getting long. So I thought it could be its own reference page. (Another example, I think HTTP logic can have a dedicated page) |
Ah, I see where you're coming from. Looking at it this way, I feel like API is indeed a bit long. What do you think about a split across the HTTP vs SQL line? So:
The "Custom Queries" page is more or less a transition between the two parts along the lines of: If you hit the limits with just the request syntax, you might have to do in-database stuff. This would also nicely separate the use-cases:
I feel like "Configuration" could also go into "Administration". That should give us a nice structure of 3 main topics. |
You know, it used to be that way. But I found myself always searching and pointing users to the config section inside "Administration". So I made Configuration its own reference page. This also goes in line with divio's reference concept. "Administration" is more loaded with sysadmin tasks(nginx, systemd), so the config got a bit lost there.
That sounds good, I feel like that would be an explanation.
Yes, sounds that would be an extended Schema Structure. A word of care though, with your suggestion we'd be mixing references(http logic, sps, etc) and explanations(schema structure). I think it's best to follow the divio guides on this matter. We should keep them separate, otherwise docs will become hard to manage. |
Got it, makes sense. Configuration certainly sticks out more like this.
Maybe the "basic question" was hinting in the wrong way, but I certainly meant this in a reference way, not explanation.
I absolutely I agree. In terms of divio, I suggest to do the following:
You mentioned something like "Behind the scenes" somewhere else and we already have "Howto", so those two could be more on the explanation side - one of them rather practical and of them more theoretical. Maybe I did not look carefully enough into "Schema structure" and not all of that is really reference. I certainly think that only the reference stuff should go into "SQL API", the explanation stuff maybe in "Behind the scenes" or "Howto" - wherever it fits more. |
With the pg generated columns, that says:
The term "computed columns" is now a bit confusing, users think computed columns are not possible. So I think we should rename to "computed fields", the term that PostgreSQL uses here.
|
From time to time we get feature request where we suggest to use computed columns instead. Maybe we can extend the docs here a bit with more examples what can be done with those columns. We should also move the section out of the "vertical filtering" subsection, one level up. It's hard to find in there and it does not only apply to vertical filtering, but also to horizontal filtering and ordering.
Collecting issues where we suggest computed columns here, for reference:
The text was updated successfully, but these errors were encountered: