Set Index Lock Mode Operation
-
The lock mode controls the behavior of index modifications.
UseSetIndexesLockOperation
to modify the lock mode for a single index or multiple indexes. -
Indexes scope:
The lock mode can be set only for static-indexes, not for auto-indexes. -
Nodes scope:
The lock mode will be updated on all nodes in the database group. -
Setting the lock mode can also be done from the indexes list view in the Studio.
Locking an index is not a security measure, the index can be unlocked at any time. -
In this page:
Lock modes
-
Unlocked - when lock mode is set to
Unlock
:- Any change to the index definition will be applied.
- If the new index definition differs from the one stored on the server,
the index will be updated and the data will be re-indexed using the new index definition.
-
Locked (ignore) - when lock mode is set to
LockedIgnore
:- Index definition changes will Not be applied.
- Modifying the index definition will return successfully and no error will be raised,
however, no change will be made to the index definition on the server.
-
Locked (error) - when lock mode is set to
LockedError
:- Index definitions changes will Not be applied.
- An exception will be thrown upon trying to modify the index.
Sample usage flow
Consider the following scenario:
-
Your client application defines and deploys a static-index upon application startup.
-
After the application has started, you make a change to your index definition and re-indexing occurs.
However, if the index lock mode is 'Unlock', the next time your application will start,
it will reset the index definition back to the original version. -
Locking the index allows to make changes to the running index and prevents the application
from setting it back to the previous definition upon startup. See the following steps:
- Run your application
- Modify the index definition on the server (from Studio, or from another application),
and then set this index lock mode toLockedIgnore
. - A side-by-side replacement index is created on the server.
It will index your dataset according to the new definition. - At this point, if any instance of your original application is started,
the code that defines and deploys the index upon startup will have no effect
since the index is 'locked'. - Once the replacement index is done indexing, it will replace the original index.
Set lock mode - single index
// Define the set lock mode operation
// Pass index name & lock mode
var setLockModeOp = new SetIndexesLockOperation("Orders/Totals", IndexLockMode.LockedIgnore);
// Execute the operation by passing it to Maintenance.Send
// An exception will be thrown if index does not exist
store.Maintenance.Send(setLockModeOp);
// Lock mode is now set to 'LockedIgnore'
// Any modifications done now to the index will Not be applied, and will Not throw
// Define the set lock mode operation
// Pass index name & lock mode
var setLockModeOp = new SetIndexesLockOperation("Orders/Totals", IndexLockMode.LockedIgnore);
// Execute the operation by passing it to Maintenance.SendAsync
// An exception will be thrown if index does not exist
await store.Maintenance.SendAsync(setLockModeOp);
// Lock mode is now set to 'LockedIgnore'
// Any modifications done now to the index will Not be applied, and will Not throw
Set lock mode - multiple indexes
// Define the index list and the new lock mode:
var parameters = new SetIndexesLockOperation.Parameters {
IndexNames = new[] {"Orders/Totals", "Orders/ByCompany"},
Mode = IndexLockMode.LockedError
};
// Define the set lock mode operation, pass the parameters
var setLockModeOp = new SetIndexesLockOperation(parameters);
// Execute the operation by passing it to Maintenance.Send
// An exception will be thrown if any of the specified indexes do not exist
store.Maintenance.Send(setLockModeOp);
// Lock mode is now set to 'LockedError' on both indexes
// Any modifications done now to either index will throw
// Define the index list and the new lock mode:
var parameters = new SetIndexesLockOperation.Parameters {
IndexNames = new[] {"Orders/Totals", "Orders/ByCompany"},
Mode = IndexLockMode.LockedError
};
// Define the set lock mode operation, pass the parameters
var setLockModeOp = new SetIndexesLockOperation(parameters);
// Execute the operation by passing it to Maintenance.SendAsync
// An exception will be thrown if any of the specified indexes do not exist
await store.Maintenance.SendAsync(setLockModeOp);
// Lock mode is now set to 'LockedError' on both indexes
// Any modifications done now to either index will throw
Syntax
// Available overloads:
public SetIndexesLockOperation(string indexName, IndexLockMode mode);
public SetIndexesLockOperation(Parameters parameters);
Parameters | Type | Description |
---|---|---|
indexName | string | Index name for which to set lock mode |
mode | IndexLockMode |
Lock mode to set |
parameters | SetIndexesLockOperation.Parameters |
List of indexes + Lock mode to set. An exception is thrown if any of the specified indexes do not exist. |
public enum IndexLockMode
{
Unlock,
LockedIgnore,
LockedError
}
public class Parameters
{
public string[] IndexNames { get; set; }
public IndexLockMode Mode { get; set; }
}