timescale / docs.timescale.com-content Goto Github PK

Eventually, an information view should specify the current chunk interval. Until then, we should let folks know how to do this in the docs:

SELECT h.table_name, c.interval_length FROM _timescaledb_catalog.dimension c JOIN _timescaledb_catalog.hypertable h ON h.id = c.hypertable_id;

Should likely add this to hypertable section on specifying dimension, as well as API reference.

Relevant system information:

• OS: Ubuntu 18.04
• PostgreSQL version 10.11
• TimescaleDB version 1.6.0
• Installation method: Docker, image timescale/timescaledb:1.6.0-pg10-oss

Describe the bug
when starting the docker container I get:

[28] ERROR: could not access file "$libdir/timescaledb-1.2.1": No such file or directory
[1] LOG: worker process: TimescaleDB Background Worker Scheduler (PID 28) exited with exit code 1

but everything else seems to run fine after that.

To Reproduce
Steps to reproduce the behavior:

1. Start a docker container with the image timescale/timescaledb:1.2.1-pg10-oss and volumes:
   • database:/var/lib/postgresql/data
   • pg_sock:/var/run/postgresql/
2. Follow the upgrade guide https://docs.timescale.com/latest/using-timescaledb/update-db#update and update the image to timescale/timescaledb:1.6.0-pg10-oss

Expected behavior
The database should start up without any errors.

Actual behavior
[28] ERROR: could not access file "$libdir/timescaledb-1.2.1": No such file or directory

Users sometimes have several time columns in their tables and they wonder, which is of them to chose for time dimension during hypertable creation. Recommendations for choosing the time dimension seems to be missing in best practice. Actually I failed to find any place where we explain that time should increase monotonically and the column is commonly included in to queries so chunk exclusion can happen.

Migrate repo from docs.timescale.com-content to docs

Document alter replication factor after it is implemented.

In the documentation I see the following for create_hypertable:

Convert table conditions to hypertable with time partitioning on time and space partitioning (4 partitions) on location:

SELECT create_hypertable('conditions', 'time', 'location', 4);

This is not an issue, just that reading that description I do not follow what is happening.
What does 4 partitions on location mean?
Some sample output would help.

/faq.md says:

What are my compression options?

Benchmarks show TimescaleDB running on ZFS getting around 4x compression. However,
this can vary based on your data size and type requirements. Please reach
out to us at [email protected] or by [joining our Slack group][]. [Top]

This should be updated to reference https://docs.timescale.com/latest/using-timescaledb/compression :

As of version 1.5, TimescaleDB supports the ability to natively compress data.

and maybe https://blog.timescale.com/blog/building-columnar-compression-in-a-row-oriented-database/ :

91-96% storage savings

Change in content, appearance, or functionality?
Minor point, but the pg_dump and pg_restore section could have more explicit instructions for users with remote databases (e.g. Cloud)

Describe the change
Add an additional line for remote databases to supplement this one...

pg_dump -Fc -f tutorial.bak tutorial

Location(s)
https://docs.timescale.com/latest/using-timescaledb/backup#pg_dump-pg_restore

How soon is this needed?
Not urgent, just a nice to have

The docs contain a page about installing TimescaleDB on Azure. This page is not up to date, since it only mentions PG 9.6 and 10, while Azure support TimescaleDB 1.3.2 on PG11 as described here.

Suggestions for fixing the page to be up-to-date:

1. Add support for PG11 (v 1.3.2).
2. Make a note that TimescaleDB will not be supported on PG 9.6 and 10 in later versions.

Following installation instruction for Fedora-31:
https://github.com/timescale/docs.timescale.com-content/blob/master/getting-started/installation-yum.md

'sudo timescaledb-tune' breaks with error message:
exit: could not execute pg_config --version: exec: "pg_config": executable file not found in $PATH

Workaround - provide path in command line:
sudo PATH=$PATH:/usr/pgsql-11/bin/pg_config timescaledb-tune

https://docs.timescale.com/latest/getting-started/installation/windows/installation-windows

The URL is given as: https://timescalereleases.blob.core.windows.net/windows/timescaledb-postgresql-11_1.7.0-windows-amd64.zip

But 1.7 isn't out yet. Should link to

https://timescalereleases.blob.core.windows.net/windows/timescaledb-postgresql-11_1.6.0-windows-amd64.zip

User 'postgres' not authenticated trying to run psql after yum/dnf local installation:
psql -U postgres -h localhost

Error message: Ident authentication failed for user '...'

Workaround:

1. Change 'ident' to 'trust' in file 'var/lib/pgsql/11/data/pg_hba.conf':
   # TYPE DATABASE USER ADDRESS METHOD
host all all 127.0.0.1/32 trust
2. Restart service
   sudo -u postgres service postgresql-11 restart
3. Set password for superuser
   ALTER USER postgres PASSWORD 'psql'
4. Change 'trust' to 'md5' and restart service - steps similar to described as (1) and (2)

