Release 1.0

LET $value = "I am a string";

RETURN [
  type::is::string($value),
  type::is::record($value),
  type::is::number($value),
];

// Will return an object, as we can guarantee just a single record is requested
SELECT * FROM ONLY person:tobie;

// This will throw an error, as multiple records are being created and returned
CREATE ONLY person:tobie, person:jaime;

// You can initiate the live query in your application
LET $lq = LIVE SELECT * FROM person WHERE age > 18;
// And you can dispose the live query once it is no longer needed
KILL $lq;

// SurrealDB SDKs allow you to easily initiate live queries, and to process the received messages.
const lq = await db.live('person', function ({ action, result }) {
    if (action == 'CREATE') {
        renderPersonInFrontend(result);
    }
});

// Once you no longer need the live feed of updates, you can dispose the live query
await db.kill(lq);

// We can define an analyzer on our database,
// Then, define an index to dictate which content we want to index (yep, that easy)
DEFINE ANALYZER simple TOKENIZERS blank,class FILTERS snowball(english);
DEFINE INDEX content ON article FIELDS content SEARCH ANALYZER simple BM25 HIGHLIGHTS;

// We can then create some content
CREATE article SET content = "Join us at SurrealDB World, as we unveil our version 1.0.0 to the world!";
CREATE article SET content = "We will absolutely be at Surreal World!";

// And lastly, select some data from the article table.
// We use the special "@num@" operator, where we define a reference.
// We can then reference back in the search::* functions.
SELECT
  *,
  search::score(1) AS score,
  search::offsets(1) AS offsets,
  search::highlight('<b>', '</b>', 1) AS highlighted
FROM article WHERE
  content @1@ 'world'
ORDER BY score DESC;

# Allow all capabilities {#1-0-0-allow-all-capabilities}
user@localhost % surreal start --allow-all

# Allow all functions, except for custom functions {#1-0-0-allow-all-functions-except-for-custom-functions}
user@localhost % surreal start --allow-funcs --deny-funcs fn

# Allow all capabilities, but deny guest/anonymous access to the database {#1-0-0-allow-all-capabilities-but-deny-guestanonymous-access-to-the-database}
user@localhost % surreal start --allow-all --deny-guests

# When you initially start the database, you can create the first root user. {#1-0-0-when-you-initially-start-the-database-you-can-create-the-first-root-user}
user@localhost % surreal start --auth --user root --pass root file:database.db

# In the future, you don't need to specify the --user and --pass flags anymore {#1-0-0-in-the-future-you-dont-need-to-specify-the---user-and---pass-flags-anymore}
user@localhost % surreal start --auth file:database.db

// Afterwards, you are able to create multiple root users.
DEFINE USER tobie ON ROOT PASSWORD "SecurePassword!" ROLES OWNER;
DEFINE USER jaime ON ROOT PASSWORD "SecurePassword!" ROLES EDITOR;
DEFINE USER john  ON ROOT PASSWORD "SecurePassword!" ROLES VIEWER;

// Where you previously had to manually assert that a field does not contain NONE or NULL
DEFINE FIELD age ON person TYPE number ASSERT $value != NONE AND $value != NULL;

// You can now simply set the type and be ensured that only a number will be stored in that field.
DEFINE FIELD age ON person TYPE number;

// To make types optional, you can use the newly introduced "option<type>" type.
// This guarantees the field to be either empty (NONE), or a number.
DEFINE FIELD age ON person TYPE option<number>;

// We also introduces some new types!
DEFINE FIELD ratings     ON movie   TYPE array<number>;
DEFINE FIELD best_ratings   ON movie   TYPE array<number, 5>;
DEFINE FIELD unique_ratings ON movie   TYPE set<number, 5>;

// And we made sure that the record type is also in-line with this new format
DEFINE FIELD author     ON book   TYPE record<person>;

// Lastly, it is now possible to set a union type.
DEFINE FIELD title       ON article   TYPE string | number;
// They can also be used in "nested" types
DEFINE FIELD description   ON article   TYPE option<string | number>;
DEFINE FIELD author     ON article   TYPE record<person | admin>;

// You previously needed to involve logic with the "VALUE" clause to set a default value.
DEFINE FIELD enabled ON user TYPE bool VALUE $value OR $before OR true;
// You can now simply use the DEFAULT clause for this.
DEFINE FIELD enabled ON user TYPE bool DEFAULT true;

// As an added bonus, when you only define a VALUE clause with a simple value,
// then that will also act as the default value.
DEFINE FIELD constant ON demo VALUE 123;
// This will act the same as the following
DEFINE FIELD constant ON demo VALUE 123 DEFAULT 123;

DEFINE PARAM $perms_none VALUE 'Nobody can see me' PERMISSIONS NONE;
DEFINE PARAM $perms_full VALUE 'Everybody can see me' PERMISSIONS FULL;
DEFINE PARAM $perms_scope VALUE 'Only admins can see me' PERMISSIONS WHERE $scope = 'admin';

DEFINE FUNCTION fn::perms::none() {
  RETURN 'Nobody can invoke me';
} PERMISSIONS NONE;

DEFINE FUNCTION fn::perms::full() {
  RETURN 'Everybody can invoke me';
} PERMISSIONS FULL;

DEFINE FUNCTION fn::perms::scope() {
  RETURN 'Only admins can invoke me';
} PERMISSIONS WHERE $scope = 'admin';

// Here, we loop through an array with three numbers.
// For any number under two, we skip the iteration
// For any number above two, we break the loop
// The result is that only when the number is two, we will create the "person:two" record.

FOR $num IN [1, 2, 3] {
  IF $num < 2 {
    CONTINUE;
  };

  IF $num > 2 {
    BREAK;
  };

  CREATE person:two;
};

// Here, we select the id for every person in the database, and we gift them a ticket to SurrealDB World.
FOR $person IN (SELECT VALUE id FROM person) {
  CREATE gift CONTENT {
    recipient: $person,
    type: "ticket",
    event: "SurrealDB World"
  };
};

LET $message = "Some error message";
THROW "Failed to perform action: " + $message;

// Give extra context about a certain resource
DEFINE TABLE user COMMENT "This table will store users!";

// Previously
IF something = true THEN {
  RETURN 123;
} END;

// Now
IF something = true {
  RETURN 123;
};

function() {
  const page = await fetch('https://google.com');
  const people = await surrealdb.query('SELECT * FROM person');
  const auth = await surrealdb.value('auth');
  const uuid = surrealdb.functions.rand.uuid.v4();
}

// We want to define a SCHEMAFULL table
DEFINE TABLE person SCHEMAFULL;
// But we want one field to allow any content
DEFINE FIELD settings on person TYPE object FLEXIBLE;
// We can then set the field value without a schema
CREATE person:test CONTENT {
  settings: {
    nested: {
      object: {
        thing: 'test'
      }
    }
  }
};

DEFINE FIELD average_sales ON metrics VALUE {
  LET $sales = (SELECT VALUE quantity FROM sales);
  LET $total = math::sum($sales);
  LET $count = count($sales);
  RETURN ($total / $count);
};

-- Define a global function which can be used in any query
DEFINE FUNCTION fn::get_person($first: string, $last: string, $birthday: string) {

  LET $person = SELECT * FROM person WHERE [first, last, birthday] = [$first, $last, $birthday];

  RETURN IF $person[0].id THEN
    $person[0]
  ELSE
    CREATE person SET first = $first, last = $last, birthday = $birthday
  END;

};

-- Call the global custom function, receiving the returned result
LET $person = fn::get_person('Tobie', 'Morgan Hitchcock', '2022-09-21');