6.1 File analysis

The database can learn what is in the files you upload, in the background after each upload, using the Image AI and File to text services (§34). Three database settings turn it on for every file property, all off by default:

Setting	What is sent	What you get
`EnableAiImageAnalysisByDefault`	Pictures, to Image AI	A title, a description, keywords, the focus point and the things in the picture
`EnableFileTextIndexingByDefault`	Documents, and pictures for OCR, to File to text	The text of the file, its title, author, language and pages
`EnableVideoAndAudioFileTextIndexingByDefault`	Recordings and videos, to File to text	A transcript, timed line by line, and the duration

They are under Settings › Search & AI › File analysis in the admin UI, or in LocalSettings (§12.1). A file property can decide for itself. BoolValue.Default follows the database setting:

[FileProperty(AiImageAnalysis = BoolValue.True)]          // always analysed, whatever the default
FileValue Photo { get; set; }

[FileProperty(FileTextIndexing = BoolValue.False)]        // never read, even with the default on
FileValue SignedContract { get; set; }

[FileProperty(VideoAndAudioFileTextIndexing = BoolValue.True)]
FileValue Recording { get; set; }

What happens. An upload or a file copy queues a background task (Settings › Tasks shows it). The task sends the file to the service, then writes the result into the file value: the text goes into TextExtract, and everything else goes into MetaJSON as typed meta. That write queues the node for text indexing again, so the words, the title, the description and the keywords make the node findable with WhereSearch (§21). For recordings, the search text has the timestamps removed.

Each file analysed is charged to the license. A file is analysed once. Two kinds of failure are treated differently:

The service refuses the file (a kind it does not read, or a file that is too large). This is recorded in the meta, and the file is not sent again.
The call fails (no credits, no answer). Nothing is recorded, and the file is tried again at the next text reindex.

Files uploaded before a switch was on are analysed when the text index is rebuilt: Storage › Maintenance › Rebuild text index in the admin UI, db.Datastore.ReIndexAllText(), or the reindex-text job (§36). The rebuild queues every stored file that is still missing an analysis.

Reading the meta. FileValue.GetMeta() returns the meta as a class that matches the kind of file:

Class	For	Adds
`FileValueMeta`	Every file (the base class)	`Title`, `Description`, `Keywords`, `Author`, `Language`, `TextExtraction`, `Technical`
`ImageFileMeta`	Pictures	`FocusPoint` (pixels from the top left), `Objects` (type, name, confidence, box), `AiAnalysis`, and the picture's own `CropMode` and `BackgroundColor` (A picture's own defaults)
`DocumentFileMeta`	Documents	`Pages`
`AudioFileMeta`, `VideoFileMeta`	Recordings and videos (both derive from `MediaFileMeta`)	`Duration`

var photo = db.Get<Product>(id).Photo;

if (photo.TryGetMeta<ImageFileMeta>(out var image)) {
    var focus = image.FocusPoint;        // null if the service found none
    var tags = image.Keywords ?? [];
    var faces = image.Objects?.Count(o => o.Type == ImageObjectType.Face) ?? 0;
}

var meta = photo.GetMeta();              // always a FileValueMeta, of the file's own kind
bool read = meta.TextExtraction?.Succeeded == true;
string text = photo.TextExtract;         // the file's text, or a timed transcript

TextExtraction and AiAnalysis record when the step ran, which provider ran it, and the Error if the service refused the file. Technical holds what the decoder reported when the file was stored: the image details, or the probe of a video. You can also write the meta yourself with SetMeta(meta) and then save the node.