The documentation at https://docs.timescale.com/v1.5/using-timescaledb/reading-data under "SELECT Commands" says SELECT * FROM conditions LIMIT 100; will "Return the last 100 entries written to the 'conditions' hypertable" but that's not how a SELECT with a LIMIT but no ORDER BY works. As the linked PostgreSQL documentation says (under "LIMIT Clause"), if you use LIMIT without ORDER BY "you will get an unpredictable subset of the query's rows".

Suggested fix: remove that example as the example that follows it is a better example of the same thing.

SELECT _timescaledb_internal.stop_background_workers();
SELECT _timescaledb_internal.start_background_workers();

The API doc of add_drop_chunks_policy gives impression that it cannot be applied to the time column of type integer. Furthermore, it is unclear what value to provide for older_than and newer_than. It is also good to link to set_integer_now_func.

It can be similar to add_compress_chunks_policy, but explanation of integer value need to be more clear.

Clarify to users that when installing a non-latest extension, you need to explicitly specify the version being installed:

CREATE EXTENSION timescaledb VERSION '1.7.0';

(The way our packaging works, a common "loader" package is a dependency that is always based on the latest, but has support for prior versions.)

Location(s)
https://docs.timescale.com/latest/getting-started/setup
https://docs.timescale.com/latest/getting-started/installation/docker/installation-docker#postgis-docker

etc.

On Firefox I cannot navigate via keyboard (arrow keys, page up/down, spacebar).
I'm not sure if it is related to my machine, but all other pages are working correctly.

So unfortunately no steps to reproduce.
But perhaps someone else can share their experience on firefox.

I am trying to install timescaledb on Centos 7. I navigated to the timescaledb docs to see what command to use, any considerations, etc. However, the documentation for installation is completely blank.

The page in question: https://docs.timescale.com/latest/getting-started/installation/rhel-centos/installation-yum

On Chrome and Firefox, the only elements that load on the page are the nav bar at the top and the nav drawer to the left with contents. Clicking on another section of the docs such as "Setting Up TimescaleDB" loads content as expected. Trying to click back on "Installing" from there does nothing.

On Chrome for Android, only the top nav bar loads.

On Internet Explorer, the docs don't load at all (not surprised, but worth a shot).

I tried to navigate around a bit and ended up finding the following (more generic) page, but it is unfortunately also blank: https://docs.timescale.com/getting-started/installation

I'm opening up an issue here as it doesn't look like this is expected behavior, considering other pages in the documentation load without problems.

Minor request to correct our Docs Left-Hand menu to "GitHub" v. current "Github" (see screenshot).

Need to denote which version upgrades require restart and which don't

Using TimescaleDB >> Continuous Aggregates

This limit was from pre-compression days when we had per-row overhead. Right now that overhead is a /lot/ less given high compression ratios, so limit is now much higher.

See picture, probably an issue with the parser used? Reproduces in Chrome and Edge.

Users somewhat report permissions errors on Windows installations:

I have PostgreSQL 12 installed already. When I run setup.exe, I get the error "ERROR: could not copy file 'timescaledb-1.7.1.dll': open C:/PROGRA1/POSTGR1/12/lib/timescaledb-1.7.1.dll: Access is denied." Can I get some help completing my installation?

Problem is often related to admin privileges, in which case they should also do install/setup using admin privileges.

Suggested change: Add TIP to WIndows install: https://docs.timescale.com/latest/getting-started/installation/windows/installation-windows

Instruction for local yum/dnf installation should mentions how to start server:

sudo -u postgres service postgresql-11 start

The schema tables in /local/tutorials/prometheus-adapter have misaligned dividers

The following changes need to be documented for 1.6.1

