Describe the bug

The following example is in the docs (well technically it's in a blog post but they currently serve as supplementary docs/examples):

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;

};

But it doesn't parse and throws an error, because the branch expressions of the IF statement have semicolons at the end.

The following parses fine:

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;

};

It also works if you leave the semicolons in and move RETURN to the branches:

DEFINE FUNCTION fn::get_person($first: string, $last: string, $birthday: string) {

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

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

};

Steps to reproduce

Attempt to parse the function definition from the docs:

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;

};

Expected behaviour

Examples from the docs should parse.

I'm unsure whether the expected behaviour is for IF statements' branches to work with semicolons or not, so either the docs need fixing or the behaviour needs fixing.

My guess is that this is intended behaviour, but maybe I've just spent too much time with Rust.

SurrealDB version

1.0.0-beta.9+20230402.5eafebd for macos on aarch64

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

Hi,

It would be great if there was an option to switch to a light color theme.

My eyes are pretty bad, and the dark background with low contrast between font color and background make it difficult for me to read the text of the website.

Subquery eg. doesn't mention how to refer to parent fields when using SELECT queries that have inline subqueries

Ref: Discussion

There are some anchors but not everywhere.
Also add anchor link to set anchor (to copy link).

I can work on this if you want.

Hi,
I've recently discovered this project and it's gotten me really excited!
While trying to use it, I've found myself often looking in the code to figure out how to perform certain operations, and I would like to both contribute and make the project more accessible by documenting what I've found in the official docs.

How can I start writing docs? Is there a convention to them? What are the most important missing docs?

Thanks!

Surrealdb has been added to Scoop, a command line installer for windows.

The instructions to install it with Scoop are very simple:

scoop install surrealdb 

The instructions should be added to this section of the official website.

To understand what's being presented, it would be nice to have a visual diagram of how the things look in the db.

Per https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts there are a number of methods missing documenation:

• sync https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts#L249
• ping https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts#L274
• live https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts#L371
• kill https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts#L385
• info https://github.com/surrealdb/surrealdb.js/blob/411cb95e707459f749d790bab509891a17119a6b/src/index.ts#L302

Would like to see information about these methods on:

• https://surrealdb.com/docs/integration/libraries/webassembly
• https://surrealdb.com/docs/integration/libraries/nodejs
• https://surrealdb.com/docs/integration/libraries/deno
• https://surrealdb.com/docs/integration/libraries/javascript

Being SurrealDB a database that is expected to be exposed for frontend apps, it seems that is necessary a section for authentication and authorization.

It should, at least, contain the following topics:

• Why you should secure your database access
• How to create an user to map authentication
• How to allow creating an user dynamically
• How to map authorization (permissions) over an user

the structure of the sql syntax documentation blocks on the website is not explained, which can be confusing. A brief explanation of this would make it easier to parse, possibly on rollover or a dropdown.
some of the most confusing ones:


https://surrealdb.com/docs/surrealql/statements

Description

On the Libraries page, there is Java library shown as available.
But the Integration – Libraries page says Java library is not available yet.

Which one is right?

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

The C# .NET driver for SurrealDB has reached a stable point in development.

• Most of the client sided issues except for JWT Authentication are sorted out.
• We have API documentation.
• Examples are available.
  I would love to make .NET support official.
  The aim of this issue is to determine required changes for becoming the official driver. And subsequently adding Surreal.Net as the driver for the dotnet framework in the www.surrealdb.com website.

https://surrealdb.com/docs/installation/upgrading/beta8-to-beta9

At point 3:
Instead of:
user@localhost % /path/to/binary/surreal export -c http://localhost:8000 -u root -p root mydata.surql
should be:
user@localhost % /path/to/binary/surreal export --conn http://localhost:8000 --ns ns --db db --user root --pass root mydata.surql

Point 4 is missing and should be replaced by 'Stop the SurrealDB instance'

Point 5 is the copy of point 3 but it should be 'Install SurrealDB 1.0.0-beta.9'

At point 7:
Instead of:
user@localhost % surreal import -c http://localhost:8000 -u root -p root mydata.surql
should be:
user@localhost % surreal import --conn http://localhost:8000 --ns ns --db db --user root --pass root mydata.surql

https://github.com/surrealdb/www.surrealdb.com/blob/main/app/templates/docs/surrealql/datamodel/numbers.hbs
https://surrealdb.com/docs/surrealql/datamodel/numbers

For Docs / SurrealQL / Data Model / Numbers, the sections Number Precision and Number Calculation are almost repeats of each other. Number Calculation doesn't have its own example.

There appears to be a major CSS problem! I just went to find the docs on running with Docker and I got hit with bare html! The issue persisted as I clicked links around the site. Somebody should look into this asap.

At the time of writing https://surrealdb.com/docs/surrealql/statements/define only shows the syntax and provides no examples. Please add examples of how the define statement can be used to accomplish different objectives.

