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.

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

[8.x] Document that index/enable: false SO mappings is an anti-pattern (#201969) #202244

Merged
merged 1 commit into from
Nov 29, 2024
Merged
Changes from all commits
Commits
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
50 changes: 50 additions & 0 deletions dev_docs/tutorials/saved_objects.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,56 @@ Do not use field mappings like you would use data types for the columns of a SQL
SQL index. Only specify field mappings for the fields you wish to search on or query. By specifying `dynamic: false`
in any level of your mappings, Elasticsearch will accept and store any other fields even if they are not specified in your mappings.

Never use `enabled: false` or `index: false` in your mappings. Elasticsearch does not support toggling these mapping options, so if
your plugin ever needs to query the data, you will not be able to do so. Since these fields cannot be queried, they would require
migrating to a new field and making associated code changes. Instead, use `dynamic: false` which provides the same flexibility while
maintaining the future ability to query fields if necessary.

Here's an example of what NOT to do:

```ts
export const dashboardVisualization: SavedObjectsType = {
name: 'dashboard_visualization',
...
mappings: {
properties: {
metadata: {
enabled: false, // ❌ Don't do this
properties: {
created_by: { type: 'keyword' }
}
},
description: {
index: false, // ❌ Don't do this
type: 'text'
}
}
}
};
```

Instead, use `dynamic: false` if you want to persist data which does not need to be queryable.
```ts
export const dashboardVisualization: SavedObjectsType = {
name: 'dashboard_visualization',
...
mappings: {
properties: {
dynamic: false, // ✅ Do this instead
metadata: {
// dynamic: false gets inherited from above
properties: {
// `created_by` can now be stored but won't be queryable
}
},
// `description` can now be stored but won't be queryable
}
}
};
```

This approach maintains flexibility while ensuring all fields remain queryable if needed in the future.

Since Elasticsearch has a default limit of 1000 fields per index, plugins should carefully consider the
fields they add to the mappings. Similarly, Saved Object types should never use `dynamic: true` as this can cause an arbitrary
amount of fields to be added to the .kibana index.
Expand Down