Feedback from a newcomer & broken links

Site Feedback
1

Hi All,

I’ve spent the last few days looking at xtdb as a complete newcomer, and I thought it might be useful to let you know where I’ve struggled and what was useful.

I think the first thing to note is that there is a lot of assumption in the documentation that we already know about Clojure and how to get “things” set up. For instance, I simply installed clojure from apt, and eventually realised that it was too old. (-M isn’t supported).

I found the v2 docker container to be extremely useful for getting started, so quickly moved to trying that. (Although without really considering how new it was at the time). It would be great if there was a v1 docker image that provides a rest api too, but I didn’t find one.

However, by far the most frustrating experience I’ve found is that there are so many broken links on the website. Also, more often than not, a broken link will take you to the main site instead of showing a 404, so you don’t immediately realise that the link is broken. Even worse, on the docs site there seems to be no 404 content, so the page is blank. And most of the links I found externally seem to point to docs that don’t exist any more.
(I assume that the docs site has been recently renamed to v1-docs(?), but it would be really good if this was v2-docs that “changed” instead! Or some other mechanism to keep links.)

As I was more interested in experimenting with the rest api initially, I found the openapi docs to be useful. However it would be great if the examples could form a complete eg curl command that we can run, as the context is often difficult to determine. (I’ve still not figured out how to “limit” the query, any tips gratefully received!).

Finally, although I don’t yet know if xtdb is good for our use case, I commend you on what looks like an excellent product and wish you all the best with v2.

I have intentionally not been too specific, or given examples, as I don’t want you to think that this is a request. I hope my feedback is taken with the spirit in which it is offered.

1 Like
2

Hi @lilphil thank you for writing up all this feedback :pray:

We are definitely keen to make the experience as smooth a possible, and it’s safe to say I have now bumped “404 link checking” way up my own priority list :slightly_smiling_face: also, we are going to be making loads of new changes to the website & docs very soon (ahead of wider v2 promotion) so it’s a good opportunity to take stock.

I’ve still not figured out how to “limit” the query, any tips gratefully received!

This should work, but let me know if not:

curl -X POST localhost:3000/query \
     -H "Content-Type: application/json" \
     -d '{"query":[{"rel": [ {"a": 1, "b": 2 }, { "a": 3, "b": 4 } ], "bind": [ "a", "b" ]}, {"limit": 1}]}'

# returning {"a":1,"b":2}

Out of interest, what is your client language of choice?

3

Hi @refset,

Thanks for the hint on limit, I’ve now realised where I was getting confused in finding this (and google was not my friend today). The getting started page has a “What is XTQL” underneath, and I kept skipping over that with the assumption that I would be using XTQL later and for now “I need to find the api pages”! Perhaps that was side effect of having the “At a glance” page in the middle so I thought the getting started was over, but totally my fault in not seeing the wood for the trees.

Personally my language of choice is “whatever fits”, but that said it’s likely that we would be using Java for this project :slight_smile:

If there is any information on how xtdb performs at scale (what a wide question I know!) then I’d appreciate it if you could point me in the right direction, and I’d be really interested to hear more about the timeline of v2 if it’s “coming soon”.

4

The blog’s RSS feed (XTDB Blog) also has broken links. For example, the latest entry in the feed links to /blog/2024-02-26-dev-diary-feb-24, which should be /blog/dev-diary-feb-24. They all appear to follow this pattern.

(Links abbreviated due to posting policies).