tablelandnetwork / docs Goto Github PK

Update SQL docs / spec re: TRUE/FALSE being supported for integer columns, which is also relevant in Solidity to SQL types docs. Namely, you can pass a value of true or false (not wrapped in ') into an int column; these are aliases to 1 or 0

_{From SyncLinear.com | DOC-42}

Create an example in the docs of how to wire up a form submit function to Tableland using the SDK. Original request: here

• Finish the rest of supported JOIN docs
• Add guide for aliasing
• Add brief about relationships (aka basics about primary keys and 1:1, 1:many, etc)
• Include guides for all supported compound select statements
• Include examples for all supported expressions
  • Operators & parse-affecting attributes
  • Parameters
  • CASE
  • BETWEEN
  • CAST
  • EXISTS
• Examples for all supported aggregate functions
• A list of all (un)supported scalar functions (note: only examples “needed” are the existing docs for JSON functions). WIP list here.
• Open questions:
  • Is WINDOW and/or OVER supported?
  • Is WITH supported?
  • RAISE?
  • RECURSIVE?

_{From SyncLinear.com | DOC-49}

• React (use Vite)
• NextJS
• Nuxt
• Remix
• Svelte
• SvelteKit (also related to Vite)
• Vue
• Vite (if needed, show the generic setup and how to fix issue with optimizeDeps: here)
• Rainbowkit

See here and here for where some ideas came from.

_{From SyncLinear.com | DOC-44}

Check these two PRs:

• tablelandnetwork/go-sqlparser#33
• tablelandnetwork/go-sqlparser#34

Summary

Paragraphs within the docs inject new line characters mid-sentence, which makes it difficult to export markdown and repurpose it elsewhere (e.g., copy/paste into a Notion page). Ideally, there's a build script that fixes this such that the markdown doesn't have the new lines, and exporting specs into other tools is straightforward.

Example

See line 57 -- it should be a continuous sentence instead of starting a new line with link 58's "semicolon-separated...":

The main site links to the docs site for on-chain security; the docs site needs a better link for this.

Leverage wallet and contract-based authentication & authorization. Configure tables with fine-grained row- and column-level write access control.

_{From SyncLinear.com | DOC-41}

Ship docs post-launch changes: #73

_{From SyncLinear.com | DOC-35}

This is just a mirror issue for the discussion happening in Notion.

We want to make it clear that to create a table (currently) you need to both mint and create the table via the gateway. This flow is actually going to change soon, so perhaps we hold off on fixing this directly until we update the docs to the newer (contract based) create flow?

cc @joewagner and @awmuncy

Add an SDK section or page that specifies compatibility with different tech (e.g., webpack version, node version, etc.)

_{From SyncLinear.com | DOC-45}

Update node polyfill page to be more descriptive and include this (via Alchemy): https://docs.tableland.xyz/sdk/reference/node-polyfills

_{From SyncLinear.com | DOC-46}

Now that the docs repo is an "app" with deps, we need to configure dependabot. Let's keep the frequency pretty low, as this isn't critical code updates.

_{From SyncLinear.com | DOC-33}

Create a docs page that provides a reference for all possible errors that can bubble up to the various clients. This type partially exists but is a manual writing process instead of automated, e.g., via a React component.

_{From SyncLinear.com | DOC-26}

The docs provide some high-level cost comparisons as static values, via here. It'd be nice to have a query price estimator that does something like this under the hood but with a real-time price API or user inputs.

_{From SyncLinear.com | DOC-29}

The below is taken from a Discord thread:

@asutula: Did we evaluate the consequences of storing floating point values in text columns of json data? I think it would be ok since the value is handled as and stored as a string on the way in, and could maybe be a problem for read queries where you use a function like json_extract() where the docs explain:

If only a single path P1 is provided, then the SQL datatype of the result is NULL for a JSON null, INTEGER or REAL for a JSON numeric value...

So if we really must stick to our rule that read query results must be deterministic, does this present a problem?

@brunocalza: interesting. gotta investigate that a bit more. but tbh it's getting hard to be very strict with that rule. there are already some scenarios where we cannot guarantee a deterministic result. for example, ORDER BY is one of them. when you sort by a column that is not able to break ties you can have problems,

so let's see how that goes

@jsign: mmm i think that JSON situation might be a problem for the new INSERT with SELECT statements. in that case, feels we should block -> in those SELECTS maybe.
or even in simple UPDATEs, if an UPDATE has UPDATE .... WHERE foo->imafloat :/
so maybe -> should be blocked in all write-queries.
just sharing first thoughts here. agree on thinking of it

Currently, we are mixing a regex and a text statement to explain to our users what is allowed as a table's name prefix:

Where prefix is optional, and may include any characters from the regular expression ([A-Za-z0-9\_]+), but cannot start with a number.

We should follow @carsonfarmer suggestion:

but now reading that, we should not mention regex in the spec doc like that at all, it doesn't read very nicely. it should just describe in prose what we want, and then we have a regex that implements that description in the code

I'd say use this regex: ^([A-Za-z]+[A-Za-z0-9_]*) and then describe it in the docs as: "Where prefix is optional. When a prefix is included it must start with a letter, and be followed by any combination of (zero or more) letters, numbers, and/or underscores."

This makes it easier to get back here within embeds and docs that mirror the content.

Check these two PRs:

• tablelandnetwork/go-sqlparser#33
• tablelandnetwork/go-sqlparser#34

The current registry API docs are not helpful. More use cases should be demonstrated, and the setup steps are missing some imports—see the repo README for fixing this aspect: here

_{From SyncLinear.com | DOC-48}

There should be client-specific FAQs for each client in the "Develop" section: SDK, CLI, smart contracts, gateway API. Note that the "troubleshooting" keyword should be added here so that docs site search pulls up these results.

_{From SyncLinear.com | DOC-51}

Comply with the standard README format used by other repos, including how to start the docs up with npm, Algolia API key, etc.: https://github.com/RichardLitt/standard-readme

_{From SyncLinear.com | DOC-40}

Today we have a problem with letting users manipulate the rowid value of a row, which can result in non-determinism because (quoting SQLite spec):

If the largest ROWID is equal to the largest possible integer (9223372036854775807) then the database engine starts picking positive candidate ROWIDs at random until it finds one that is not previously used.

We've been chatting with @brunocalza about this problem, and it's quite nuanced.

Some notes about this problem:

• If the user defines a INTEGER PRIMARY KEY (with or without AUTOINCREMENT), it becomes an alias for rowid, which is the crux of the problem.
• If we allow the user to assign 9223372036854775807 to rowid, _rowid_, oid then the next insert would be non-deterministic.
• The above bullet also applies to a column name the user-defined as INTEGER PRIMARY KEY (with or without AUTOINCREMENT).
• PRIMARY KEYs that aren't INTEGER won't create an alias, which can help narrow down the spec change.

Tentative/fuzzy idea skeleton:

• If a user wants to define an INTEGER PRIMARY KEY (with or without AUTOINCREMENT), it should have a fixed name defined by the spec (e.g: say __id). The idea is to allow the parser to detect invalid queries (see point below)
• The spec should only allow a direct assignment or updates to column names rowid, _rowid_, oid or __id with constant values lower than some number X (where X << 9223372036854775807).
• User defined PRIMARY KEYs which aren't INTEGER looks like they are safe to have arbitrary assignments.

The above are some quick notes, we need to jump into a convo about this to dive deeper.
We have to remember to discuss what this means for existing history.

The specs folder in root is not used. Instead, it was duplicated/slightly altered into the docs folder so that it could be successfully rendered—i.e., ./docs/specs is what gets shown when visiting the SQL specification page.

• Delete the rootspecs folder.
  • Note: the reason the ./specs markdown files cannot be used it because LaTex did not work for any maths unless the file is placed in the docs folder. Perhaps there's a way to fix this, which would be nice to keep specs top-level instead of nested in docs; a nice to have.
• Restructure the folder in docs into decomposed sidebar pages (aka not a monolithic single page of all SQL specs but easier to navigate).

Alternatively, it may make sense to use deployment build scripts to enable this structure. Namely, the README outlines how the specs top-level folder creates a README using files in the specs/sql folder. Maybe, that build script should keep spec/sql and copy what's needed into the docs/specs folder. Just an idea.

_{From SyncLinear.com | DOC-52}

It seems like so far we are assuming lowercase string output for all AST components, which seems fine. Since we aren't exposing the AST to the outside world (yet), a canonical encoding (JSON?) of the tree state itself isn't really required at this time... but it would be nice to spec and document the string encoding and finalize that sooner rather than later.

I would propose we stick with lowercase string outputs. It would be nice to have a canonical JSON representation as well, at least to help with future-proofing ourselves to a degree. In that case, I would propose we use lower-case, snake-case field names for all AST nodes and elements.

If we are happy with this, then we can update our spec with this information.

cc @sanderpick @brunocalza @jsign

Discussion already started in Tableland public APIs across platforms are inconsistent. We have to finish a final spec.

The use cases overview page is lacking. This should probably be a dropdown that has dedicated pages describing each use case in more detail. https://docs.tableland.xyz/fundamentals/use-cases/

_{From SyncLinear.com | DOC-50}

Example: https://gist.github.com/joewagner/f240b91246081dbd1202b13a0714f802

_{From SyncLinear.com | DOC-28}

Example subgraph code: https://github.com/anudit/tableland-subgraph