Documentation: Add documentation about embedded records vs graph relations

[nickchomey]

Description

One of the biggest challenges that I have had in getting started with SurrealDB is figuring out when and why you would embed records vs create graph relations. There should be an explicit document on this topic that explains the pros and cons of each.

In particular, it should be documented clearly that Embedded records have many significant downsides - to the extent that they really ought to be used with considerable caution.

Consider this example

INSERT INTO person [
   { id: "jaime", name: "Jaime", surname: "Morgan Hitchcock" },
   { id: "tobie", name: "Tobie", surname: "Morgan Hitchcock" },
];

INSERT INTO company {
    id: 'SurrealDB',
    name: 'SurrealDB',
    founded: "2021-09-10",
    founders: [person:tobie, person:jaime],
    tags: ['big data', 'database']
};

DELETE person:tobie;

SELECT * FROM company:SurrealDB;
SELECT * FROM company:SurrealDB FETCH founders;

It returns the following, which still has person:tobie even though that record was deleted. This seems like an immense downside to embedding records, as it would essentially accumulate unlimited cruft over time.

-------- Query 1 (199.999µs) --------

[
	{
		founded: '2021-09-10',
		founders: [
			person:tobie,
			person:jaime
		],
		id: company:SurrealDB,
		name: 'SurrealDB',
		tags: [
			'big data',
			'database'
		]
	}
]

-------- Query 2 (200µs) --------

[
	{
		founded: '2021-09-10',
		founders: [
			NONE,
			{
				id: person:jaime,
				name: 'Jaime',
				surname: 'Morgan Hitchcock'
			}
		],
		id: company:SurrealDB,
		name: 'SurrealDB',
		tags: [
			'big data',
			'database'
		]
	}
]

It has also been brought to my attention that it is generally ill-advised to essentially create unlimited array fields in a document/nosql database. For example, if company had an employees or sales or other such field that would grow very large.

It would be much more appropriate to use the graphing capabilities here.

I'm also curious what performance implications there are between Selecting embedded records vs graph relations.

This was all discussed starting with this comment in Discord

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