timescale
[Docs RFC]Revisit the hypertables docs about foreign keys
I feel like our docs are actually a huge mess for how this kind of stuff works. When I google hypertable foreign keys, I find this one: https://docs.timescale.com/self-hosted/latest/distributed-hypertables/foreign-keys/ Which is about distributed hypertables which are apparently deprecated for a long time already. So not sure why this outperforms our more generic docs: https://docs.timescale.com/use-timescale/latest/schema-management/about-constraints/ This docs page mentions: Hypertables support all standard PostgreSQL constraint types, except for foreign key constraints from a hypertable referencing another hypertable. Which is good but google ranks this closed and not fixed github issue result higher: https://github.com/timescale/timescaledb/issues/1394 This links to: https://github.com/timescale/timescaledb/issues/498 which is apparently an open feature request for foreign keys in hypertables However there is a comment in here that links to this PR: https://github.com/timescale/timescaledb/pull/6989 Which says: Currrently we only allow Hypertables references other tables, with this patch the opposite direction is supported as well and tables can have foreign key references into hypertables. So what now? Foreign keys are an open issue while they don't support foreign keys into other hypertables (or rather they do according to the PR?) To make it even better when you look generically for hypertable limitations I find this: https://docs.timescale.com/use-timescale/latest/limitations/ Which again mentions that foreign keys between hypertables don't work? And also talks a whole lot about a long time deprecated feature with distributed hypertables without the docs page being marked as deprecated. My take away would be, if I can trust the PR it all works and all the open and closed issues as well as the docs are inconsistent and lying. (edited)
As an outsider who recently discovered TimescaleDB I found the docs very confusing - and not just around the foreign keys but that one took me a couple of hours to figure out.
I'm not in any way mean disrespect as I'm grateful for the project, just sharing my perspective.
Regarding the rankings:
- It seems that neither https://docs.timescale.com/self-hosted/latest/distributed-hypertables/foreign-keys/ nor https://docs.timescale.com/use-timescale/latest/schema-management/about-constraints/ are currently ranking for "hypertable foreign keys" on the first page. If the outdated page ranked higher before, it was because it's dedicated to foreign keys and uses this keyword multiple times, while the more generic up-to-date page is about constraints in general (only uses the keyword once). No surprise here. I assume the distributed section will be deleted with time and through the AI optimization/restructuring effort anyway.
- Github has the authority of Github, that's why Google ranks its pages high. Plus each of those pages mentions "foreign key constraint" a million times. No way (or use) for us to push them down and honestly not an issue.
- With proper optimization which is planned, the entire hypertable doc section should rank better.
Regarding the open development tickets and PRs:
- All of them are now closed/merged with explanations why, so there are no open issues.
- Older tickets cannot be seen as a source of truth for the current state of things (the first ticket is as old as 2019, not sure why we would be looking there at all).
- When I google, I get another selection of tickets, so this is a per-reader assortment.
Regarding the doc updates:
In both mention pages, the docs reflect the current state of things, which is:
Hypertable -> regular table - Yes Regular table -> hypertable - Yes Hypertable -> hypertable - No
I have made it a bit clearer in this PR: https://github.com/timescale/docs/pull/4115/files Also moved the limitations concerning distributed pages to the dedicated section of the docs.
As an outsider who recently discovered TimescaleDB I found the docs very confusing - and not just around the foreign keys but that one took me a couple of hours to figure out.
I'm not in any way mean disrespect as I'm grateful for the project, just sharing my perspective.
Hi! We really appreciate input from our community on where we can make the docs better, so please don't be shy. See https://github.com/timescale/docs/blob/latest/README.md for how to contribute. Thanks!