Skip to content

Conversation

knz
Copy link
Contributor

@knz knz commented Jan 17, 2017

Fixes #992.

This change is Reviewable

@knz knz force-pushed the knz-updates branch 3 times, most recently from ba26800 to fe1b2e9 Compare January 17, 2017 21:50
@cockroach-teamcity
Copy link
Member

@knz knz changed the title [WIP - do not merge] New docs on expressions and constants New docs on expressions and constants Jan 17, 2017
Copy link
Contributor

@jseldess jseldess left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whoa! Amazing work, @knz! Thank you so much for taking this on.

I'm reviewing in two batches. Here are suggestions/questions on the changes to the existing data type pages. Next, I'll review the new pages.

bytes.md Outdated
- String literal: `'a1b2c3'`

You can also use these in combination, for example, `b'\141\061\x62\x32\c3'`.
When it is not ambiguous, a string literal can also be automatically
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this statement ambiguous ;). @arjunravinarayan also wasn't quite certain about the intention. Can you be more explicit about when a string is not ambiguous? What that means exactly? Perhaps an example?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reworded to clarify.

data-types.md Outdated
- `<value>::<data type>`, or its equivalent longer form `CAST(<value> AS <data type>)`, which converts an arbitrary expression of one built-in type to another (this is also known as type coercion or "casting"). For example:
`NOW()::DECIMAL`, `VARIANCE(a+2)::INT`.

