Class SpriteDatabase

Executes a command on the target database. This method should only be used for non-transactional, non-idempotent statements such as CREATE, ALTER, or DROP.

CRUD operations must be part of a transaction; otherwise, changes will not persist. Use the SpriteTransaction.crud() method for this purpose.

If you need to execute idempotent commands, see SpriteDatabase.query().

Note

This package includes type definitions to help you issue commands with typed return values.

db.command<CreateDocumentType>(
  'sql',
  'CREATE DOCUMENT TYPE aType'
);
Copy

Throws

Error if the command cannot be executed.

See

SpriteDatabase.query()
SpriteDatabase.transaction()

Example

const db = new SpriteDatabase({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
  databaseName: 'aDatabase'
});

async function spriteCommandExample() {
  try {
    const result = await db.command<CreateDocumentType>(
      'sql',
      'CREATE DOCUMENT TYPE aType',
    );
    console.log(result);
    // [ { operation: 'create document type', typeName: 'aType' } ]
    return result;
  } catch (error) {
    // handle error conditions
    console.error(error);
  }
}

spriteCommandExample();
Copy

Create a new database on the server.

Throws

Error if the database could not be created.

Example

async function createDatabaseExample() {
  try {
    const exists = await db.exits();
    if (!exits) {
      const created = await db.create();
      console.log(created);
      // true
    }
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
}

createDatabaseExample();
Copy

Check to see if this database exists on the server (i.e. the database was created).

Throws

Error if the database does not exist.

Example

async function databaseExistsExample() {
  try {
    const exists = await db.exists();
    console.log(exists);
    // true
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
}

databaseExistsExample();
Copy

Returns information about query execution planning of a specific statement, without executing the statement itself.

Example

const db = new SpriteDatabase({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
  databaseName: 'aDatabase'
});

async function spriteExplainExample() {
  try {
    const explanation = await db.explain("SELECT FROM schema:types");
    console.log(explanation);
    // {
    //   executionPlan: {
    //     type: 'QueryExecutionPlan',
    //     javaType: 'com.arcadedb.query.sql.executor.SelectExecutionPlan',
    //     cost: -1,
    //     prettyPrint: '+ FETCH DATABASE METADATA TYPES',
    //     steps: [ [Object] ]
    //   },
    //   executionPlanAsString: '+ FETCH DATABASE METADATA TYPES'
    // }
    return explanation;
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
};

spriteExplainExample();
Copy

Return the current schema.

Example

async function getSchemaExample() {
  try {
    const schema = await db.getSchema();
    console.log(schema);
    // [...]
    return schema;
  } catch (error) {
    console.log(error);
    // handle error conditions
  }
}

getSchemaExample();
Copy

Creates and returns a new SpriteTransaction. Operations requiring the transaction should be executed using the crud() method on the returned object. The transaction can be committed using the commit() method, and rolled-back by invoking rollback().

See

SpriteTransaction

Example

const db = new SpriteDatabase({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
  databaseName: 'aSpriteDatabase'
});

type DocumentType = {
  aProperty: string
}

async function transactionExample() {
  try {
    await db.command<CreatDocumentType>(
      'sql',
      'CREATE document TYPE aType',
    );

    const trx = await db.newTransaction();
    await trx.crud<InsertDocument<DocumentType>(
      'sql',
      'INSERT INTO aType SET aProperty = :aProperty',
      { aProperty: 'aValue' }
    );
    await trx.commit();
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
};

transactionExample();
Copy

Executes a query against the target database. This method only executes idempotent statements (that cannot change the database), namely SELECT and MATCH.

The execution of non-idempotent commands will throw an IllegalArgumentException exception.

If you are trying to execute non-idempotent commands, see the SpriteDatabase.command method.

Note

This library includes type definitions to assist in writing queries with typed return values. For example: ArcadeDocument, ArcadeEdge, etc. You can use these like so:

const result = await db.query<ArcadeDocument<DocumentType>>(
 'sql',
 'SELECT * FROM aType WHERE aProperty == "aValue"'
);
Copy

See

SpriteDatabase.command()

Example

const db = new SpriteDatabase({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
  databaseName: 'aDatabase'
});

type DocumentType = {
  aProperty: string
}

async function spriteQueryExample() {
  try {
    const result = await db.query<ArcadeDocument<DocumentType>>(
      'sql',
      'SELECT * FROM DocumentType WHERE aProperty == "aValue"'
    );
    console.log(result);
    // [{
    //   '@rid': '#0:0',
    //   '@cat': 'd',
    //   '@type': 'DocumentType',
    //   aProperty: 'aValue'
    // }];
    return result
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
};

spriteQueryExample();
Copy

Set the credentials that the database client should use when interacting with the ArcadeDB server.

Throws

Error if the credentials could not be set.

Creates a new transaction and passes it as an argument to a callback which represents the transaction scope. The transaction is committed when the callback resolves. The transaction can be rolled back by invoking SpriteTransaction.rollback() within the callback.

See

SpriteDatabase.newTransaction()
SpriteTransaction.commit()

Example

const db = new SpriteDatabase({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
  databaseName: 'aSpriteDatabase'
});

type DocumentType = {
  aProperty: string
}

async function transactionExample() {
  try {
    await db.command<CreatDocumentType>(
      'sql',
      'CREATE document TYPE aType',
    );
    await db.transaction(async (trx) => {
      trx.crud<InsertDocument<DocumentType>(
        'sql',
        'INSERT INTO aType SET aProperty = :aProperty',
        { aProperty: 'aValue' }
      );
    });
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
};

transactionExample();
Copy