Documenting how to use ISession, DocumentManager and other database operations

[weirdyang]

Hi,

I'm starting a thread to document all the questions and problems I've faced regarding these topics.

[weirdyang]

Declare a property Id of type long on your model and it will be autopopulated with the document id
(note for version 1.6 and below use type int)
Sample:
https://github.com/weirdyang/Cms.Web/blob/develop/Cms.Module.Api/TestObject/TestEntity.cs
Dicussion:
#16448
Changelog (v1.7):

OrchardCore/src/docs/releases/1.7.0.md

Line 7 in f0b0d3b

The database identity columns' size is now configurable. This applies to both the `Id` column in all tables and the `DocumentId` column in all index tables.

To create the documents in a separate table, pass a collection parameter when saving and in startup ConfigureServices method add the collection to StoreCollectionOptions

services.Configure<StoreCollectionOptions>(o => o.Collections.Add(TestEntity.Collection));

[weirdyang]

when to use ISession vs IDocumentManager?

ISession is the low-level data access service where you essentially interact with SQL in the YesSql model. Whatever you want to do in the document DB, you can do it via ISession. And if you want to fetch documents via arbitrary queries (i.e. SELECT ... WHEREs) you have to do it via ISession.

IDocumentManager is a higher-level services that uses ISession and provides a simplified, as well as cached access layer to single documents of a given type. This is useful if for your feature you want to keep a single piece of JSON in the DB. E.g. Queries keeps all the Queries in a single document, because you'll never really have more than a handful of them, so having them in separate documents (i.e. DB rows) would hurt performance.

From @Piedone #16433

[weirdyang]

String methods not suppored when using LINQ with ISession:

• ToLower()
• Contains()

(there might be more, but these are the two I've experienced problems wtih)
Note: the string comparison already ignores case by default

Supported string methods:

sebastienros/yessql#576 (comment)
.StartsWith("") and .StartsWith('')
.EndsWith("") and .EndsWith('')
.Contains("") and .Contains('')
.Concat([""]) .Concat(""), .Concat("", ""), .Concat("", "", ""), and .Concat("","","","")
.Min(), .Max(), .Count(), .Average(), .Sum()
IsLike("")
IsNotLike("")
.NotContains("")
IsIn([])
IsNotIn([])

[Piedone]

This is great but would you consider an even better contribution to the docs?

[weirdyang]

sure but under which sections?

[Piedone]

E.g. a subpage under https://docs.orchardcore.net/en/latest/topics/data/. This is the "TBD YesSql", really.