Define is a VERY powerful feature and may deserve several sub-pages as well to deal with it's different features.
These sub-pages may include using DEFINE with:

• NAMESPACE
• DATABASE
• LOGIN
• TOKEN
• SCOPE
• TABLE
• EVENT
• FIELD
• INDEX
• 'LINKS` - per https://discord.com/channels/902568124350599239/1018618253695795261/1026900902877069353

These sub-pages may include specific use-case examples describing how one could accomplish common objectives.

The documentation page should provide some usage examples:

https://surrealdb.com/docs/surrealql/statements/remove

Describe the bug

In beta.8, function () { was acceptable syntax for js scripting functions, but it is now a parse error. Only function() { works.

Steps to reproduce

RETURN function () { return true }

Expected behaviour

RETURN function () { return true } should not cause a parse error.

SurrealDB version

1.0.0-beta.9+20230402.5eafebd for linux on x86_64

Contact Details

[email protected]

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

For the Beta 9 release section (https://surrealdb.com/releases#v1-0-0-beta-9) the content for "Support code blocks and advanced expressions" is a repeat of the "Add support for selecting ranges of records"'s section's content.

In the website footer there is a link called Status pointing to https://status.surrealdb.com/
On this page there is a button called Get in touch pointing to https://surrealdb.com/contact

THE PROBLEM: The Contact page returns 404 error. I also couldn't find the Contact link anywhere else on the website.
THE SOLLUTION: Replace the button link with something else or create the Contact page.

Code snippet to install libraries in react.js and vue.js are wrong on this route.

Same thing in main route: surrealdb.com

Should be:

npm install surrealdb.js

For some reason the Text Record IDs shows the same code as Numeric Record IDs at
https://surrealdb.com/docs/surrealql/datamodel/ids

Looks different in the file on the main branch, unless I'm looking on the wrong file or branch?
It states "CREATE company:surrealdb SET name = 'SurrealDB';"
app/templates/docs/surrealql/datamodel/ids.hbs

hello 👋
is it possible to have some insight/pointers about this : embedding surraldb in a rust app

If I success to do a small POC with this I could try to contribute an example here.

cheers,

Currently, the code block for installation in https://surrealdb.com/docs/start/installation looks something like this:

In interest of the first time users and for user experience, I feel it is better to remove the user@localhost prefix and either keep the command only or keep it with the % prefix. This will also make it easier to copy-paste directly without giving much thought to it.

I'm willing to take up the implementation and open a pull request if this Enhancement gets approved.

Hello there!

Needlessly to say, I've fallen in love with this project and I'm already using it in an app I'm building (secret for now).

I'd love to start translating the docs to Spanish if you agree. Have you got any plans to add i18n support to the website? If you do I will start translating right away!

The website has no search ability and taking into account the fact that the content will grow over time, I think it is necessary for such a feature.

Maybe something like Algolia or Elasticsearch will provides the best user experience.

Can we add an example of relating nested hierarchy to the docs?

This showcases the ability to resolve relationships dynamically based on another object's record

REMOVE TABLE car;
REMOVE TABLE engine;
REMOVE TABLE piston;

DEFINE TABLE car SCHEMALESS;
    DEFINE FIELD name ON TABLE car TYPE string;

DEFINE TABLE engine SCHEMALESS;
    DEFINE FIELD parent ON TABLE engine TYPE any;

DEFINE TABLE piston SCHEMALESS;
    DEFINE FIELD parent ON TABLE piston TYPE any;
    DEFINE FIELD grandparent ON TABLE piston TYPE any
        VALUE { $this.parent.parent };


CREATE car:ulid() CONTENT {
	label: 'I am a generic car',
};
CREATE engine:ulid() CONTENT {
	label: 'I am an engine in  the car',
    parent: (SELECT * from car LIMIT 1)[0]
};
CREATE piston:ulid() CONTENT {
	label: 'I am a piston',
    parent: (SELECT * from engine LIMIT 1)[0]
};

SELECT * from piston;

This will yield the following result, which lets the piston read the car through the engine without needing to dereference engine. Yes, I am aware that this can be redundant, but with complex filters applied it can be useful and not duplicating data.

[
    {
        "grandparent": {
            "id": "car:01H5ACKCSFYJJ5QN1KM4EKNMR5",
            "label": "I am a generic car"
        },
        "id": "piston:01H5ACKCSFXPAWAW932DERSCFG",
        "label": "I am a piston",
        "parent": {
            "id": "engine:01H5ACKCSFEWVAT38CAZB7K471",
            "label": "I am an engine in  the car",
            "parent": {
                "id": "car:01H5ACKCSFYJJ5QN1KM4EKNMR5",
                "label": "I am a generic car"
            }
        }
    }
]

I don't mind submitting a PR, but i'm not really sure where it fits in or what adjustments should be made

Create a repository for Vue.js so we can send pull requests.

The last two count should be sort

Per this change surrealdb/surrealdb#2215

A collection of typos:

Validation Functions
In the first is::alpha example (SELECT * FROM is::alpha("ABC123");) the output should be false

JS-based Client Libraries (both Deno and Node on the server-side and JavaScript on the client side)
In the code, in the // Perform a custom advanced query example, there is a missing $ before the tb identifier in the query string

Deno driver
In the code for the Surreal.Instance example, the Surreal module is imported cjs-style, not ESM-

Thanks for the hard work! Keep it up!

On this page: https://surrealdb.com/docs/surrealql/datamodel, the description for UUIDs, Objects and Arrays says Datetimes and durations can be used to store and manipulate dates and times instead of their proper descriptions.

Angular.js is Angular 1, and it's deprecated and abandoned by Google

Angular or Angular 2+ is the new framework still ongoing, and the image has no border

So it's better to update this page (url, text and the image) and keep in mind

https://surrealdb.com/docs/integration/libraries/angularjs

Description

Currently, there are many variables, such as $auth, $value, and others that appear throughout the documentation, but are not easily found in a single place. Moreover, there are variables that seem to exist, but are not documented anywhere, such as $session, nor a mechanism to view all parameters available to the current connection.

I believe it would be a great idea to place all available variables in their own dedicated documentation page, or perhaps within the already existing Params page.

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

On the website https://surrealdb.com/features#libraries, under Dart [future] it reads;

A real-time, fast SDK library for Golang with bi-directional communication over WebSockets.

I think the Golang is a typo and should be Dart instead, making it read as follows;

A real-time, fast SDK library for Dart with bi-directional communication over WebSockets.

At
Documentation > Introduction > Features
Architecture > Distributed (using SurrealKV)
SurrealKV <- this page is blank

Would love a info for SurrealKV if there is some.

Hi I couldn't find a RSS feed on the releases page https://surrealdb.com/releases can this be added?

Would be good to improve the open graph social media sharing previews

When sharing the geo functions page https://surrealdb.com/docs/surrealql/functions/geo

It just gave a general title for both title and description

What I expected was:

SurrealDB | Geo functions
These functions can be used when working with and analysing geospatial data.

https://www.freecodecamp.org/news/what-is-open-graph-and-how-can-i-use-it-for-my-website/

Describe the bug

The main website for this project uses a colour scheme that is not colourblind-friendly.

Steps to reproduce

1. Be colourblind
2. Go to site
3. Cry as you can't read the docs

Expected behaviour

1. Be colourblind
2. Go to site
3. Be able to read the text

SurrealDB version

N/A

Contact Details

No response

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

This section should cover the following topics:

• Namespaces, their purpose and why databases are in them
• Tokens. Use cases where you would need to use the token functionality and how they are solved. Links to the DEFINE TOKEN docs #55
• Scopes. Use cases (What they are used for). Links to the DEFINE SCOPES docs #55
• SurrealDB security model, authentication, account management, roles and permissions. #50
• Records and references
• Graphs and relations
• More?

These topics would be sub-pages under the concepts section.

Currently SurrealDB supports DISTINCT operations but there is no documentation for it on the SELECT section.

I recently saw a message posted on Discord where someone was struggling with a bug in SurrealDB that was being made manifest by a SELECT statement they wrote. The bug is not related to this issue, but what is related is that they weren't sure that they could make an alias using the AS keyword in a query, which they could do.

I noticed that AS is missing from the official documented syntax for the SELECT statement on the website. I think this should be fixed.

It would be nice to be able to search Surrealdb documentation via a search bar to make it easier to traverse and find relevant content.

When we open the home page we have linked it to google analytics to track our traffic but due to some issue, it's not getting connected.

I would love to fix this issue as I have worked with google analytics multiple times. Have setup this website on my local system. Please assign me this issue so can create a PR.

thanks!

Currently the libraries section look like this:

It would be nice if the header was clickable which took you to the GitHub repository for that specific library.

The example is wrong for the usage of scopes here as mentioned in the discord here.

The NS, DB and SC parameters should be in the body not the header as shown in the example

Documentation sidebar is not visible/accessible on mobile. Because of this I couldn't find any of the documentation that was not directly linked from the "Overview" page (e.g. "SurrealQL", "CLI tool", sections).

Hey all,

While searching the internet for "querying SurrealDB" I came across this broken documentation site as the first result: https://surrealdb.dev/docs/start/querying-surrealdb

The URL is surrealdb.dev instead of surrealdb.com. I'm not sure why this site exists but my assumption is that either it shouldn't be indexed by search engines at all or it should redirect to surrealdb.com

It can be confusing because the two sites look identical.

Considering the ability of SurrealDB to create schemafull tables, there is no extensive documentation to create them.

A section for schemafull tables should be present with, at least the following points:

• Why you should use Schemafull tables.
• Defining table and data models
• All available data model types
• Adding default values
• Adding assertions to values
• Setting permissions at column level