4.6. The IDBIndex interface

The [IDBIndex](#idbindex) interface represents an index handle.

[Exposed=(Window,Worker)]
interface IDBIndex {
  attribute DOMString name;
  [SameObject] readonly attribute IDBObjectStore objectStore;
  readonly attribute any keyPath;
  readonly attribute boolean multiEntry;
  readonly attribute boolean unique;
 
  [NewObject] IDBRequest get(any query);
  [NewObject] IDBRequest getKey(any query);
  [NewObject] IDBRequest getAll(optional any query,
                                optional [EnforceRange] unsigned long count);
  [NewObject] IDBRequest getAllKeys(optional any query,
                                    optional [EnforceRange] unsigned long count);
  [NewObject] IDBRequest count(optional any query);
 
  [NewObject] IDBRequest openCursor(optional any query,
                                    optional IDBCursorDirection direction = "next");
  [NewObject] IDBRequest openKeyCursor(optional any query,
                                       optional IDBCursorDirection direction = "next");
};

index . [name](#dom-idbindex-name)

Returns the name of the index.

index . [name](#dom-idbindex-name) = newName

Updates the name of the store to newName.

Throws an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if not called within an upgrade transaction.

index . [objectStore](#dom-idbindex-objectstore)

Returns the [IDBObjectStore](#idbobjectstore) the index belongs to.

index . keyPath

Returns the key path of the index.

index . multiEntry

Returns true if the index’s multiEntry flag is true.

index . unique

Returns true if the index’s unique flag is true.

The name attribute’s getter must return this‘s name.

Is this the same as the index‘s name? As long as the transaction has not finished, this is the same as the associated index‘s name. But once the transaction has finished, this attribute will not reflect changes made with a later upgrade transaction.

The [name](#dom-idbindex-name) attribute’s setter must run these steps:

1. Let name be the given value.

2. Let transaction be this‘s transaction.

3. Let index be this‘s index.

4. If transaction is not an upgrade transaction, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

6. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

7. If index’s name is equal to name, terminate these steps.

8. If an index named name already exists in index’s object store, throw a “[ConstraintError](https://heycam.github.io/webidl/#constrainterror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

9. Set index’s name to name.

10. Set this‘s name to name.

The objectStore attribute’s getter must return this‘s object store handle.

The keyPath attribute’s getter must return this‘s index‘s key path. The key path is converted as a [DOMString](https://heycam.github.io/webidl/#idl-DOMString) (if a string) or a sequence (if a list of strings), per [WEBIDL].

The returned value is not the same instance that was used when the index was created. However, if this attribute returns an object (specifically an Array), it returns the same object instance every time it is inspected. Changing the properties of the object has no effect on the index.

The multiEntry attribute’s getter must return this‘s index‘s multiEntry flag.

The unique attribute’s getter must return this‘s index‘s unique flag.

The following methods throw an “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if called when the transaction is not active.

request = index . [get](#dom-idbindex-get)(query)

Retrieves the value of the first record matching the given key or key range in query.

If successful, request’s [result](#dom-idbrequest-result) will be the value, or undefined if there was no matching record.

request = index . [getKey](#dom-idbindex-getkey)(query)

Retrieves the key of the first record matching the given key or key range in query.

If successful, request’s [result](#dom-idbrequest-result) will be the key, or undefined if there was no matching record.

request = index . [getAll](#dom-idbindex-getall)(query [, count])

Retrieves the values of the records matching the given key or key range in query (up to count if given).

If successful, request’s [result](#dom-idbrequest-result) will be an Array of the values.

request = index . [getAllKeys](#dom-idbindex-getallkeys)(query [, count])

Retrieves the keys of records matching the given key or key range in query (up to count if given).

If successful, request’s [result](#dom-idbrequest-result) will be an Array of the keys.

request = index . [count](#dom-idbindex-count)(query)

Retrieves the number of records matching the given key or key range in query.

If successful, request’s [result](#dom-idbrequest-result) will be the count.

The get(query) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query and null disallowed flag true. Rethrow any exceptions.

6. Return the result (an [IDBRequest](#idbrequest)) of running asynchronously execute a request with this as source and retrieve a referenced value from an index as operation, using the current Realm as targetRealm, index and range.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) identifying the record to be retrieved. If a range is specified, the method retrieves the first existing record in that range.

This method produces the same result if a record with the given key doesn’t exist as when a record exists, but has undefined as value. If you need to tell the two situations apart, you can use [openCursor()](#dom-idbindex-opencursor) with the same key. This will return a cursor with undefined as value if a record exists, or no cursor if no such record exists.

The getKey(query) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query and null disallowed flag true. Rethrow any exceptions.

6. Return the result (an [IDBRequest](#idbrequest)) of running asynchronously execute a request with this as source and retrieve a value from an index as operation, using index and range.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) identifying the record key to be retrieved. If a range is specified, the method retrieves the first existing key in that range.

The getAll(query, count) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query. Rethrow any exceptions.

6. Return the result (an [IDBRequest](#idbrequest)) of running asynchronously execute a request with this as source and retrieve multiple referenced values from an index as operation, using the current Realm as targetRealm, index, range, and count if given.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) identifying the records to be retrieved. If null or not given, an unbounded key range is used. If count is specified and there are more than count records in range, only the first count will be retrieved.

The getAllKeys(query, count) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query. Rethrow any exceptions.

6. Return the result (an [IDBRequest](#idbrequest)) of running asynchronously execute a request with this as source and retrieve multiple values from an index as operation, using index, range, and count if given.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) identifying the records keys to be retrieved. If null or not given, an unbounded key range is used. If count is specified and there are more than count keys in range, only the first count will be retrieved.

The count(query) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query. Rethrow any exceptions.

6. Return the result (an [IDBRequest](#idbrequest)) of running asynchronously execute a request with this as source and count the records in a range as operation, using index as source and range.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) identifying the records keys to be counted. If null or not given, an unbounded key range is used.

The following methods throw an “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if called when the transaction is not active.

request = index . [openCursor](#dom-idbindex-opencursor)([query [, direction = “next”]])

Opens a cursor over the records matching query, ordered by direction. If query is null, all records in index are matched.

If successful, request’s [result](#dom-idbrequest-result) will be an [IDBCursorWithValue](#idbcursorwithvalue), or null if there were no matching records.

request = index . [openKeyCursor](#dom-idbindex-openkeycursor)([query [, direction = “next”]])

Opens a cursor with key only flag set to true over the records matching query, ordered by direction. If query is null, all records in index are matched.

If successful, request’s [result](#dom-idbrequest-result) will be an [IDBCursor](#idbcursor), or null if there were no matching records.

The openCursor(query, direction) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query. Rethrow any exceptions.

6. Let cursor be a new cursor with its transaction set to transaction, undefined position, direction set to direction, got value flag set to false, undefined key and value, source set to index, range set to range, and key only flag set to false.

7. Let request be the result of running asynchronously execute a request with this as source and iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

8. Set cursor’s request to request.

9. Return request.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) to use as the cursor‘s range. If null or not given, an unbounded key range is used.

The openKeyCursor(query, direction) method, when invoked, must run these steps:

1. Let transaction be this‘s transaction.

2. Let index be this‘s index.

3. If index or index’s object store has been deleted, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Let range be the result of running convert a value to a key range with query. Rethrow any exceptions.

6. Let cursor be a new cursor with its transaction set to transaction, undefined position, direction set to direction, got value flag set to false, undefined key and value, source set to index, range set to range, and key only flag set to true.

7. Let request be the result of running asynchronously execute a request with this as source and iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

8. Set cursor’s request to request.

9. Return request.

The query parameter may be a key or key range (an [IDBKeyRange](#idbkeyrange)) to use as the cursor‘s range. If null or not given, an unbounded key range is used.