See on GitHub

    Set Index Lock Mode Operation

    • The lock mode controls the behavior of index modifications.
      Use SetIndexesLockOperation 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 the Studio indexes list view.
      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:

      1. Run your application
      2. Modify the index definition on the server (from Studio, or from another application),
        and then set this index lock mode to LockedIgnore.
      3. A side-by-side replacement index is created on the server.
        It will index your dataset according to the new definition.
      4. 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'.
      5. 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; }
}

    related articlesRelated Articles

    Indexes

    Server

    Operations

    Home / Docs / Client Api / Operations / Maintenance / Indexes / Set Index Lock