• Changes to drop_chunks (see timescale/timescaledb#1666)
• Changes to add_drop_chunks_policy (see timescale/timescaledb#1666)

Instruction page:
https://github.com/timescale/docs.timescale.com-content/blob/master/getting-started/installation-yum.md

contains hyperlink for '...instructions for adding a postgres user' which is not working:
suite.opengeo.org/docs/latest/dataadmin/pgGettingStarted/firstconnect.html

The package pgcopy is mystyped by pycopy when it's mentioned
in https://docs.timescale.com/latest/tutorials/quickstart-python

....To do this, install pycopy pgcopy using pip3 or the like and then add this line to your list of import statements:...

Another small one in the last paragraph:

Now that you’re able to connect, read, and write to a TimescaleDB instance from your Rails Python application...

Relevant system information:
Irrelevent, website related
Describe the bug
When trying to link directly to the Delta section of the Reading data page, i end up wit ha link to Rate, which is the function above delta.
https://docs.timescale.com/latest/using-timescaledb/reading-data#rate

To Reproduce
Steps to reproduce the behavior:

1. Go to https://docs.timescale.com/latest/using-timescaledb/reading-data
2. Click on the link symbol after Delta
3. Page jumps to Rate

Expected behavior
Page Jumps directly to Delta, not Rate

Actual behavior
Page jumps to Rate

Screenshots

https://docs.timescale.com/latest/api#compression says:

The syntax is:
ALTER TABLE <table_name> SET (timescale.compress, timescale.compress_orderby = ...

but running this command results in the error

ERROR: must set the 'compress' boolean option when setting compression options

The correct options begin with timescaledb. not timescale..

When users encounter issues related to creating caggs or having them properly update we often see that it's attributed to a set of common reasons. We should add a section around "best practices" or "what to check if your caggs aren't working" to the docs.

We'll eventually post below a draft outline for this section; posting as a github issue so that the community could offer their own suggestions before we finalize the docs pages.

Page: https://docs.timescale.com/latest/getting-started/installation/windows/installation-windows

Seems the default version is updated to 1.7, and https://timescalereleases.blob.core.windows.net/windows/timescaledb-postgresql-12_1.7.0-windows-amd64.zip is already available. But there is no option to choose PostgreSQL version:12.

Is it just forget to add the new version, or support for pg12 in 1.7.0 is still in beta stage?

Currently each installation page contains:

Note: TimescaleDB requires PostgreSQL 9.6.3+, 10.9+, or 11.4+

However, Support for 9.6 and 10 are deprecated.

A proposal:

Note: TimescaledDB requires PostgreSQL 11.4+.

Should we mention that support for PostgreSQL 9.6.3+, 10.9+ is deprecated and support for PostgreSQL 12 is coming?

The option timescaledb.create_group_index does not exist, looking in the source it is called timescaledb.create_group_indexes.

https://github.com/timescale/timescaledb/issues/1455

Add a description for how data node bootstrapping works to the documentation.

This is a request for a minor change in content.

In some environments, timescaledb is pre installed, and running CREATE EXTENSION timescaledb; might return an error.

Describe the change

We could ask users to run CREATE EXTENSION IF NOT EXISTS timescaledb;

Therefore, the instructions would be:

\c tutorial --connect to the db where we'll perform the restore
CREATE EXTENSION IF NOT EXISTS timescaledb;
SELECT timescaledb_pre_restore();

-- execute the restore (or from a shell)
\! pg_restore -Fc -d tutorial tutorial.bak


SELECT timescaledb_post_restore(); 

Location(s)
https://docs.timescale.com/latest/using-timescaledb/backup#pg_dump-pg_restore

How soon is this needed?

Not urgent

Chunk sizing in best practices should refer to shared_buffers, as discussed in #294

Current docs page does not make it obvious to users that you cannot use window functions for cont aggs definitions.

Location(s)
https://docs.timescale.com/latest/api#continuous-aggregates

Restrictions section needs the update.

How soon is this needed?
Just a nice to have.

Describe the update
We should have better instructions how to upgrade PG and TimescaleDB concurrently, particularly when there are version interactions, e.g., PG12 isn't supported prior to 1.7, so if coming from PG10/TimescaleDB 1.6, there is a careful order of things that must be done (first upgrade Timescale to 1.7, then pg_upgrade PG to 12). This is also true with TimescaleDB 2.0 drops support for PG 9.6 and 10.

Location(s)
https://docs.timescale.com/latest/using-timescaledb/update-db

How soon is this needed?
Should be done soon to reflect 1.7.

alter_job_schedule sample usage query should be broken into several lines.

See: timescale/timescaledb#1031
Windows install method has to be made as admin.

When users encounter slower-than-expected INSERT performance, we often see that it's attributed to a set of common reasons. We should add a section around "best practices" or "what to check if your inserts are slow" to the docs.

Find below a draft outline of this section; posting as a github issue so that the community could offer their own suggestions before we finalize the docs pages.

This uses an older syntax, which needs the START/STOP in the function declaration. We should use the "easier/prettier" example of where this is inferred from a WHERE predicate:

https://docs.timescale.com/latest/using-timescaledb/reading-data#gap-filling

I haven't been able to find any information about the ANALYZE command in your documentation. Here are a few of my unanswered questions:

1. What is the behavior when I analyze a hypertable?
2. Are all chunks analyzed?
3. Should I disable auto-vacuum and just avoid analyze entirely?
4. Is there a way to only analyze recent chunks or specific time windows rather than all chunks?

One reason I ask is that I recently had an analyze command run for 12 minutes on my test system. I would expect it to take 10 times longer if this were to go to production, so I need to know what is going on. Most of the data I work with arrives within an hour of being recorded; I assume there would be no benefit to analyzing hypertables that are built this way, but this wasn't clear to me from the documentation. However, I also have an infrequent occurrence where days-old, sometimes even weeks-old, data arrives, so I'd like to be able to run ANALYZE on an intelligent basis, if it will improve query performance.

Add docs note that you normally don't want to use both together as compression performs an implicit reorder with segment bys/order bys.

When users encounter slower-than-expected query performance, we often see that it's attributed to a set of common reasons. We should add a section around "best practices" or "what to check if your queries are slow" to the docs.

Find below a draft outline of this section; posting as a github issue so that the community could offer their own suggestions before we finalize the docs pages.