4. API - 4.6. The IDBIndex interface - 《Indexed Database API 2.0》

4.6. The IDBIndex interface

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://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#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 set.

index . unique

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

The name attribute’s getter must return this index handle‘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:

Let name be the given value.
Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If transaction is not an upgrade transaction, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If index’s name is equal to name, terminate these steps.
If an index named name already exists in index’s object store, throw a “[ConstraintError](https://www.w3.org/TR/WebIDL-1/#constrainterror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Set index’s name to name.
Set this index handle‘s name to name.

🚧 The [name](#dom-idbindex-name) attribute’s setter is new in this edition. It is supported in Chrome 58, Firefox 51, and Safari 10.1. 🚧

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

The keyPath attribute’s getter must return this index handle‘s index‘s key path. The key path is converted as a [DOMString](https://www.w3.org/TR/WebIDL-1/#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 true if this index handle‘s index‘s multiEntry flag is set, and false otherwise.

The unique attribute’s getter must return true if this index handle‘s index‘s unique flag is set, and false otherwise.

The following methods throw an “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if called when the transaction is not active.

request = store . [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 = store . [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 = store . [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 = store . [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 = store . [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:

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query and null disallowed flag set. Rethrow any exceptions.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to 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 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:

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query and null disallowed flag set. Rethrow any exceptions.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to retrieve a value from an index as operation, using index and range.

The query parameter may be a key or 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:

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to 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 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 [getAll()](#dom-idbindex-getall) method is new in this edition. It is supported in Chrome 48, Firefox 44, and Safari 10.1. 🚧

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

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to retrieve multiple values from an index as operation, using index, range, and count if given.

The query parameter may be a key or 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 [getAllKeys()](#dom-idbindex-getallkeys) method is new in this edition. It is supported in Chrome 48, Firefox 44, and Safari 10.1. 🚧

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

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to count the records in a range as operation, with index as source and range.

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

request = store . [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 = store . [openKeyCursor](#dom-idbindex-openkeycursor)([query [, direction = “next”]])

Opens a cursor with key only flag set 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:

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Let cursor be a new cursor with transaction set to transaction, an undefined position, direction set to direction, got value flag unset, and undefined key and value. The source of cursor is index. The range of cursor is range.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

The query parameter may be a key or 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:

Let transaction be this index handle‘s transaction.
Let index be this index handle‘s index.
If index or index’s object store has been deleted, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Let cursor be a new cursor with transaction set to transaction, an undefined position, direction set to direction, got value flag unset, and undefined key and value. The source of cursor is index. The range of cursor is range. The key only flag of cursor is set.
Run the steps to asynchronously execute a request and return the [IDBRequest](#idbrequest) created by these steps. The steps are run with this index handle as source and the steps to iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

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