Terms
This guide provides editorial guidelines for terms commonly used in OpenSearch documentation, including spelling, capitalization, hyphenation, and usage. For definitions of OpenSearch concepts, see Concepts.
A
abort
Avoid because it has unpleasant associations and is unnecessarily harsh sounding. Use stop, end, or cancel instead.
above
Use only for physical space or screen descriptions, for example, “the button above the bar pane.”
For orientation within a document, use previous, preceding, or earlier.
ad hoc
Avoid. Use one-time instead.
administrator, admin
Spell out when used as a noun (“contact your administrator”). You can use admin as an adjective (“admin credentials,” “admin privileges”) and in code font (for example, the admin user).
affect
Affect as a noun refers to emotion as expressed in face or body language. Affect as a verb means to influence. Do not confuse with effect.
AI
No need to define as artificial intelligence (AI).
AI/ML
On first mention, use artificial intelligence and machine learning (AI/ML).
allow
Use allow when the user must have security permissions in order to complete the task.
Avoid using allow to refer to making something possible for the user. Instead, rewrite to focus on what’s important from the user’s point of view.
allow list
Use to describe a list of items that are allowed (not blocked). Do not use as a verb. Do not use whitelist.
Amazon OpenSearch Serverless
Use Amazon OpenSearch Serverless on first appearance; OpenSearch Serverless is acceptable for subsequent appearances. Amazon OpenSearch Serverless is an on-demand serverless configuration for Amazon OpenSearch Service.
Amazon OpenSearch Service
Use Amazon OpenSearch Service on first appearance; OpenSearch Service is acceptable for subsequent appearances. Amazon OpenSearch Service is a managed service that makes it easy to deploy, operate, and scale OpenSearch clusters in the AWS Cloud. Amazon OpenSearch Service is the successor to Amazon Elasticsearch Service (Amazon ES) and supports OpenSearch and legacy Elasticsearch OSS (up to 7.10, the final open-source version of the software).
API, API operation
Use operation instead of action, method, or function. Three capitalization rules apply:
- API names: capitalize all words (“Field Capabilities API”).
- API operations by endpoint name: lowercase with code font (“
_field_capsAPI”). - API operations described generically: lowercase (“field capabilities operations” or “field capabilities API operations”).
For more information, see Formatting and organization.
app or application
Use app for mobile software, application for all other uses.
appear, display, and open
Messages and pop-up boxes appear. Windows, pages, and applications open. The verb display requires a definite object. For example: The system displays the error message.
as well as
Avoid. Replace with in addition to or and as appropriate.
auto scaling
Use lowercase scaling, auto scaling, and automatic scaling (but not autoscaling) as the preferred descriptive terms when generically describing auto scaling functionality.
Do not use hyphenated auto-scaling as a compound modifier. Instead, use scaling (for example, scaling policy), or scalable (for example, scalable target or scalable, load-balanced environment).
AWS Signature Version 4
Use on first appearance. On subsequent appearances, Signature Version 4 may be used. Only use SigV4 when space is limited.
B
backend (n., adj.)
Use backend as an adjective and a noun. Do not use back end or back-end. Do not make backend possessive except as part of a compound noun, such as backend system.
below
Use only for physical space or screen descriptions, such as “the outlet below the vent,” or “the button below the bar pane.”
For orientation within a document, use following or later.
Base64
Not base64, base-64, or Base-64.
big data
blacklist
Do not use. Use deny list instead.
blackout
Avoid using. Use service outage or blocked instead.
BM25
A ranking function used to estimate the relevance of documents to a given search query. BM25 extends TF–IDF by normalizing document length.
boost (v., n.), boosting (n., adj.)
Use boost as a verb (“boost the field’s relevance”) and as a noun for the parameter value (“apply a boost of 2.0”). Use boosting as a noun for the concept (“term boosting increases relevance”) and as an adjective for the query type (“boosting query”). Do not use boost as a noun to mean the general concept; use boosting instead.
Boolean
Avoid using the name of a Boolean value at the beginning of a sentence or sentence fragment. In general, capitalize the word Boolean. For specific programming languages, follow the usage in that language.
OpenSearch style:
- You can use the Boolean functions with Boolean expressions or integer expressions.
- IsTruncated(): A Boolean value that specifies whether the resolved target list is truncated.
bottom
Use only as a general screen reference, such as “scroll to the bottom of the page.” Don’t use for window, page, or pane references to features or controls. Rather, use lower instead. For example, you can use the following wording: “Choose the button on the lower left.”
browse
Use when referring to scanning information or browsing the web. Don’t use when describing how to navigate to a particular item on our site or a computer. Instead, use see or navigate to.
build (n., v.)
Use as a verb to refer to compiling and linking code. Use as a noun only to refer to a compiled version of a program (for example, Use the current build of Amazon Linux 2…) in a programming reference.
C
CA
certificate authority
certs, certificates
Use certificates on first mention. It’s OK to use certs thereafter.
checkbox, checkboxes
CI/CD
Use continuous integration and continuous delivery (CI/CD) or continuous integration and delivery (CI/CD) on first mention.
CLI
No need to define as command-line interface (CLI).
cluster manager
Do not capitalize. A single node that routes requests for the cluster and makes changes to other nodes. Each cluster contains a single cluster manager.
cluster-manager-eligible node
Hyphenate cluster-manager-eligible when used as a compound adjective before node. Do not use cluster manager eligible node.
coordinating node
Use coordinating node, not coordinator node. The coordinating node receives client requests, routes them to the appropriate shards, and aggregates the results.
command line, command-line
Two words as a noun. Hyphenate as an adjective.
Cross-Cluster Replication
A plugin that replicates indexes, mappings, and metadata from one OpenSearch cluster to another. Hyphenate Cross-Cluster. Do not use Cross Cluster Replication.
cut over (v.), cutover (n., adj.)
Use cut over as a verb (“cut over to the new cluster”). Use cutover as a noun or adjective (“perform the cutover,” “the cutover phase”). Do not hyphenate.
cyber
Except when dictated by open standards, use as a prefix in a closed compound: don’t use spaces or hyphens between cyber and the rest of the word.
D
dashboard, Dashboards, OpenSearch Dashboards
Use OpenSearch Dashboards (capitalized, full name) on all appearances when referring to the web UI application. Use Dashboards (capitalized) only as a short form for the Dashboards application within OpenSearch Dashboards (the tool for assembling visualizations into a single page). Use dashboard (lowercase) when referring to an individual page of visualizations created in that application. Do not use Dashboards as a standalone abbreviation for OpenSearch Dashboards.
data
Use data is, not data are. Don’t use datas. Use pieces of data or equivalent to describe individual items within a set of data.
data center
dataset
data source
data store, datastore
Two words when used generically, but one word when referring to the VMware product.
data type
dates
Use one of the following date formats:
- When a human-readable date format is preferred, spell out the date using the Month D, YYYY format (for example, October 1, 2022). Do not use an ordinal number for the day (use 1, not 1st). If the context is clear, you can omit the year on subsequent mention. If the specific day isn’t known, use the Month YYYY format (for example, October 2022).
- When a numeric, lexicographically sortable date is required, use the YYYY-MM-DD format (for example, 2022-10-01). Make sure to add a zero (0) in front of a single-digit month and day. This is the ISO 8601 standard date format. Make sure also that you use a hyphen (-) and avoid omitting the year. Doing so avoids the ambiguity that’s caused by the common, locally used formats of MM/DD and DD/MM.
deny list
Use to describe a list of items that aren’t allowed (blocked). Do not use blacklist.
Dev Tools console
A tool in OpenSearch Dashboards used to interact with the OpenSearch REST API. Use Dev Tools console on first appearance; console is acceptable for subsequent appearances. Do not capitalize console on its own.
disable
Use disable to describe making a feature or command unavailable. For example:
- Clear the checkbox to disable automatic monitoring.
- The feature is disabled by default.
Note that alternatives to disable—such as deactivate, turn off, or stop—are acceptable usage where appropriate and may be found in existing documentation. In all cases, use language that corresponds to the language used in the UI, if applicable.
Do not use disable to refer to users.
downvote
dropdown list
due to
Don’t use. Use because of instead.
E
easy, easier, easily
Avoid the use of easy, easier, or easily if possible when describing or comparing an OpenSearch Project product, feature, or procedure in technical content. Use of these terms is audience dependent. These terms are potentially misleading or inaccurate and might be perceived as condescending by some technical users. Instead, describe what the user can do.
On documentation landing pages, it’s acceptable to use easy, easier, or easily within the service description only.
effect
Effect as a noun refers to something that’s caused by something else. Effect as a verb means to bring about. Do not confuse with affect.
e.g.
Avoid. Use for example or such as instead.
Use as a singular noun or adjective to refer to the collective concept, and use message or mail for individual items. Use send email as the verb form. Don’t use the plural form because it’s a collective noun.
enable
Use enable to describe making a feature or command available. For example:
- Select the checkbox to enable automatic monitoring.
- The feature is enabled by default.
Note that alternatives to enable—such as activate, turn on, or start—are acceptable usage where appropriate and may be found in existing documentation. In all cases, use language that corresponds to the language used in the UI, if applicable.
Avoid using enable to refer to making something possible for the user. Instead, rewrite to focus on what’s important from the user’s point of view. For example, “With ABC, you can do XYZ” is a stronger statement than “ABC enables you to XYZ.” Additionally, using a task-based statement is usually more clear than the vague “…enables you to….”
embedding, embeddings
A numerical vector representation of data (text, images, or other content) used for similarity search. Use the plural embeddings when referring to multiple vectors. Do not use vector embedding redundantly unless distinguishing from other types of embeddings in a non-search context.
enter
In general, use in preference to type when a user adds text or other input (such as numbers or symbols).
etc., et cetera
Do not use.
Generally speaking, etc. and its equivalents (such as and more or and so on) aren’t necessary.
execute
Replace with a more specific verb. In the sense of carrying out an action, use run, process, or apply. In the sense of initiating an operation, use start, launch, or initiate.
Exception: Execution is unavoidable for third-party terms for which no alternative was determined, such as SQL execution plans. Executable is also unavoidable.
F
fail over (v.), failover (n.)
Faiss
Facebook AI Similarity Search. Do not define on first appearance. Faiss is a library that allows developers to quickly search for embeddings of multimedia documents that are similar to each other.
fine-tune (v.), fine-tuned (adj.), fine-tuning (n.)
Always hyphenated. Not finetune or fine tune.
file name
frontend (n., adj.)
Use frontend as an adjective and a noun. Do not use front end or front-end. Do not make frontend possessive except as part of a compound noun, such as frontend system.
G
generative AI
Do not use GenAI, Gen AI, gen AI, or genAI. To avoid the overuse of generative AI, AI/ML-powered applications may also be used.
geodistance
geohash
geohex
geopoint
geopolygon
geoshape
geospatial
geotile
H
hang
Do not use. This term is unnecessarily violent for technical documentation. Use stop responding instead.
hardcode
hard disk drive (HDD)
high availability (HA)
high performance computing (HPC)
hostname
Hugging Face
I
i.e.
Do not use. Use that is or specifically instead.
if, whether
Do not use if to mean whether. It is best to use whether in reference to a choice or alternatives (“we’re going whether it rains or not”) and if when establishing a condition (“we will go if it doesn’t rain”).
in, on
Use in Windows or in Linux in reference to components of the OS or work in the OS. Use on Windows in reference to Windows applications. Examples:
- Use the Devices and Printers Control Panel in Windows to install a new printer.
- In Windows, run the setup command.
- Select an application that runs on Windows.
Run applications and instances in the cloud, but extend services to the cloud.
Use on the forum. Whatever is on the internet (the various websites, etc.), you are on because you cannot be in it.
index, indexes
In technical documentation and the UI, use indexes as the plural form of index. Use indices only in the context of mathematical expressions. Variable and setting names should not be changed.
In blog posts, use the plural indexes unless there is a domain-specific reason (for example, a mathematical or financial context) to use indices.
Index Management (IM)
Index State Management (ISM)
ingest (v.), ingestion (n.)
Use ingest as a verb (“ingest data into OpenSearch”) and ingestion as a noun (“data ingestion”). Do not use ingest as a noun; use ingestion instead.
ingest node
Not ingestion node.
ingest pipeline
Not ingestion pipeline. The compound uses the verb form as a modifier.
inline
install (v.), installation (n.)
Use install only as a verb (“install the plugin”). For the noun, use installation (“complete the installation”). Do not use install as a noun.
Use in with folders, directories, or paths; use on with disks, drives, or instances.
internet
Do not capitalize.
invalid
Avoid using. Use not valid instead.
IP address
Always use the full term IP address; do not abbreviate to IP alone.
J
just
Use just in the sense of just now (as in “the resources that you just created”). Otherwise, use only in all other contexts (to mean “limited to; nothing more than”).
K
keystore
key-value
Not key/value.
kill
Avoid because it has unpleasant associations and is unnecessarily harsh sounding. Replace with stop, end, clear, remove, or cancel.
Exception: Use kill when referring to the UNIX kill command.
k-means
Lowercase k, hyphenated. Do not use K-means, k means, or K means.
k-NN
Short for k-nearest neighbors. No need to define. Do not use KNN, K-NN, or kNN.
L
launch
You start an application but launch an instance, environment, or cluster.
let
Avoid using let to refer to making something in a service or feature possible for the user. Instead, rewrite to focus on what’s important from the user’s point of view.
leverage
Replace with use.
lifecycle
One word in reference to software.
like (prep.)
OK to use to call out something for comparison.
As a general rule, if you can replace like with similar to, it’s OK to use like. But, if you can replace like with such as, use such as.
LLM
Define on first appearance as large language model (LLM).
locate in, on
Located in (a folder, directory, path), located on a disk drive or instance.
log in (v.), login (adj., n.)
Use log in as a verb (“log in to the instance”). Use login as a noun or adjective (“the login page”). Note: log in to, not log into.
log out (v.), logout (n., adj.)
Use log out as a verb (“log out of the session”). Use logout as a noun or adjective (“after logout”).
lower left, lower right
Hyphenate as adjectives. Use instead of bottom left and bottom right, unless the field name uses bottom. For example, “The lower-right corner.”
LTS
Long-Term Support
Lucene
Apache Lucene™ is a high-performance, full-featured search engine library written entirely in Java. OpenSearch uses a modified version of Lucene as the basis for search operations within OpenSearch.
M
machine learning
When machine learning is used multiple times in a document, use machine learning (ML) on first mention and ML thereafter. There is no need to redefine ML when AI/ML has already been defined. If spelled out, write machine learning as two words (no hyphen) in all cases, including when used as an adjective before a noun.
ML Commons
The plugin name is ML Commons—do not spell out as Machine Learning Commons. Use ML Commons plugin on first appearance (for example, “the ML Commons plugin provides a framework for ML features”).
master
Do not use. Use primary, main, or leader instead.
master node
Do not use. Use cluster manager node instead.
may
Avoid. Use can or might instead.
MS MARCO
Microsoft Machine Reading Comprehension. Do not define on first appearance. MS MARCO is a collection of datasets focused on deep learning in search.
multilayer, multilayered
multi-tenant, multi-tenancy
Always hyphenated. Not multitenant, multitenancy, or multi tenant.
must, shall, should
Must and shall refer to requirements. If the reader doesn’t follow the instruction, something won’t work right.
Should is used with recommendations. If the reader doesn’t follow the instruction, it might be harder or slower, but it’ll work.
N
navigate to
Not navigate in.
near real time (n.), near real-time (adj.) (NRT)
Use near real time as a noun; use near real-time as an adjective. Don’t add a hyphen between near and real time or real-time.
Spell out near real time on first mention; NRT can be used on subsequent mentions.
NMSLIB
Non-Metric Space Library. Do not define on first appearance. NMSLIB is an efficient similarity search library and a toolkit for evaluation of k-NN methods for generic non-metric spaces.
non-production
Hyphenate to make the term easier to scan and read.
O
onsite
OpenSearch
OpenSearch is a community-driven, open-source search and analytics suite derived from Apache 2.0 licensed Elasticsearch 7.10.2 and Kibana 7.10.2. It consists of a search engine daemon, OpenSearch, and a visualization and user interface, OpenSearch Dashboards.
OpenSearch Dashboards
The default visualization tool for data in OpenSearch. Use the full name OpenSearch Dashboards on all appearances. See also dashboard, Dashboards, OpenSearch Dashboards for disambiguation.
OpenSearch UI (Dashboards)
This is an Amazon OpenSearch Service term for the OpenSearch Dashboards interface within the managed service console. Use OpenSearch UI (Dashboards) on first appearance; on subsequent appearances, use OpenSearch UI. Do not use this term in open-source OpenSearch documentation—use OpenSearch Dashboards instead.
OpenSearch Data Prepper
Use OpenSearch Data Prepper on first appearance; Data Prepper is acceptable for subsequent appearances. OpenSearch Data Prepper is a server-side data collector capable of filtering, enriching, transforming, normalizing, and aggregating data for downstream analytics and visualization. Data Prepper also lets users build custom pipelines to improve the operational view of applications.
open source (n.), open-source (adj.)
Use open source as a noun (for example, “The code used throughout this tutorial is open source and can be freely modified”). Use open-source as an adjective (open-source software).
OpenSearch Playground
Do not precede with the. OpenSearch Playground provides a central location for users to explore and evaluate features in OpenSearch and OpenSearch Dashboards without downloading or installing any OpenSearch components locally.
operating system
When referencing operating systems in documentation, follow these guidelines:
- In general, if your docs or procedures apply to both Linux and macOS, you can also include Unix.
- Unix and UNIX aren’t the same. UNIX is a trademarked name that’s owned by The Open Group. In most cases, you should use Unix.
- When referring to the Mac operating system, use macOS. Don’t say Mac, Mac OS, or OS X.
- When referring to Windows, it’s not necessary to prefix with Microsoft.
- If you need to reference multiple Unix-like operating systems, you should separate by commas and use the following order: Linux, macOS, or Unix.
or earlier, or later
OK to use with software versions.
P
Painless
The default scripting language for OpenSearch, either used inline or stored for repeat use. Similar to Java’s language specification.
per
- Do not use to mean according to (for example, per the agreement).
- OK to use in meaning of to, in, for, or by each (one per account) where space is limited and in set terms and phrases, such as any of the following:
- queries per second (QPS)
- bits per second (bps)
- megabytes per second (MBps)
- Consider writing around per elsewhere. Per can sound stuffy and confusing to some global users.
percent
Spell out in blog posts (for example, 30 percent).
Use % in headlines, quotations, and tables or in technical copy.
pipeline
A sequence of processing stages that data passes through. OpenSearch uses this term in multiple contexts: an ingest pipeline processes documents before indexing, a search pipeline processes queries or results, and a Data Prepper pipeline moves data between sources and sinks. Use the qualified form (for example, ingest pipeline) to avoid ambiguity.
plaintext, plain text
Use plaintext only to refer to nonencrypted or decrypted text in content about encryption. Use plain text to refer to ASCII files.
please
Avoid using except in quoted text.
plugin
Capitalize the plugin name but not the word plugin (for example, Query Insights plugin, ML Commons plugin). Do not use the plugin name alone as a proper noun (for example, use the Anomaly Detection plugin, not Anomaly Detection). For more information about referencing plugins, see Plugins.
pop-up
preaggregate
precompute
premise, premises
With reference to property and buildings, always form as plural.
Correct: an on-premises solution
Incorrect: an on-premise solution, an on-prem solution
pretrain, pretrained, pretraining
Not pre-train, pre-trained, or pre-training.
purge
Use only in reference to specific programming methods. Otherwise, use delete, clear, or remove instead.
R
real time (n.) real-time (adj.)
Use with caution; this term can imply a degree of responsiveness or speed that may not be true. When needed, use real time as a noun (for example “The request is sent in real time”). Use real-time as an adjective (“A real-time feed is displayed…”).
repo
Use as a synonym for repository, on second and subsequent use.
retrieval-augmented generation (RAG)
rollover (n., adj.), roll over (v.)
Use rollover as a noun or adjective (“a rollover operation,” “the rollover index”). Use roll over as a verb (“roll over the index”). Do not hyphenate.
rollup (n., adj.), roll up (v.)
Use rollup as a noun or adjective (“an index rollup,” “rollup jobs”). Use roll up as a verb (“roll up your indexes”). Do not hyphenate.
RPM
No need to spell out. Use uppercase RPM when referring to the package format or manager. Use lowercase rpm in code font when referring to the command.
S
screenshot
segregate
Avoid using. Use separate or isolate instead.
setting
A key-value pair that creates a mapping in one of the many YAML configuration files used throughout OpenSearch. Sometimes alternatively called parameters, the programming language manipulating the key-value pair usually dictates the name of this mapping in a YAML file. For OpenSearch documentation (Java), they are properly a Setting object.
The following examples of settings illustrate key-value pairs with a colon separating the two elements:
Settings.index.number_of_shards: 4
plugins.security.audit.enable_rest: true
set up (v.), setup (n., adj.)
Use set up as a verb (“To set up a new user…”). Use setup as a noun or adjective (“To begin setup…”).
shut down (v.), shutdown (n., adj.)
Use shut down as a verb (“shut down the node”). Use shutdown as a noun or adjective (“a graceful shutdown”). Do not hyphenate.
simple, simply
Don’t use. Both simple and simply are not neutral in tone and might sound condescending to some users. If you mean only, use only instead.
slave
Do not use. Use replica, secondary, or standby instead.
Snapshot Management (SM)
solid-state drive (SSD)
standalone
start
You start an application but launch an instance, environment, or cluster.
startup (n.), start up (v.)
Never hyphenated. Use startup as a noun (for example, “The following startup procedure guides you through…”). Use start up as a verb (“You can start up the instances by…”).
syslog
T
term frequency–inverse document frequency (TF–IDF)
Use an en dash (–), not a hyphen (-). Not TF-IDF or tf-idf. A numerical statistic that reflects how important a word is to a document in a collection or corpus.
time out (verb), timeout (noun, adjective)
Never hyphenate. Use time out as a verb (“The request will time out if the server doesn’t respond”). Use timeout as a noun or adjective (“You can set the timeout interval by entering a number into…”).
time frame
time-series data
Always hyphenated. Not timeseries or time series. Data that’s provided as part of a metric. The time value is assumed to be when the value occurred.
timestamp
time zone
trade-off
trigger
Avoid using as a verb to refer to an action that precipitates a subsequent action. It is OK to use when referring to a feature name, such as a trigger function or time-triggered architecture. As a verb, use an alternative, such as initiate, invoke, launch, or start.
truststore
turn on, turn off
Use turn on and turn off in reference to a toggle to describe switching a setting or mode on or off.
Don’t use choose, select, clear, slide, enable, or disable for a toggle.
For making a feature available or unavailable, use enable.
U
upper left, upper right
Hyphenate as adjectives. Use instead of top left and top right, unless the field name uses top. For example, “The upper-right corner.”
upvote
US
No periods, as specified in the Chicago Manual of Style.
user
In most cases, replace with the more direct form you. Reserve user for cases where you are referring to a third party (not the audience you are writing for).
username
upsert
An operation that updates a document if it already exists or inserts a new document if it does not. Use as a noun (“an upsert operation”) or verb (“upsert the document”). One word, no hyphen.
V
version
Do not use version between the product name and the version number. Use OpenSearch 3.6, not OpenSearch version 3.6.
v., vs., versus
Do not use. Use compared to or compared with instead.
via
Do not use. Replace with by using, through, or with or a more specific phrase such as by accessing or by choosing.
W
warm up (v.), warmup (n., adj.)
Use warm up as a verb (“warm up the cache”). Use warmup as a noun or adjective (“the warmup phase,” “warmup settings”). Do not hyphenate.
web
webpage
Never web page.
website
Never web site.
while, although, whereas
Only use while to mean “during an interval of time.” Don’t use it to mean although because it is often ambiguous. Whereas is a better alternative to although in many cases, but it can sound overly formal.
whitelist
Do not use. Use allow list instead.
white space
wish, want, desire, need
Wish and desire are indirect and nuanced versions of want. Don’t use them. Be direct.
Do not confuse wants with needs. Use the term that’s appropriate to the situation. Need connotes a requirement or obligation, whereas want indicates that you have an intent but still a choice of valid actions.
Y
YUM
No need to spell out. Use uppercase YUM when referring to the tool name or repository (for example, “a local YUM repository”). Use lowercase yum in code font when referring to the command (for example, sudo yum install).
Z
ZIP Code
Use ZIP Code (capitalized) when referring to postal codes (ZIP is an acronym for Zone Improvement Plan).
zip file
Use zip file (lowercase) when referring to the compressed archive format. Use .zip in code font for the file extension.