Possible documentation improvements

[andyzukunft]

Hey,

I am replacing my current Arango driver (ArangoDB.Client) with yours. I realized that some of the documentation could be improved.

Trying to execute queries always returned error 401 from the database. After some try and fail and checking your test code I figured out the following:

• Realm is .. I don't know. I must not specify this for my connection to work. At least not provide my db name here.
• The executions parameter of type ArangoHandle (e.g. CreateAsync("test"), UpdateAsync("test"), ...) references to the used database (-> "test")

Some other documentation questions:

• How to best handle large-ish queries (just thousands of documents, nothing larger) if I want to link those to data grids (e.g. with Blazorize) for dynamic filtering/sorting?
• Is LINQ recommended or should one use AQL?
• In general: can you provide options for the LINQ params? The only way to find what is supported seems to have a look at the code base documentation. And AsQueryable() is not realy self-explanatory IMHO especially on how to use it properly (when/where/why) vs. ToListAsync() (I guess ToList() processes all the data, AsQueryable does not, but how to use it properly as a return value?).
• What's the difference between WHERE() and FILTER() (maybe this is a LINQ specific question, I am using it from time to time but I am not an expert. If it is LINQ specific question than please don't invest time in an answer)?
• List options for the serializers and specify that System.Text.Json Pascal Case is the default (you write it somewhere, but it's not easy to see, found it here: https://github.com/coronabytes/dotnet-arangodb/blob/master/Core.Arango.Tests/Core/TestBase.cs
• Is it possible to specify a default database on the ArangoContext (didn't find anything to ConnectionString at the Arango documentation homepage)?
• Why document JsonIgnore and ArangoIgnore so prominently? Isn't ArangoIgnore a ... real special case - especially because it only works with Newtonsoft.Json?
• Supported data types? My previous driver didn't support DateTime (well or Arango, however you want to look at it). It would be good to now which data types can be used beforehand .
• Is there a way to specify how a enum value is serialized (as Int or String)?
• You say hot backup is only available for enterprise system. Any recommendations on how to backup / restore data in general? Possible to use Arango.Backup but taking DB offline beforehand?

Anyway that's everything I managed to collect on the top of my hat after using your library for roughly 3 hours. Thanks for your great work!

Regards,

Andy

[coronabytes]

Hi,

• Realm is only specified once in the connection string, which prepends "prod-" "dev-" for all databases used by the arango context
• the first parameter for most of the functions is the database name without realm
  • we typically have a master db and one foreach tenant
  • thus when listing all dbs in arango we have prod-master prod-1 prod-2 dev-master ...
  • I agree that it makes it more complicated if you only ever use a single db
• we use DevExtreme DataGrids and have an adapter for that and it just uses regulär "Skip + Take" -> LIMIT 10, 20
  • for really large datasets that you want to stream to the client 100k+ docs there is the Stream Query + Lazy option
• We use this driver in two comercial projects and none of them use LINQ
  • For really simple use case it should work
  • however forget it for advanced analysis querys were AQL really shines (Multiple Graph Traverels / Joins etc)
• For AsQueryable, what exactly to you need? what kind of parameters?
• No difference between where and filter - adapted from the Arango Client LINQ driver
  • it tries to make fluent linq look like AQL
  • and this is where I struggle: when its impossibe to do all of AQL in LINQ, does it even make sense to include these helpers
• Default is newtonsoft PascalCase - because at project start there was no system.json.text
  • PascalCase because we like the idea of having same caseing as C# model
  • for interop camelCase may be a more sensible default
• No default db possible
• this would force me to make ALL parameters optional which I find bad design in C#
• ArangoIgnore is a very special usecase indeed, but we needed it quite often in our projects
• No datatype magic happening in the driver - json serializer defaults
  • this means DateTime will always be a ISO Z string
  • however for performance reason I should add the option to convert to integer timestamp (planned)
• We convert all enums to string with the [JsonConverter(typeof(.JsonStringEnumMemberConverter))] attribute
  • to hell with performance - no one likes debugging INTs in queries
• For "free" backups take a look at https://github.com/coronabytes/dotnet-arangodb-extensions
  • It works but, I wouldn't trust it as the interface import/export ist not very consistent in ArangoDB

var migrationService = new ArangoMigrator(Arango);

await using var fs = File.Create("export.zip", 1024 * 1024);
await migrationService.ExportAsync("source-database", fs, ArangoMigrationScope.Data | ArangoMigrationScope.Structure);

Thanks for the feedback - I'll try to integrate this into the readme