NoSQL comparison
Couchbase Server, MongoDB, and DataStax Enterprise scored
Leading vendors ranked on 24 criteria in 3 categories – architecture, administration, and development
Get it now
COUCHBASE IS THE NOSQL DATABASE FOR
BUSINESS-CRITICAL APPLICATIONS
Develop with agility. Perform at any scale. Manage with ease.
Free Download Get started
Couchbase architectural advantages
Develop with agility
Time to market is critical, separating the first mover from everyone else. Developing an application today without knowing all of its needs at the outset requires a database that provides flexibility in schema and access patterns. As a document database, Couchbase empowers developers to build responsive, flexible applications at scale.
- Flexible schema for continuous delivery
- Fully featured SQL for JSON database
- No hassle scale out
Flexible schema for continuous delivery
- Flexible JSON data model enables on-the-fly schema change for continuous delivery
Fully featured SQL for JSON database
- SQL extended to JSON for query and analytics, including support for JOINs
- Storage, retrieval, structured querying, full-text search, real-time analytics and triggers, in the cloud or on mobile and edge devices
No hassle scale out
- Application behavior unchanged on 1-node development laptop to multi-node production deployment
- No manual sharding, or re-sharding
Perform at any scale
Raw speed isn’t enough. The experience of the first user must be as seamless for the millionth and beyond. Gone are the days of weekend maintenance windows. You must be available all the time, anywhere around the globe. As a distributed scale-out database, Couchbase guarantees consistent performance all day, every day, for all users.
- Memory and network centric
- Always-on, edge-to-cloud
- Consistent performance at any scale
Memory and network centric
- Memory-first architecture with integrated document cache
- Network-centric architecture with a high-performance replication backbone allows new workloads to be easily added while maintaining performance at scale
Always-on, edge-to-cloud
- Architected as a scale-out distributed database across physical, virtualized, container, and public cloud environments
Consistent performance at scale
- Intelligent, direct application-to-node data access without additional routing and proxying
- Independent data and index partitioning to optimize mixed and varied workloads
- Multi-Dimensional Scaling enables workloads to be added quickly and scaled independently with no impact on the existing performance
Manage with ease
Distributed databases are hard. Couchbase makes it easy. A single platform integrates storage, access, transport, and enterprise-grade security on premises and across multiple clouds and mobile devices. Administration and maintenance is abstracted from the application behavior: scale out, in, or up; replicate around the globe; upgrade versions; and recover from failures with zero downtime or application changes.
- Global deployment with low write latency
- Consistent performance when adding microservices
- Full stack security
Global deployment with low write latency
- Active-active cross datacenter replication (XDCR) with flexible topologies and low latency
- Hybrid-cloud deployment and management with Docker containers and Kubernetes/OpenShift Operator
Consistent performance when adding microservices
- Auto-sharding, replication, and failover for easy scale out and high availability
- Autonomously maintain application availability 24x365 across upgrades, node failures, network failures, or even cloud provider failures
- All functionality available across physical, virtualized, public cloud, container, and managed services environments
Full stack security
- End-to-end encryption over the wire and at rest
- Role-based authentication, with support for LDAP, PAM, and X.509
- Data and administrative auditing
Get under the hood
Click the graphic to explore the Couchbase architecture
Memory First
Customers expect and demand fast, responsive applications. Many enterprises will add an in-memory caching product in front of their relational and NoSQL database to increase performance and throughput, and to ensure responsiveness. However, this adds operational and management complexity as well as additional cost.
Built on a memory-first architecture, Couchbase ensures that all operations occur in-memory and supports special memory-optimized data management options, including 100% memory resident indexes and data buckets. This optimizes data-access performance and throughput while also simplifying operational management and reducing costs. By achieving memory-speed data transfer between nodes in the cluster, Couchbase avoids traditional database disk I/O bottlenecks.
Expand
Couchbase leverages its memory-first architecture to transfer data between nodes in the cluster at the speed of memory, thus avoiding traditional database disk I/O bottlenecks.
Learn more:
Elastic Scalability
As part of the core database engine, Couchbase provides an elastic Multi-Dimensional Scaling (MDS) architecture that supports both scale-up and scale-out approaches.
MDS allows you to separate the different data processing workloads as distinct, independently scalable services. You can independently configure and scale (up or out) the data, index, query, Full Text Search, and Analytics Services based on your data management processing requirements and application workloads. This gives you both the scalability to deliver responsive customer applications and the flexibility to adapt to new and changing workloads and application requirements.
Expand
MDS is particularly well-suited for the cloud where compute, storage, and memory resources are typically allocated and expensed separately. MDS allows you to independently configure and scale your compute, storage, and memory resources for each service. This results in a more efficient allocation and use of resources, ultimately reducing your overall cost of operations in the cloud.
Includes:
Query
Build and evolve web, mobile, and IoT apps faster using Couchbase’s own query language, N1QL (“nickel”). N1QL combines the power and familiarity of SQL with the flexibility and agility of the JSON data model.
N1QL is a declarative query language that extends SQL for JSON data. You can query data via native framework and language integrations, a fluent and easy-to-use API, several Couchbase utilities, or available JDBC/ODBC drivers.
With N1QL you can query JSON documents without any limitations: sort, filter, transform, group, and combine data with a single query. You can combine data from multiple documents with a JOIN. And you’re not limited to the “single table” and “table per query” data models often found in other NoSQL products.
Expand
In the Couchbase Mobile 2.0 release, N1QL has also been added to Couchbase Lite. This allows mobile application developers to leverage their existing SQL programming skills along with the flexibility of JSON.
Read the Couchbase under the hood white paperAnalytics
Powerful parallel query processing over JSON data allows you to:
- Efficiently execute complex, long-running SQL-like queries that contain complex joins and set, aggregation, and grouping operations
- Address the challenges of supporting responsive, scalable apps and ad hoc analytics on the same dataset
Couchbase Analytics powerfully combines a common JSON data model with:
- A SQL-like query language extended for JSON
- Effective analytical workload isolation
- Up-to-date data freshness via a fast memory-to-memory transfer protocol in a single platform
This allows app developers and DevOps to build intelligent applications and dashboards that surface insights to customers and business users in real time without the overhead and latency of performing separate extract, transform, load (ETL) operations.
Expand
Learn more:
Full-Text Search
Built-in Full Text Search (FTS) makes it simple for developers to add intelligence to apps. Full-text indexes are automatically managed within the Couchbase cluster, avoiding the delay, overhead, and complexity of managing a separate full-text search product and infrastructure.
FTS enables you to create, manage, and query full-text indexes on JSON documents stored in a Couchbase bucket. It provides powerful capabilities for natural language queries, including:
- Stemming, which provides a language-aware manner of searching (e.g., users can type "beauties" and find results for "beauty")
- Scoring, which provides relevance ranking for results
- Fast multipurpose indexes where a single index can support a wide range of possible text searches
Expand
In the Couchbase Mobile 2.0 release, Full Text Search has also been added to Couchbase Lite. This allows mobile application developers to incorporate device-local FTS queries and intelligence into their mobile applications.
Read the Couchbase under the hood white paperMobile
Couchbase gives you a full-stack data platform for your mobile and IoT apps, including built-in real-time data synchronization, enterprise-level security, and data integration with your existing ecosystem.
Your mobile and IoT apps leverage the full power of Couchbase by using Couchbase Server, Couchbase Sync Gateway, and Couchbase Lite to enable secure online and offline data access, as well as automatic data synchronization from device to the backend.
Data integration APIs let you integrate with your existing systems of record, data warehouses, and other legacy systems via Sync Gateway or Couchbase Server.
Expand
Whether you have hundreds, thousands, or millions of devices, Couchbase Server and Sync Gateway are independently scalable in real time, enabling you to keep up with changing demands.
Read the Couchbase under the hood white paper
Get started
- Server
- Mobile
- Enterprise
- Community
Couchbase Server 6.0.2 Enterprise
Couchbase Server 6.0.2 Enterprise Edition is a full-featured NoSQL Database available free of charge for unlimited pre-production development and testing, with support from our Couchbase Forums. Built on the most powerful NoSQL technology, Couchbase Server gives you the flexibility to constantly reinvent the customer experience. Experience unmatched agility, flexibility, and unparalleled performance on the easiest platform to manage, all risk-free as you revolutionize and deploy your mission-critical applications. Note: Enterprise and Community editions are largely API compatible, so if you later decide you do not need enterprise-grade features and support, you can deploy on Community Edition.
Couchbase Server 6.0.2, released in June 2019, is the second maintenance release in the 6.0.x series for Couchbase Server. This release includes a few improvements in addition to bug fixes related to many components. It also adds support for the Red Hat Linux (RHEL) 8 platform.
Couchbase Server 6.0.0 Community
Couchbase Server 6.0 Community Edition is the open source version of our non-proprietary data platform. It is supported by the community on Couchbase Forums, and is best suited for non-enterprise developers or non-commercial development where basic availability, performance, tooling, and query is sufficient. The Community Edition is available free of charge for both development and production, but is not subjected to the same rigorous "test, fix, and verify" quality assurance cycle as the Enterprise Edition, and is generally released several months behind Enterprise Edition.
Read
// Get (Sync)
JsonDocument myAirline = bucket.get("airline_5209");
// Get (Async)
Observable<JsonDocument> myAirline = bucket.async().get("airline_5209"); // async using RxJava Observables!
Write
// Insert (Sync)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
JsonDocument stored = bucket.upsert(JsonDocument.create("walter", passenger));
// Insert (Async)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
Observable<JsonDocument> stored = bucket.async().upsert(JsonDocument.create("walter", passenger));
// Upsert (Sync)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
JsonDocument stored = bucket.upsert(JsonDocument.create("walter", passenger));
// Upsert (Async)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
Observable<JsonDocument> stored = bucket.upsert(JsonDocument.create("walter", passenger));
// Replace (Sync)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
JsonDocument replaced = bucket.replace(JsonDocument.create("walter", passenger));
// Replace (Async)
JsonObject passenger = JsonObject.empty()
.put("firstname", "Walter")
.put("lastname", "White");
Observable<JsonDocument> walter2 = bucket.async().replace(JsonDocument.create("walter", passenger));
Query
// Query (String)
Observable<AsyncN1qlQueryResult> theAirline = bucket
.query(N1qlQuery
.simple("SELECT name FROM `travel-sample` AS Airline WHERE id = 5209"));
// Query (fluent API)
Observable<AsyncN1qlQueryResult> theAirline = bucket
.async()
.query(N1qlQuery.simple(
select("name")
.from("travel-sample")
.as("Airline")
.where(x("id")
.eq(5209))));
Read
// Get Document
bucket.get("walter", function (err, resRead) {/* handle results */});
Write
// Insert
var key = "walter";
bucket.insert(key, {firstname: "Walter", lastname: "White"},function(err, res) {/* handle results */});
// Upsert
var key = "walter";
bucket.upsert(key, {firstname: "Walter", lastname: "White"},function(err, res) {/* handle results */});
// Replace
var key = "walter";
bucket.replace(key, {firstname: "Walter", lastname: "White"},function(err, res) {/* handle results */});
Query
// Query (String)
var N1qlQuery = couchbase.N1qlQuery;
var query = N1qlQuery.fromString("SELECT name FROM `travel-sample` AS Airline WHERE id = 5209");
bucket.query(query,function(err,result){/* handle results */});
Read
// Get
$res = $myBucket->get(‘document_name’);
Write
// Insert
$res = $myBucket->insert('document_name', array('some'=>'value'));
// Upsert
$res = $myBucket->upsert('document_name', array('some'=>'value'));
// Replace
$res = $myBucket->replace('document_name', array('some'=>'value'));
Query
// Query (String)
$myBucket->enableN1ql(array('http://1.1.1.1:8093/','http://1.1.1.2:8093/'));
$query = CouchbaseN1qlQuery::fromString('SELECT * FROM default');
Read
' Get (Sync)
var result = bucket.GetDocument("airline_5209");
Write
' Insert (Sync)
var passenger = new Document() {
Firstname = "Walter",
Lastname = "White"
};
bucket.Insert(passenger);
' Upsert (Sync)
var passenger = new Document() {
Firstname = "Walter",
Lastname = "White"
};
bucket.Upsert(passenger);
' Replace (Sync)
var passenger = new Document() {
Firstname = "Walter",
Lastname = "White"
};
bucket.Replace(doc);
Query
' Query (String)
var query = new QueryRequest("SELECT name FROM `travel-sample` AS Airline WHERE id = 5209");
' Query (using LINQ)
var airlinesQuerySyntax = (
from fromAirport in ClusterHelper.GetBucket(CouchbaseConfigHelper.Instance.Bucket).Queryable<Airport>()
where fromAirport.Airportname == @from
select new { fromAirport = fromAirport.Faa, geo = fromAirport.Geo })
.ToList() // need to execute the first part of the select before call to Union
.Union<dynamic>(
from toAirport in ClusterHelper.GetBucket(CouchbaseConfigHelper.Instance.Bucket).Queryable<Airport>()
where toAirport.Airportname == to
select new { toAirport = toAirport.Faa, geo = toAirport.Geo });
Read
# Get
rv = bucket.get('document_name')
Write
# Insert
rv = bucket.insert('document_name', {'some': 'value'})
# Upsert
rv = bucket.upsert('document_name', {'some': 'value'})
# Replace
rv = bkt.replace('document_name', {'some':'newvalue'}
Query
# Query (Simple)
for row in bkt.n1ql_query('SELECT * FROM default'):
# Query (Placeholders)
q = N1QLQuery('SELECT fname, lname, age FROM default WHERE age > $age', age=22)
for row in bkt.n1ql_query(q):
...
Read
// Get
cas, err := myBucket.Get("document_name", &myValue)
Write
// Insert
cas, err := myBucket.Insert("document_name", &myDoc, 0)
// Upsert
cas, err := myBucket.Upsert("document_name", &myDoc, 0)
// Replace
cas, err := myBucket.Replace("document_name", &testValue, 0, 0)
Query
// Query (String)
myQuery := gocb.NewN1qlQuery("SELECT * FROM default")
rows, err := myBucket.ExecuteN1qlQuery(myQuery)
- Enterprise
- Community
Couchbase Lite 2.5.x Enterprise
Couchbase Lite 2.5.2 Enterprise Edition extends Couchbase to the edge with a full-featured embedded database that supports key-value, query, full-text search, eventing, sync, and security – both online and offline. It is available free of charge for unlimited pre-production development and testing, with support from our Couchbase Forums. Experience the unmatched agility, flexibility, and unparalleled performance on the easiest full-stack platform to manage, from the cloud to the edge, all risk-free as you revolutionize and deploy your mission-critical mobile applications. Note: Enterprise and Community editions are largely API compatible, so if you later decide you do not need enterprise-grade features and support, you can deploy on Community Edition.
• Couchbase 2.5.2 for Android, Objective-C, Swift, and .NET platforms was released in July 2019 to address important bug fixes.
• Couchbase Lite 2.5.1 for Swift and Objective-C was released in May 2019 to address an important upgrade bug and supersedes version 2.5.0 released earlier. We recommend that all customers using Swift and Objective-C upgrade to the 2.5.1 release and deploy this important bug fix.
• Couchbase Lite 2.5.0 was released in April 2019. In addition to bug fixes, this release includes delta sync, enhanced logging, advanced replication eventing and filtering capabilities.
Couchbase Lite 2.5.x Community
Couchbase Lite 2.5.x Enterprise Edition extends Couchbase to the edge with a full-featured embedded database that supports key-value, query, full-text search, eventing, sync, and security – both online and offline. It is available free of charge for unlimited pre-production development and testing, with support from our Couchbase Forums. Experience the unmatched agility, flexibility, and unparalleled performance on the easiest full-stack platform to manage, from the cloud to the edge, all risk-free as you revolutionize and deploy your mission-critical mobile applications. Note: Enterprise and Community editions are largely API compatible, so if you later decide you do not need enterprise-grade features and support, you can deploy on Community Edition.
• Couchbase 2.5.2 for Android, Objective-C, Swift, and .NET platforms was released in July 2019 to address important bug fixes.
• Couchbase Lite 2.5.1 for Swift and Objective-C was released in May 2019 to address an important upgrade bug and supersedes version 2.5.0 released earlier. We recommend that all customers using Swift and Objective-C upgrade to the 2.5.1 release and deploy this important bug fix.
• Couchbase Lite 2.5.0 was released in April 2019. In addition to bug fixes, this release includes delta sync, enhanced logging, advanced replication eventing and filtering capabilities.
- Enterprise
- Community
Sync Gateway 2.5 Enterprise
Couchbase Sync Gateway 2.5 Enterprise Edition provides seamless data synchronization from any cloud to the edge using WebSocket-based replication with fine-grained access control, enterprise-grade security, and elastic scalability. It is available free of charge for unlimited pre-production development and testing, with support from our Couchbase Forums. Experience the unmatched agility, flexibility, and unparalleled performance on the easiest platform to manage, all risk-free as you revolutionize and deploy your mission-critical mobile applications. Note: Enterprise and Community editions are largely API compatible, so if you later decide you do not need enterprise-grade features and support, you can deploy on Community Edition.
Couchbase Sync Gateway 2.5 was released in April 2019. In addition to bug fixes, this release includes delta sync and enhanced stats collection and logging support.
Sync Gateway 2.5 Community
Couchbase Sync Gateway 2.5 Community Edition is the open source version of our non-proprietary sync technology. It is supported by the community on Couchbase Forums, and is best suited for non-enterprise mobile developers or non-commercial development where basic availability, performance, tooling, and query is sufficient. The Community Edition is available free of charge for both development and production, but is not subjected to the same rigorous "test, fix, and verify" quality assurance cycle as the Enterprise Edition, and is generally released several months behind Enterprise Edition.
Couchbase Sync Gateway 2.5 was released in April 2019. In addition to bug fixes, this release includes delta sync and enhanced stats collection and logging support.
OPEN DATABASE
// Get the database (and create it if it doesn’t exist).
let database = try Database(name: "my-database")
ADD DOCUMENT
let newTask = MutableDocument()
.setString("John", forKey: "firstName")
try database.saveDocument(newTask)
READ AND UPDATE DOCUMENT
guard let document = database.document(withID: "xyz") else { return }
let mutableDocument = document.toMutable()
mutableDocument.setString("jonny", forKey: "firstName")
try database.saveDocument(mutableDocument)
DELETE DOCUMENT
try database.deleteDocument(mutableDocument)
ENABLING SYNC
let url = URL(string: "ws://localhost:4984/db")!
var replConfig = ReplicatorConfiguration(withDatabase: database, targetURL: url)
replConfig.replicatorType = .pull
let replication = Replicator(withConfig: replConfig)
replication.start()
QUERY
let query = QueryBuilder
.select(SelectResult.all())
.from(DataSource.database(database))
.where(Expression.property("firstName").equalTo(Expression.string("jonny")))
.limit(10)
OPEN DATABASE
CBLDatabase *database = [[CBLDatabase alloc] initWithName:@"my-database" error:&error];
ADD DOCUMENT
CBLMutableDocument *newTask = [[CBLMutableDocument alloc] init];
[newTask setString:@"firstName" forKey:@"john"];
CBLDocument *saved = [database saveDocument:newTask error:&error];
READ/ UPDATE DOCUMENT
CBLDocument *document = [database documentWithID:@"xyz"];
CBLMutableDocument *mutableDocument = [document toMutable];
[mutableDocument setString:@"jonny" forKey:@"firstName"];
[database saveDocument:mutableDocument error:&error];
DELETE DOCUMENT
[database deleteDocument: doc error: &error];
ENABLING SYNC
NSURL *url = [NSURL URLWithString:@"ws://localhost:4984/db"];
CBLURLEndpoint *target = [[CBLURLEndpoint alloc] initWithURL: url];
CBLReplicatorConfiguration *config = [[CBLReplicatorConfiguration alloc] initWithDatabase:database target:target];
config.replicatorType = kCBLReplicatorTypePull;
CBLReplicator *replicator = [[CBLReplicator alloc] initWithConfig:config];
[replicator start];
QUERY
CBLQuery *query = [CBLQueryBuilder select:@[[CBLQuerySelectResult all]]
from:[CBLQueryDataSource database:database]
where:[[CBLQueryExpression property:@"firstName"]
equalTo:[CBLQueryExpression string:@"jonny"]]
groupBy:nil having:nil orderBy:nil
limit:[CBLQueryLimit limit:[CBLQueryExpression integer:10]]];
OPEN DATABASE
// Get the database (and create it if it doesn’t exist).
DatabaseConfiguration config = new DatabaseConfiguration(/* Android Context*/ context);
Database database = new Database("my-database", config);
CREATE DOCUMENT
MutableDocument newTask = new MutableDocument();
newTask.setString("firstName", "john");
database.save(newTask);
READ/ UPDATE DOCUMENT
Document document = database.getDocument("xyz");
MutableDocument mutableDocument = document.toMutable();
mutableDocument.setString("firstName", "jonny");
database.save(mutableDocument);
DELETE DOCUMENT
database.delete ( document);
ENABLING SYNC
URI uri = new URI("ws://localhost:4984/db");
Endpoint endpoint = new URLEndpoint(uri);
ReplicatorConfiguration config = new ReplicatorConfiguration(database, endpoint);
config.setReplicatorType(ReplicatorConfiguration.ReplicatorType.PULL);
Replicator replication = new Replicator(config);
replication.start();
QUERY
Query query = QueryBuilder
.select(SelectResult.expression(Meta.id),
SelectResult.property("name"),
SelectResult.property("type"))
.from(DataSource.database(database))
.where(Expression.property("firstName").equalTo(Expression.string("jonny")))
.orderBy(Ordering.expression(Meta.id));
OPEN DATABASE
// Get the database (and create it if it doesn’t exist).
var database = new Database("my-database");
CREATE DOCUMENT
var dict = new Dictionary {
["firstName"] = "john"
};
var newTask = new MutableDocument(dict);
database.Save(newTask);
READ/ UPDATE DOCUMENT
var newTask = database.GetDocument(“docId”).toMutable();
// We can directly access properties from the document object:
newTask.SetString("firstName", "jonny");
database.Save(newTask);
DELETE DOCUMENT
database.Delete(newTask);
ENABLE SYNC
var url = new Uri("ws://localhost:4984/db");
var replConfig = new ReplicatorConfiguration(database, url);
replConfig.ReplicatorType = ReplicatorType.Pull;
var replication = new Replicator(replConfig);
replication.Start();
QUERY
using(var query = QueryBuilder.Select(SelectResult.Property("name"))
.From(DataSource.Database(database))
.Where(Expression.Property("firstName").EqualTo(Expression.String("jonny")))
.Limit(10))
Couchbase Todo Training App: Step by Step
1. Couchbase Travel Sample Training App: A step-by-step walkthrough of all the various features of Couchbase Mobile using a sample travel application. Available for Swift, Java (Android), and C# (UWP, Xamarin).
2. Todo Sample App: A started to-do task list app for iOS, Android, and Windows.
3. A Query Playground for iOS: Playground for testing the Couchbase Mobile Query and Full-Text Search (FTS) capabilities.
Download Couchbase Mobile
Code Intro
Sample Projects
Start today!
Get started in a few easy steps and join the NoSQL movement today!
3 reasons customers are making the switch.
How Couchbase beats MongoDB™
Office Depot ensures seamless shopping by serving rich
product information from Couchbase at blazing speed.
$1.5B+
online commerce
Marriott relies on Couchbase to process billions of dollars
in reservations annually with 99.995% availability.
13M
documents
Comcast uses Couchbase and a Customer 360 solution to deliver
better visibility and support across its lines of business.
40+
million documents
61K
users
BD’s Briight offers patients an always-on personal
diabetes companion supported by Couchbase.
24/7
assisted
care
+100K
users
Powered by Couchbase, FICO’s fraud detection platform is No. 1
in the world and scores 65% of the world’s credit/debit cards.
<1ms
response times
24x365
application uptime
Discover common use case patterns
Customer 360
Aggregate data collected from different sources in one platform to build a single view of your customer or business.
Catalog and Inventory
Publish new product and inventory content in real time and scale to millions of products and requests per second to present the right data at the right time.
Field Service
Enable field employees with one platform to manage data from different sources, push that data to the edge, and ensure that data is available online and offline.
IoT Data Management
Manage, support, and drive real-time data insights at the edge with embedded and cloud databases, sync, and guaranteed data availability.
Get the only NoSQL database built for business-critical applications
How can we help you?
All fields must be filled out unless marked (optional)
