Conventions
-
Conventions in RavenDB are customizable settings that users can configure to tailor client behaviors according to their preferences.
-
In this page:
- How to set conventions
- Conventions:
customFetch
disableAtomicDocumentWritesInClusterWideTransaction
disableTopologyUpdates
findCollectionName
findJsType
findJsTypeName
firstBroadcastAttemptTimeout
identityPartsSeparator
loadBalanceBehavior
loadBalancerContextSeed
loadBalancerPerSessionContextSelector
maxHttpCacheSize
maxNumberOfRequestsPerSession
readBalanceBehavior
requestTimeout
secondBroadcastAttemptTimeout
sendApplicationIdentifier
shouldIgnoreEntityChanges
storeDatesInUtc
storeDatesWithTimezoneInfo
syncJsonParseLimit
throwIfQueryPageSizeIsNotSet
transformClassCollectionNameToDocumentIdPrefix
useCompression
useJsonlStreaming
useOptimisticConcurrency
waitForIndexesAfterSaveChangesTimeout
waitForNonStaleResultsTimeout
waitForReplicationAfterSaveChangesTimeout
How to set conventions
-
Access the conventions via the
conventions
property of theDocumentStore
object. -
The conventions set on a Document Store will apply to ALL sessions and operations associated with that store.
-
Customizing the conventions can only be set before calling
documentStore.initialize()
.
Trying to do so after calling initialize() will throw an exception.
const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB");
// Set conventions HERE, e.g.:
documentStore.conventions.maxNumberOfRequestsPerSession = 50;
documentStore.conventions.disableTopologyUpdates = true;
documentStore.initialize();
// * Here you can interact with the RavenDB store:
// open sessions, create or query for documents, perform operations, etc.
// * Conventions CANNOT be set here after calling initialize()
Conventions:
customFetch
-
Use the
customFetch
convention to override the default fetch method.
This method is useful to enable RavenDB Node.js client on CloudFlare Workers. -
DEFAULT: undefined
// Returns an object
get customFetch();
// Set an object bound to worker with type: mtls_certificate
set customFetch(customFetch);
disableAtomicDocumentWritesInClusterWideTransaction
-
EXPERT ONLY:
Use thedisableAtomicDocumentWritesInClusterWideTransaction
convention to disable automatic
atomic writes with cluster write transactions. -
When set to
true
, will only consider explicitly added compare exchange values to validate cluster wide transactions. -
DEFAULT:
false
// Returns a boolean value
get disableAtomicDocumentWritesInClusterWideTransaction();
// Set a boolean value
set disableAtomicDocumentWritesInClusterWideTransaction(
disableAtomicDocumentWritesInClusterWideTransaction
);
disableTopologyUpdates
-
When setting the
disableTopologyUpdates
convention totrue
,
no database topology updates will be sent from the server to the client (e.g. adding or removing a node). -
DEFAULT:
false
// Returns a boolean value
get disableTopologyUpdates();
// Set a boolean value
set disableTopologyUpdates(value);
findCollectionName
-
Use the
findCollectionName
convention to define a function that will customize the collection name
from given type. -
DEFAULT: The collection name will be the plural form of the type name.
// Returns a method
get findCollectionName();
// Set a method
set findCollectionName(value);
findJsType
-
Use the
findJsType
convention to define a function that finds the class of a document (if exists). -
The type is retrieved from the
Raven-Node-Type
property under the@metadata
key in the document. -
DEFAULT:
null
// Returns a method
get findJsType();
// Set a method
set findJsType(value);
findJsTypeName
-
Use the
findJsTypeName
convention to define a function that returns the class type name from a given type. -
The class name will be stored in the entity metadata.
-
DEFAULT:
null
// Returns a method
get findJsTypeName();
// Set a method
set findJsTypeName(value);
firstBroadcastAttemptTimeout
-
Use the
firstBroadcastAttemptTimeout
convention to set the timeout for the first broadcast attempt. -
In the first attempt, the request executor will send a single request to the selected node.
Learn about the "selected node" in: Client logic for choosing a node. -
A second attempt will be held upon failure.
-
DEFAULT:
5 seconds
// Returns a number
get firstBroadcastAttemptTimeout();
// Set a number
set firstBroadcastAttemptTimeout(firstBroadcastAttemptTimeout);
identityPartsSeparator
-
Use the
identityPartsSeparator
convention to set the default ID separator for automatically-generated document IDs. -
DEFAULT:
/
(forward slash) -
The value can be any
char
except|
(pipe). -
Changing the separator affects these ID generation strategies:
// Returns a string
get identityPartsSeparator();
// Set a string
set identityPartsSeparator(value);
loadBalanceBehavior
loadBalancerPerSessionContextSelector
loadBalancerContextSeed
-
Configure the load balance behavior by setting the following conventions:
loadBalanceBehavior
loadBalancerPerSessionContextSelector
loadBalancerContextSeed
-
Learn more in the dedicated Load balance behavior article.
maxHttpCacheSize
-
Use the
MaxHttpCacheSize
convention to set the maximum HTTP cache size.
This setting will affect all the databases accessed by the Document Store. -
DEFAULT:
128 MB
-
Disabling Caching:
- To disable caching globally, set
MaxHttpCacheSize
to zero. - To disable caching per session, see: Disable caching per session.
- To disable caching globally, set
-
Note: RavenDB also supports Aggressive Caching.
Learn more about that in article Setup aggressive caching.
// Returns a number
get maxHttpCacheSize();
// Set a number
set maxHttpCacheSize(value);
maxNumberOfRequestsPerSession
-
Use the
maxNumberOfRequestsPerSession
convention to set the maximum number of requests per session. -
DEFAULT:
30
// Returns a number
get maxNumberOfRequestsPerSession();
// Set a number
set maxNumberOfRequestsPerSession(value);
readBalanceBehavior
-
Configure the read request behavior by setting the
readBalanceBehavior
convention. -
Learn more in the dedicated Read balance behavior article.
requestTimeout
-
Use the
requestTimeout
convention to define the global request timeout value for allRequestExecutors
created per database. -
DEFAULT:
null
(the default HTTP client timout will be applied - 12h)
// Returns a number
get requestTimeout();
// Set a number
set requestTimeout(value);
secondBroadcastAttemptTimeout
-
Use the
secondBroadcastAttemptTimeout
convention to set the timeout for the second broadcast attempt. -
Upon failure of the first attempt the request executor will resend the command to all nodes simultaneously.
-
DEFAULT:
30 seconds
// Returns a number
get secondBroadcastAttemptTimeout();
// Set a number
set secondBroadcastAttemptTimeout(timeout);
sendApplicationIdentifier
-
Use the
sendApplicationIdentifier
convention totrue
to enable sending a unique application identifier to the RavenDB Server. -
Setting to true allows the server to issue performance hint notifications to the client, e.g. during robust topology update requests which could indicate a Client API misuse impacting the overall performance.
-
DEFAULT:
true
// Returns a boolean
get sendApplicationIdentifier();
// Set a boolean
set sendApplicationIdentifier(sendApplicationIdentifier)
shouldIgnoreEntityChanges
-
Set the
shouldIgnoreEntityChanges
convention to disable entity tracking for certain entities. -
Learn more in Customize tracking in conventions.
storeDatesInUtc
-
When setting the
storeDatesInUtc
convention totrue
,
DateTime values will be stored in the database in UTC format. -
DEFAULT:
false
// Returns a boolean
get storeDatesInUtc();
// Set a boolean
set storeDatesInUtc(value);
storeDatesWithTimezoneInfo
-
When setting the
storeDatesWithTimezoneInfo
totrue
,
DateTime values will be stored in the database with their time zone information included. -
DEFAULT:
false
// Returns a boolean
get storeDatesWithTimezoneInfo();
// Set a boolean
set storeDatesWithTimezoneInfo(value);
syncJsonParseLimit
-
Use the
syncJsonParseLimit
convention to define the maximum size for the sync parsing of the JSON data responses received from the server.
For data exceeding this size, the client switches to async parsing. -
DEFAULT:
2 * 1_024 * 1_024
// Returns a number
get syncJsonParseLimit();
// Set a number
set syncJsonParseLimit(value);
throwIfQueryPageSizeIsNotSet
-
When setting the
throwIfQueryPageSizeIsNotSet
convention totrue
,
an exception will be thrown if a query is performed without explicitly setting a page size. -
This can be useful during development to identify potential performance bottlenecks since there is no limitation on the number of results returned from the server.
-
DEFAULT:
false
// Returns a boolean
get throwIfQueryPageSizeIsNotSet();
// Set a boolean
set throwIfQueryPageSizeIsNotSet(value);
transformClassCollectionNameToDocumentIdPrefix
-
Use the
transformTypeCollectionNameToDocumentIdPrefix
convention to define a function that will
customize the document ID prefix from the the collection name. -
DEFAULT:
By default, the document id prefix is determined as follows:
Number of uppercase letters in collection name | Document ID prefix |
---|---|
<= 1 |
Use the collection name with all lowercase letters |
> 1 |
Use the collection name as is, preserving the original case |
// Returns a method
get transformClassCollectionNameToDocumentIdPrefix();
// Set a method
set transformClassCollectionNameToDocumentIdPrefix(value);
useCompression
-
Set the
useCompression
convention to true in order to accept the response in compressed format and the automatic decompression of the HTTP response content. -
A
Gzip
compression is always applied when sending content in an HTTP request. -
DEFAULT:
true
// Returns a boolean
get useCompression();
// Set a boolean
set useCompression(value);
useJsonlStreaming
-
Set the
useJsonlStreaming
convention totrue
when streaming query results as JSON Lines (JSONL) format. -
DEFAULT:
true
// Returns a boolean
get useJsonlStreaming();
// Set a boolean
set useJsonlStreaming(value);
useOptimisticConcurrency
-
When setting the
useOptimisticConcurrency
convention totrue
,
Optimistic Concurrency checks will be applied for all sessions opened from the Document Store. -
Learn more about Optimistic Concurrency and the various ways to enable it in article
how to enable optimistic concurrency. -
DEFAULT:
false
// Returns a boolean
get useOptimisticConcurrency();
// Set a boolean
set useOptimisticConcurrency(value);
waitForIndexesAfterSaveChangesTimeout
-
Use the
waitForIndexesAfterSaveChangesTimeout
convention to set the default timeout for thedocumentSession.advanced.waitForIndexesAfterSaveChanges
method. -
DEFAULT: 15 Seconds
// Returns a number
get waitForIndexesAfterSaveChangesTimeout();
// Set a number
set waitForIndexesAfterSaveChangesTimeout(value);
waitForNonStaleResultsTimeout
-
Use the
waitForNonStaleResultsTimeout
convention to set the default timeout used by the
waitForNonStaleResults
method when querying. -
DEFAULT: 15 Seconds
// Returns a number
get waitForNonStaleResultsTimeout();
// Set a number
set waitForNonStaleResultsTimeout(value);
waitForReplicationAfterSaveChangesTimeout
-
Use the
waitForReplicationAfterSaveChangesTimeout
convention to set the default timeout for the
documentSession.advanced.waitForReplicationAfterSaveChanges
method. -
DEFAULT: 15 Seconds
// Returns a number
get waitForReplicationAfterSaveChangesTimeout();
// Set a number
set waitForReplicationAfterSaveChangesTimeout(value);