[DOCS] Reorg field data types page #61117

jrodewig · 2020-08-13T19:30:09Z

Reorganizes the field data types page based on use case.

Also incorporates type families and standardizes usage.

Relates to #57548

Preview

https://elasticsearch_61117.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/mapping-types.html

elasticmachine · 2020-08-18T16:43:47Z

Pinging @elastic/es-search (:Search/Mapping)

elasticmachine · 2020-08-18T16:43:47Z

Pinging @elastic/es-docs (>docs)

jtibshirani

This looks like a nice start! I left a couple preliminary comments.

docs/reference/mapping/types.asciidoc

jtibshirani · 2020-08-19T21:25:06Z

docs/reference/mapping/types.asciidoc

+The following sections organize the available field types based on their
+intended use. Except where noted, the type family is the same as the field type.
+
+<<binary,`binary`>>::


For me this organization is a bit unclear. Some types like binary and boolean don't belong to an overall section. And the sections don't relate to a consistent concept -- some describe use cases like 'full text search' while others are broad type categories like 'dates'.

It's actually quite challenging to come up with a good grouping! I'll reach out to you through another channel with a brainstorming document.

Awesome! Thanks!

jrodewig · 2020-08-20T23:17:02Z

@jtibshirani @markharwood @giladgal

I updated the categorization of the data types based on feedback from the other channel. Please take a look at the preview and leave any additional feedback you have. All feedback welcome!

jtibshirani · 2020-08-21T16:57:53Z

docs/reference/mapping/types.asciidoc

+
+<<binary>>::          `binary`
+<<boolean>>::         `boolean`
+keyword::             <<keyword,`keyword`>>,


This is out of scope for the current PR, but seeing this made me think that each 'field type family' should live on a single sub-page. We could have a short description of the family at the top, and then a subsection for each type. This would help users directly compare the different options, and could make wildcard more discoverable.

@jrodewig @markharwood what would you think about this idea as a potential follow-up?

👍 I like this idea. I've created #61441 to track.

docs/reference/mapping/types.asciidoc

jtibshirani

This looks good to me. I understand if you'd like to wait to merge to give others some time to weigh in though.

docs/reference/mapping/types.asciidoc

jtibshirani · 2020-08-21T21:12:38Z

docs/reference/mapping/types.asciidoc

+[[object-types]]
+==== Objects and relational types
+
+<<object,`object`>>::         A single JSON object.


I just noticed that the existing description of object + nested is quite confusing. Suggested update:

object: A JSON object.

nested: A JSON object that preserves the relationship between its subfields.

This is much clearer. Thanks for the suggestion.

jrodewig · 2020-08-21T22:20:53Z

Thank you so much for your reviews and the work on this reorg @jtibshirani. You did most of the heavy lifting!🙇

I'll leave this PR open for a few more days to get any additional feedback.

markharwood · 2020-08-24T09:32:38Z

I wonder if "quantifiers" might be a useful word to help describe the purpose of our numerics? A JSON long shouldn't be mapped as an elasticsearch long field if the data is something like a customer ID - that's better mapped as keyword. Our numeric indexing fields are optimised for range queries and range queries are used on:

weights
sizes
counts
money etc

... all quantities of something.
In a previous life/product we talked about quantitifiers vs identifiers to clearly distinguish the two use cases for numeric fields.

jrodewig · 2020-08-24T13:41:12Z

I wonder if "quantifiers" might be a useful word to help describe the purpose of our numerics?

I've added this to the Numbers description with e672593.

I think relabelling "Numbers" as "Quantifiers" entirely may simply obfuscate things rather than help users trying to map IDs. I think that topic has a bit more nuance than can probably be captured here (e.g., "Do you need to do math on these IDs?", "Do you need to search the IDs based on a range?", "Do you frequently sort or filter on this ID?", etc.).

markharwood · 2020-08-24T14:18:39Z

, "Do you need to do math on these IDs?",

Agreed, it's not always 100% clear-cut but generally range queries, sorting and math apply to amounts more than unique IDs. Exceptions might be IDs like order numbers that increment.

I've added this to the Numbers description with e672593.
Quantifiers and numeric types, such as long

That sounds a little like "quantifiers" and "numeric types" are two different things. How about

 "Numeric types such as long etc when used to express amounts (rather than IDs)."

jrodewig · 2020-08-24T14:25:32Z

Thanks for the suggestion @markharwood! I've added a slightly modified version to the docs.

jtibshirani · 2020-08-24T18:38:19Z

docs/reference/mapping/types.asciidoc

+Keyword::               The keyword family, including <<keyword, `keyword`>>,
+                        <<constant-keyword,`constant_keyword`>>, and
+                        <<wildcard, `wildcard`>>.
+<<number,Numbers>>::    Numeric types, such as `long` and `double`, used to