**Note that in many cases it is advisable to use an
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice tip! 2 suggestions:

  1. Instead of bolding the whole thing, let's format it as an actual tip. Here's how (plus some suggested copy edits):
{{site.data.alerts.callout_success}}
In many cases, it is recommended to use a [type annotation](sql-expressions.html#explicitly-typed-expression) instead of a coercion to create a value of an arbitrary type.
{{site.data.alerts.end}}
  1. Should we add a bit of explanation about why type annotation is better in most cases?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added the callout thing and a more clearly worded recommendation.

date.md Outdated
The string format for dates is `YYYY-MM-DD`. For example: `DATE '2016-12-23'`.

Note that in some contexts, dates may be displayed with hours, minutes, seconds, and timezone set to 0.
When it is unambiguous, a simple unannotated string literal can also
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as my comment on bytes.md. I don't understand what we're trying to say here. Can you please be more explicit, rephrase, perhaps include an example, if necessary?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

float.md Outdated

## Format

When inserting into a `FLOAT` column, format the value as a numeric literal, e.g., `1.2345` or `1`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's change the section title to Syntax and replace the first sentence with:

Values of type `FLOAT` must be expressed as [numeric literals](sql-constants.html#numeric-literals).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

For more details about `FLOAT` numeric formats,
see the section on [SQL constants](sql-constants.html).

The special IEEE754 values for positive infinity, negative infinity
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's change interpreted literal to a link:

[interpreted literal](sql-constants.html#interpreted-literals)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

int.md Outdated
### Hexadecimal-Encoded Numeric Literal

When inserting a hexadecimal-encoded numeric literal into a `INT` column, format the value as hexadecimal digits preceded by `0x`. For example, `0xcafe1111` corresponds to the numeric literal `3405648145`.
See the section on [numeric literals](sql-constants.html#numeric-literals) for more details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above, let's change the section title to Syntax and replace this sentence with:

Values of type `INT` must be expressed as [numeric literals](sql-constants.html#numeric-literals).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

---

The `SERIAL` [data type](data-types.html) defaults to a unique 64-bit signed integer. The default value is the combination of the insert timestamp and the ID of the node executing the insert. This combination is guaranteed to be globally unique. Also, because value generation does not require talking to other nodes, it is much faster than sequentially auto-incrementing a value, which requires distributed coordination.
The `SERIAL` [data type](data-types.html) is a column data type which
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for strengthening this! While you're here, can you rename the Format section to Syntax?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

string.md Outdated
## Formats

A `STRING` column accepts Unicode string literals, hexadecimal string literals, and escape strings.
A `STRING` constant can be expressed using a variety of formats,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's retitle this section Syntax and, for consistency, rephrase the content a bit:

Values of type `STRING` can be expressed in a variety of formats. See [string literals](sql-constants.html#string-literals) for more details.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.

string.md Outdated
For example, the `e'x61\141\u0061'` escape string represents the hexadecimal byte, octal byte, and 16-bit hexadecimal Unicode character values equivalent to the `'aaa'` string literal.

Note that any character not in the table above is taken literally in an escape string. Also, when continuing an escape string across lines, write `e` or `E` only before the first opening quote.
When printing out a `STRING` value in the SQL shell, the shell uses the simple
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's make SQL shell a link:

[SQL shell](use-the-built-in-sql-client.html)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

[coerced to](sql-expressions.html#explicit-type-coercions) type
`TIMESTAMP`/`TIMESTAMPTZ`.

`TIMESTAMP` constants can be expressed using the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You removed this type of guidance from other type pages - I assume because the details are available in your value expressions doc? Should we do the same here, or is there a risk that they won't find the correct details via link?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DATE/INTERVAL/TIMESTAMP constants are not lexical elements and thus not distinguishable as separate constant categories in the page "SQL constants". However I agree that a mutual xref was missing; I added it.

@sploiselle
Copy link
Contributor

Review status: 0 of 14 files reviewed at latest revision, 17 unresolved discussions, some commit checks failed.


bytes.md, line 20 at r1 (raw file):

## Formats

To express a byte array constant, see the section on

Quick note before I do a more thorough review: for this and all other data types, I would like to see at least one example of formatting left on the page. The idea being that I can jump to the page and get the information I'm most likely to need, and then find a link to deeper reference material only if I need it.


Comments from Reviewable

@jseldess
Copy link
Contributor

bytes.md, line 20 at r1 (raw file):

Previously, sploiselle (Sean Loiselle) wrote…

Quick note before I do a more thorough review: for this and all other data types, I would like to see at least one example of formatting left on the page. The idea being that I can jump to the page and get the information I'm most likely to need, and then find a link to deeper reference material only if I need it.

@knz, although I didn't say as much in my review, I agree with Sean that simple examples on page are a huge plus for getting users quick answers. I'd say a simple example per expression type mentioned, here and other data type pages.


Comments from Reviewable

@knz
Copy link
Contributor Author

knz commented Jan 19, 2017 via email

Copy link
Contributor

@jseldess jseldess left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, amazing work, @knz. Thanks very much for writing this up!

I have lots of little comments and suggestions, some content-driven, some format-driven. I'm happy to take such revisions on in a follow-up PR, if you prefer. Just let me know.

Also, we should think about how to represent these pages in the sidenav. Not sure what the best approach is here. Might want to create a new section under Develop for these pages as well as, for example, the keywords and identifiers page?

[table expressions](table-expressions.html) which produce results
structured as a table.

A value expression can be:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's necessary to provide this list, given that the auto-generated toc provides the same exact list. Instead, I'd suggest we:

  • Replace the single intro sentence ("Value expressions allow...") with the first two paragraphs of the Introduction section.
  • And then delete the entire Introduction section.

After the two intro paragraphs, and before the toc, we could have a sentence like: The following sections provide details on possible types of value expressions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.


## Introduction

Most SQL statements can contain *value expressions* that compute new
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a comma after SELECT ceil(price) FROM items.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

items` the expression `ceil(price)` computes the rounded-up value of
the values from the `price` column.

Value expressions produce values suitable to store in a single table
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a comma after the table expressions link.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.

Constant expressions represent a simple value that doesn't change.
They are described further in section [SQL Constants](sql-constants.html).

## Column references
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this and all other section headings, let's use title case, i.e., Column References instead of Column references.


## Column references

An expression can refer to columns in the current query in two ways:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be clearer as: An expression in a query can refer to columns in two ways:

sql-constants.md Outdated
[+-]9999.[9999][e[+-]999]
[+-][9999].9999[e[+-]999]
[+-]9999e[+-]999

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove extra line.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

sql-constants.md Outdated
```
The actual data type of a numeric constant depends both on the context
where it is used, its literal format and its numeric value.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use comma before and its numeric value.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.

sql-constants.md Outdated
## Byte array literals
A byte array literal uses the same syntax as string literals containing character escapes,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make [string literals](#string-literals) a link.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

sql-constants.md Outdated
The two differences between byte array literals and string literals with character escapes are:
- byte array literals always have data type `BYTES`, whereas the data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capitalize first letter of each bullet item, and end each with a period.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait what? The paragraph starts with "The two differences ..." above and ends with the last bullet point.

sql-constants.md Outdated
CockroachDB recognizes the following SQL named constants:
- `TRUE` and `FALSE`, the two possible values of data type `BOOL`;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change ; to .

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@knz knz force-pushed the knz-updates branch 3 times, most recently from ebca42c to 6640c43 Compare January 23, 2017 02:27
@cockroach-teamcity
Copy link
Member

@knz
Copy link
Contributor Author

knz commented Jan 23, 2017

I have reworked the sidebar significantly. PTAL

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@jseldess
Copy link
Contributor

sql-constants.md, line 85 at r1 (raw file):

Previously, knz (kena) wrote…

Done.

Parentheses are still there ...?


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-constants.md, line 174 at r1 (raw file):

Previously, knz (kena) wrote…

wait what? The paragraph starts with "The two differences ..." above and ends with the last bullet point.

Yes, you're right. I should have also asked you to rework the intro to the list to be a complete sentence, something like:

The two differences between byte array literals and string literals with character escapes are as follows:


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 60 at r1 (raw file):

Previously, knz (kena) wrote…

done

Whoa! Thank you.


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 69 at r1 (raw file):

Previously, knz (kena) wrote…

I do not like the idea of combining these things anytime soon. There is much more information to share in docs about operators than what fits in our auto-generator, and extending the auto-generator so that it produces output nearly as useful as a simple hand-written chapter on the topic is a non-trivial task.

You're misunderstanding what I meant. I envision adding manually created content to the page with auto-generated content, not getting the auto-generator to produce this type of content. In any case, we can revisit later. This content is great here as well.


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 198 at r1 (raw file):

Previously, knz (kena) wrote…

The whole makes a single paragraph. I do not understand why the need to split it; the semicolons are breaking the reading already as appropriate.

Instead of using a list to form a complete sentence, we introduce a list with a complete sentence and then treat each bullet as an independent item.

Can each of these bullets stand on its own, or are they dependent on each other? If the former, please don't use semicolons.


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 264 at r1 (raw file):

Previously, knz (kena) wrote…

No, and that's another example of why #1009 matters.

OK, point take, and we'll revisit that. But if a column can't contain an array, then we should say "For example, if column a of the current row contains an array...", right?


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 365 at r1 (raw file):

Previously, knz (kena) wrote…
  1. I don't know how to construe meaningful examples (and I still personally think that window functions are a poor feature that ought not to exist).

  2. window functions and processing deserve as separate page anyway. Let's address Document window functions #710 separately.

OK, thanks.


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-expressions.md, line 419 at r1 (raw file):

Previously, knz (kena) wrote…

done

Looks like this didn't actually get done?


Comments from Reviewable

@jseldess
Copy link
Contributor

sql-statements.md, line 2 at r2 (raw file):

---
title: SQL Statements

This is a huge improvement. Thank you, @knz!


Comments from Reviewable

@jseldess
Copy link
Contributor

table-expressions.md, line 7 at r1 (raw file):

Previously, knz (kena) wrote…

I disagree that the intro is unnecessary. The mention that multiple table names after FROM is a cross join is not mentioned elsewhere (for now).

OK.


Comments from Reviewable

@jseldess
Copy link
Contributor

table-expressions.md, line 156 at r1 (raw file):

Previously, knz (kena) wrote…

done

Sorry to have misdirected you here. Can you reformat the the callout to include only html formatting, not markdown?

{{site.data.alerts.callout_info}}
WITH ORDINALITY necessarily prevents some optimizations of the surrounding query. Use it sparingly if performance is a concern, and always check the output of EXPLAIN in case of doubt.
{{site.data.alerts.end}}


Comments from Reviewable

@jseldess
Copy link
Contributor

Thanks for making so many tweaks, @knz. I've included/repeated a few more, but it's look very close now.

I would like to decouple this work from an overahaul of the sidenav, however. There are some strange user experience issues that need to be factored in when designing the sidenav (page url needs to match link url in sidenav in order for the correct section to expand and the sidnav item to get highlighted, for example). And we're already intending to rethink the docs architecture (mostly this section) next quarter, as well as move to another tool that will let us restructure our site hierarchy.

So for now, I'd suggest we go back to the old sidenav with the three new pages simply added to the Develop section.


Comments from Reviewable

@jseldess
Copy link
Contributor

Reviewed 22 of 22 files at r2.
Review status: all files reviewed at latest revision, 17 unresolved discussions, some commit checks failed.


Comments from Reviewable

@knz
Copy link
Contributor Author

knz commented Jan 23, 2017

I'm very confused by the sidenav syntax and I can't seem to get it to work now (although it worked yesterday!). Are you ok with adding this fix after merging this PR?


Review status: 1 of 16 files reviewed at latest revision, 18 unresolved discussions, some commit checks pending.


data-types.md, line 31 at r1 (raw file):

Previously, jseldess wrote…

Thanks, @knz. One more change: I lead you to use markdown formatting for the link inside. Turns out that causes rendering issues. So please format the link as html instead, here an in any other callouts you added:

<a href="sql-expressions.html#explicitly-typed-expressions">type annotation</a>

Done.


date.md, line 47 at r2 (raw file):

Previously, jseldess wrote…

spelling: explicitly

Done.


manual-deployment.md, line 12 at r2 (raw file):

Previously, jseldess wrote…

As mentioned above, I've had to revert the ability to use markdown inside callouts, so we need to revert this to html as well.

Done.


sql-constants.md, line 2 at r1 (raw file):

Previously, jseldess wrote…

Title case, please: Constant Values

Done.


sql-constants.md, line 30 at r1 (raw file):

Previously, jseldess wrote…

Let's change ; to . at the end of each bullet, please. And remove and from the end of the last bullet.

Done.


sql-constants.md, line 85 at r1 (raw file):

Previously, jseldess wrote…

Parentheses are still there ...?

I had forgotten to commit the change. Apologies.


sql-constants.md, line 174 at r1 (raw file):

Previously, jseldess wrote…

Yes, you're right. I should have also asked you to rework the intro to the list to be a complete sentence, something like:

The two differences between byte array literals and string literals with character escapes are as follows:

Done.


sql-expressions.md, line 69 at r1 (raw file):

Previously, jseldess wrote…

You're misunderstanding what I meant. I envision adding manually created content to the page with auto-generated content, not getting the auto-generator to produce this type of content. In any case, we can revisit later. This content is great here as well.

Ok I agree!


sql-expressions.md, line 198 at r1 (raw file):

Previously, jseldess wrote…

Instead of using a list to form a complete sentence, we introduce a list with a complete sentence and then treat each bullet as an independent item.

Can each of these bullets stand on its own, or are they dependent on each other? If the former, please don't use semicolons.

Done.


sql-expressions.md, line 264 at r1 (raw file):

Previously, jseldess wrote…

OK, point take, and we'll revisit that. But if a column can't contain an array, then we should say "For example, if column a of the current row contains an array...", right?

Ok now I see where you're coming from.
The fun thing is that a query can produce arrays in columns by means of SQL expression computations, and these arrays can be used further in the query; however the array values cannot be stored in the database.

We were writing past each other by overlapping the notion of "physical column in storage" and "virtual column of an intermediate result table in a query".

I reworked the explanation accordingly.


sql-expressions.md, line 419 at r1 (raw file):

Previously, jseldess wrote…

Looks like this didn't actually get done?

Again forgot to commit.


sql-statements.md, line 2 at r2 (raw file):

Previously, jseldess wrote…

This is a huge improvement. Thank you, @knz!

😸


table-expressions.md, line 156 at r1 (raw file):

Previously, jseldess wrote…

Sorry to have misdirected you here. Can you reformat the the callout to include only html formatting, not markdown?

{{site.data.alerts.callout_info}}
WITH ORDINALITY necessarily prevents some optimizations of the surrounding query. Use it sparingly if performance is a concern, and always check the output of EXPLAIN in case of doubt.
{{site.data.alerts.end}}

Done.


Comments from Reviewable

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@cockroach-teamcity
Copy link
Member

@knz
Copy link
Contributor Author

knz commented Jan 24, 2017

Just extended this PR to integrate the changes from cockroachdb/cockroach#13094

@cockroach-teamcity
Copy link
Member

@jseldess
Copy link
Contributor

:lgtm: Thanks again, @knz! I'll deal with the sidenav in a follow-up pr. Excited to get this content to users.


Reviewed 16 of 21 files at r3.
Review status: all files reviewed at latest revision, 1 unresolved discussion.


Comments from Reviewable

@jseldess jseldess merged commit ecbff69 into cockroachdb:gh-pages Jan 24, 2017
This was referenced Jan 24, 2017
Simran-B added a commit to Simran-B/docs that referenced this pull request Aug 21, 2025
* Add note about non-root users

* Update getting-started.md

* Update getting-started.md

* Update oasis/getting-started.md

Co-authored-by: Simran <Simran-B@users.noreply.github.com>

* Update getting-started.md

Co-authored-by: ansoboleva <93702078+ansoboleva@users.noreply.github.com>
Co-authored-by: Simran <Simran-B@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants