docs/tech-notes: adding a note about JSONB key encoding

[Shivs11]

This commit adds a tech note that goes ahead to explain
how JSON will be key encoded in CRDB. It builds on the
RFC for JSONB encoding and explains the main motivation
behind the requirement for a key encoding in the first
place. The tech note also dives into details pertaining
to the encoding for each of the present JSON values:
NULL, Strings, Numbers, Boolean, Arrays and Objects.

Lastly, the tech note also consists of examples showing
how JSON values are encoded in hopes of simplifying the
concept to a new reader.

Release note: None

Epic: CRDB-24501

[cockroach-teamcity]

This change is 

[rytaft]

Nice work!

Reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @mgartner and @Shivs11)

---

docs/tech-notes/jsonb_forward_indexing.md line 4 at r1 (raw file):

This document intends to build on the JSONB value encoding RFC

Add a link to the RFC

Currently, it is only possible to value-encode JSONB values in CRDB....

Since you're implementing key encoding right now, I would change this paragraph to say that the key encoding does exist, and this doc explains how it works.

---

docs/tech-notes/jsonb_forward_indexing.md line 8 at r1 (raw file):

The motivation and use-cases for including JSONB were included in the scoping RFC of JSONB.

Add a link

Currently, it is only possible to value-encode...

Same comment as above

---

docs/tech-notes/jsonb_forward_indexing.md line 32 at r1 (raw file):

4. Moreover, arrays with equal number of elements are compared in the order:
element - 1, element - 2, element - 3, ….

nit: this notation is a bit confusing, since it looks like you are subtracting 1 from element. Perhaps element1, element2, element3, ... would be clearer?

---

docs/tech-notes/jsonb_forward_indexing.md line 35 at r1 (raw file):

5. Objects with an equal number of key value pairs are compared in the order:
key - 1, value - 1, key - 2, value - 2, ….

same comment here

---

docs/tech-notes/jsonb_forward_indexing.md line 37 at r1 (raw file):

Moreover, care has to be taken to ensure that none of these bytes correspond to a possible encoding of a JSON value.

I thought we decided this wasn't a concern?

---

docs/tech-notes/jsonb_forward_indexing.md line 100 at r1 (raw file):

JSONB_Array, enc(1), enc(1), JSONB_Terminator,

Are you missing JSONB_Number in between the two enc(1)? And a second JSONB_Terminator at the end of the array?

JSONB_String, enc(b),

Are you missing a JSONB_Terminator here?

[Shivs11]

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @mgartner and @rytaft)

---

docs/tech-notes/jsonb_forward_indexing.md line 4 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

This document intends to build on the JSONB value encoding RFC

Add a link to the RFC

Currently, it is only possible to value-encode JSONB values in CRDB....

Since you're implementing key encoding right now, I would change this paragraph to say that the key encoding does exist, and this doc explains how it works.

Done!

---

docs/tech-notes/jsonb_forward_indexing.md line 8 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

The motivation and use-cases for including JSONB were included in the scoping RFC of JSONB.

Add a link

Currently, it is only possible to value-encode...

Same comment as above

Done!

---

docs/tech-notes/jsonb_forward_indexing.md line 32 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

nit: this notation is a bit confusing, since it looks like you are subtracting 1 from element. Perhaps element1, element2, element3, ... would be clearer?

I agree. Changes have been made.

---

docs/tech-notes/jsonb_forward_indexing.md line 35 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

same comment here

Done.

---

docs/tech-notes/jsonb_forward_indexing.md line 37 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

Moreover, care has to be taken to ensure that none of these bytes correspond to a possible encoding of a JSON value.

I thought we decided this wasn't a concern?

You're right. The well defined structure of the encoding could resolve this issue. Removing this.

---

docs/tech-notes/jsonb_forward_indexing.md line 100 at r1 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

JSONB_Array, enc(1), enc(1), JSONB_Terminator,

Are you missing JSONB_Number in between the two enc(1)? And a second JSONB_Terminator at the end of the array?

JSONB_String, enc(b),

Are you missing a JSONB_Terminator here?

Yes, thank you for the catch. Was also missing a JSONB_Terminator at the very end of the last example to notify the end of an object.

[Shivs11]

Thank you for the review!

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @mgartner and @rytaft)

[rytaft]

Reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @mgartner and @Shivs11)

---

docs/tech-notes/jsonb_forward_indexing.md line 5 at r2 (raw file):

This document intends to build on the JSONB value encoding [RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20171005_jsonb_encoding.md). 
Previously, it was only possible to value-encode JSONB values in CRDB. The following document proposes a format 

nit: "proposes" still sounds like this is a feature that you haven't yet implemented. I'd say "describes" instead.

---

docs/tech-notes/jsonb_forward_indexing.md line 6 at r2 (raw file):

This document intends to build on the JSONB value encoding [RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20171005_jsonb_encoding.md). 
Previously, it was only possible to value-encode JSONB values in CRDB. The following document proposes a format 
for key-encoding JSONB values in hopes of having a semantic ordering for JSON which in turn allows forward indexes on JSON columns. 

ditto "in hopes of" -- maybe "for the purpose of" is better

---

docs/tech-notes/jsonb_forward_indexing.md line 113 at r2 (raw file):

enc('{“a”: ‘[1]’, “b”: {“c”: 0}'::JSONB)

Looks like you're missing a closing }

[Shivs11]

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @mgartner and @rytaft)

---

docs/tech-notes/jsonb_forward_indexing.md line 5 at r2 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

nit: "proposes" still sounds like this is a feature that you haven't yet implemented. I'd say "describes" instead.

Done!

---

docs/tech-notes/jsonb_forward_indexing.md line 6 at r2 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

ditto "in hopes of" -- maybe "for the purpose of" is better

Done.

---

docs/tech-notes/jsonb_forward_indexing.md line 113 at r2 (raw file):

Previously, rytaft (Rebecca Taft) wrote…

enc('{“a”: ‘[1]’, “b”: {“c”: 0}'::JSONB)

Looks like you're missing a closing }

Done!

[rytaft]

Reviewed 1 of 1 files at r3, all commit messages.
Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @mgartner)

[mgartner]

Nicely done! Be sure to update this when we decide how to handle the encoding of an empty JSONB array.

[Shivs11]

Sure thing @mgartner! Thank you for the review!

Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @yuzefovich)

[Shivs11]

bors r+

[craig]

Build succeeded:

• Bazel Essential CI (Cockroach)