Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[IM] Address index templates feedback #71353

Merged
merged 1 commit into from
Jul 10, 2020
Merged

[IM] Address index templates feedback #71353

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions ...ins/index_management/public/application/components/template_form/steps/step_logistics.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,20 +62,21 @@ function getFieldsMeta(esDocsBase: string) {
description: (
<FormattedMessage
id="xpack.idxMgmt.templateForm.stepLogistics.dataStreamDescription"
defaultMessage="Wheter indices that match the index patterns should automatically create a data stream. {docsLink}"
defaultMessage="Create a data stream instead of an index. {docsLink}"
Copy link
Contributor

Choose a reason for hiding this comment

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

How about:

Use the template for data streams and backing indices only.

There are a couple of problems with the current text:

  • You're not creating a data stream. You're creating a template that is then used to create a data stream.
  • A single template can be used to create multiple data streams.

I don't think instead of an index is accurate either. The template is used to create the data stream and its backing indices.

Copy link
Contributor

Choose a reason for hiding this comment

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

These are really good points! A couple things bother me and I wonder what you think of them.

One thing is the wording of “Use the template...” The way this is phrased, it sounds like the UI is telling the user to use the template to create data streams. I think this sounds like the UI is identifying some sort of restriction to this template. It leads me to wonder, “OK I have to use it to create data streams — how do I do that?” Is there a way to rephrased this to describe the template’s behavior? This is what I was trying to do (poorly and without much thought) with the “Create...” phrasing. Can we improve on that without losing the behavior aspect?

The other thing that niggles in the back of my head is the mention of backing indices. I don’t think we should expose this implementation detail in such a high-level UI. I can see us exposing it in index management (and we do) but in this UI it just seems like an unhelpful distraction. Am I missing something? Do you think it’s helpful here? With my original copy I was trying to draw a clearer distinction between the default index-oriented behavior and the new data stream behavior. Do you think that’s helpful to the user and if so, is there a way we can reword it to emphasize that distinction?

Copy link
Contributor

@jrodewig jrodewig Jul 13, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks @cjcenizal. Good points!

Would something like this work?

The template creates data streams only.

OR

The template is only used to create data streams. (passive voice)

OR

The template is only used for data streams. (passive voice)

That should clear up confusion re: imperative voice. And you're likely right re: backing indices. If users are interested in more, they can read up on it using the docs link. Thanks for iterating on this!

Copy link
Contributor

Choose a reason for hiding this comment

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

I think these sound good, @jrodewig! Is there room for confusion with the word "only"? Is it clear what this implies? Or can we be explicit by contrasting this against the alternative behavior, e.g. "The template creates data streams instead of..."?

Copy link
Contributor

Choose a reason for hiding this comment

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

The template creates data streams instead of an index. works for me @cjcenizal. Thanks again!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for working through this @cjcenizal and @jrodewig! I opened #71615 with the updated copy.

Copy link
Contributor

Choose a reason for hiding this comment

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

I personally think there is still some confusion.

An index template does not create indices. As per the docs:

An index template is a way to tell Elasticsearch how to configure an index when it is created. Templates are configured prior to index creation and then when an index is created either manually or through indexing a document, the template settings are used as a basis for creating the index.

So the template does not create the index but is used as a set of configuration that is ready to be applied on newly created indices.

I think the confusion comes from the fact that we ask a user to ingest to an index to be able to create a data stream instead of having a dedicated API. And here we try to explain that indirection.

Maybe I got it wrong but: isn't the composable index template configuration applied to the backing indices?

Copy link
Contributor

@jrodewig jrodewig Jul 14, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

An index template does not create indices.

That correct. An index template does not create indices or data streams. The template is used to
create indices/data streams by configuring them.

A matching index template is required to create a data stream. This template is used to configure the stream's backing indices.

However, as CJ pointed out, backing indices are an implementation detail we don't want to raise here. It's simpler for users to think of the template as a way to create a data stream. This also allows us to contrast data streams with regular indices.

I think the confusion comes from the fact that we ask a user to ingest to an index to be able to create a data stream instead of having a dedicated API. And here we try to explain that indirection.

Ingest isn't required to create a data stream, but that is the most common use case.

You can create an empty data stream using the create data stream API:
https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-data-stream.html

However, a matching index template is still required. Creating a data stream, even an empty one, also creates a backing index that's configured based on the template.

Maybe I got it wrong but: isn't the composable index template configuration applied to the backing indices?

That's correct. However, as CJ pointed out, backing indices are an implementation detail we don't want to raise at this level. If we abstract away backing indices, users can think of the template as something used to create data streams.

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 the explanation @jrodewig ! I didn't know about the PUT _data_stream/<name> API.

I will get my head around it, but I think as a consumer I would have preferred a dedicated API to ingest into (and manage) this new data source.

POST _data_stream/_doc
POST _data_stream/_bulk

And here in the UI we would have simply said: "Use this template for data streams.".

This would have simplified a lot my mental model. I realize that this would have implied a lot of duplicated APIs (e.g. PUT _data_stream/my-data-stream/_mapping). But being explicit sometimes helps.

values={{
docsLink: (
<>
<br />
<EuiLink href={`${esDocsBase}/data-streams.html`} target="_blank">
{i18n.translate(
'xpack.idxMgmt.templateForm.stepLogistics.dataStreamDocumentionLink',
{
defaultMessage: 'Learn more about data streams.',
}
)}
</EuiLink>
</>
<EuiLink
href={documentationService.getDataStreamsDocumentationLink()}
target="_blank"
external
>
{i18n.translate(
'xpack.idxMgmt.templateForm.stepLogistics.dataStreamDocumentionLink',
{
defaultMessage: 'Learn more about data streams.',
}
)}
</EuiLink>
),
}}
/>
Expand Down