Sorry for nitpicking -- the 'amounts' part is really helpful, but the 'rather than IDs' part feels confusing, and as @markharwood mentioned there are actually some use cases for mapping ordered IDs as numbers. We could remove 'rather than IDs' (since we already have a warning/ tip about it in the numeric types docs)?

No problem. Removed with c4beb42. Thanks for raising.

jrodewig · 2020-08-26T17:18:39Z

@elasticmachine update branch

jrodewig · 2020-08-26T18:02:05Z

Went ahead and merged this in. Please feel free to reach out if you have any further iteration. Thanks!

[DOCS] Reorg field data types page

f894947

jrodewig mentioned this pull request Aug 14, 2020

Improve top-level docs on mapping field types. #57548

Closed

jrodewig requested review from jtibshirani and markharwood August 18, 2020 16:42

jrodewig marked this pull request as ready for review August 18, 2020 16:43

jrodewig added :Search Foundations/Mapping Index mappings, including merging and defining field types >docs General docs changes v7.10.0 v7.9.1 v8.0.0 labels Aug 18, 2020

elasticmachine added Team:Search Meta label for search team Team:Docs Meta label for docs team labels Aug 18, 2020

jtibshirani reviewed Aug 19, 2020

View reviewed changes

jrodewig added 3 commits August 19, 2020 17:36

Apply feedback from review

f5bf87a

Minor reword + grammar fixes

c82f611

Incorporate feedback

e28b87c

jrodewig requested a review from giladgal August 20, 2020 23:15

jtibshirani reviewed Aug 21, 2020

View reviewed changes

docs/reference/mapping/types.asciidoc Outdated Show resolved Hide resolved

docs/reference/mapping/types.asciidoc Outdated Show resolved Hide resolved

jrodewig added 2 commits August 21, 2020 16:35

address feedback

4ee6371

Reword

2293dad

jtibshirani approved these changes Aug 21, 2020

View reviewed changes

iter

8cbd2db

Add quantifiers to numbers desc

e672593

jrodewig added 3 commits August 24, 2020 10:23

Update number desc

e50bcd5

Add missing comma

85816ba

reword

0d8c12f

jtibshirani reviewed Aug 24, 2020

View reviewed changes

Reword Numbers desc

c4beb42

Merge branch 'master' into docs__reorg-mapping-types

2357915

jrodewig merged commit 49350dd into elastic:master Aug 26, 2020

jrodewig deleted the docs__reorg-mapping-types branch August 26, 2020 18:02

This was referenced Aug 26, 2020

[7.x] [DOCS] Reorg field data types page (#61117) #61599

Merged

[7.9] [DOCS] Reorg field data types page (#61117) #61600

Merged

jrodewig added a commit that referenced this pull request Aug 26, 2020

[DOCS] Reorg field data types page (#61117) (#61599)

462754e

jrodewig added a commit that referenced this pull request Aug 26, 2020

[DOCS] Reorg field data types page (#61117) (#61600)

a092e63

jakelandis added v8.0.0-alpha1 and removed v8.0.0 labels Jul 26, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Reorg field data types page #61117

[DOCS] Reorg field data types page #61117

jrodewig commented Aug 13, 2020 •

edited

Loading

elasticmachine commented Aug 18, 2020

elasticmachine commented Aug 18, 2020

jtibshirani left a comment

jtibshirani Aug 19, 2020

jrodewig Aug 19, 2020

jrodewig commented Aug 20, 2020

jtibshirani Aug 21, 2020

jrodewig Aug 21, 2020

jtibshirani left a comment

jtibshirani Aug 21, 2020

jrodewig Aug 21, 2020

jrodewig commented Aug 21, 2020 •

edited

Loading

markharwood commented Aug 24, 2020 •

edited

Loading

jrodewig commented Aug 24, 2020

markharwood commented Aug 24, 2020

jrodewig commented Aug 24, 2020

jtibshirani Aug 24, 2020

jrodewig Aug 24, 2020

jrodewig commented Aug 26, 2020

jrodewig commented Aug 26, 2020

[DOCS] Reorg field data types page #61117

[DOCS] Reorg field data types page #61117

Conversation

jrodewig commented Aug 13, 2020 • edited Loading

Preview

elasticmachine commented Aug 18, 2020

elasticmachine commented Aug 18, 2020

jtibshirani left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jrodewig commented Aug 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jtibshirani left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jrodewig commented Aug 21, 2020 • edited Loading

markharwood commented Aug 24, 2020 • edited Loading

jrodewig commented Aug 24, 2020

markharwood commented Aug 24, 2020

jrodewig commented Aug 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jrodewig commented Aug 26, 2020

jrodewig commented Aug 26, 2020

jrodewig commented Aug 13, 2020 •

edited

Loading

jrodewig commented Aug 21, 2020 •

edited

Loading

markharwood commented Aug 24, 2020 •

edited

Loading