Documentation: table type is not documented, type::table function could use more detail

[matthewjnield]

Description

The type::table function's API definition indicates that it has a return type of table (See screenshot below).

https://surrealdb.com/docs/surrealql/functions/database/type#typetable

I am trying to understand this type, but have been unable to locate any documentation for it. There is no entry for this type in the list of data types on the page that lists all other types (https://surrealdb.com/docs/surrealql/datamodel).

Additionally, the description of the type::table function says "The type::table function converts a value into a string.", which may be incorrect since the function does not return a string.

If there is a type called table, it seems to be outside of the family of typical data types that can exist inside of a table record, since a field cannot be defined with a type of table:

However, I can tell that the type::table function does indeed actually return something that is not a string but some other type, as its return values do not appear as strings in the response:

All that I can deduce from the function's behavior without more detailed documentation is that:

• The function seems to return what many programming languages call a "name" or "symbol", intended to refer to data that exists in the environment (such as a table), used for meta-programming.
• If the provided value is a record ID, the name/symbol returned will be the table component of the record ID. Otherwise it will be exactly the value that it was provided.

I think the SurrealDB documentation would benefit from:

• Having an explanation of what the table type is and how it can be used.
• Expansion of the type::table function's documentation and example usage, and correction of the return type in the description.

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