D365 Business Central : Persistent Blob

Lots of people have heard about TempBlob, but what about Persistent Blob? Persistent Blob is a table in System App that can be used to store Blob data between sessions.
The table consists only two fields: Primary Key (Big Integer) and Blob. The Primary Key is using AutoIncrement property.

table 4151 "Persistent Blob"
{
    Access = Internal;

    fields
    {
        field(1; "Primary Key"; BigInteger)
        {
            AutoIncrement = true;
            DataClassification = SystemMetadata;
        }
        field(2; Blob; BLOB)
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(Key1; "Primary Key")
        {
            Clustered = true;
        }
    }

    fieldgroups
    {
    }
}

It’s an Internal System Table, meaning that we can’t access the table directly. If we try to access the table directly, we get below error.

So how do we access it ? We can access it using the “Persistent Blob” Codeunit. The “Persistent Blob” Codeunit itself is using Interface, so if we want to check out the logic, we need to look at “Persistent Blob Impl.” Codeunit.

There are five procedures inside the codeunit:
– Create
– Exists
– Delete
– CopyFromInStream
– CopyToOutStream

Let’s take an example on how to use this codeunit by importing and exporting a file.

Importing a file to Persistent Blob
To import into Persistent Blob, we will need to use two procedures: Create and CopyFromInStream. Create will generate a new record inside Persistent Blob table with the next primary key. CopyFromInStream will copy blob from an InStream into Persistent Blob table.

Below is an example on how to import file to an InStream, then insert it into Persistent Blob table.

local procedure ImportPersistentBlob(var BlobKey: BigInteger; var FileName: Text)
var
    PersistentBlob: Codeunit "Persistent Blob";
    FileInstream: InStream;
begin
    if UploadIntoStream('Upload File', '', '', FileName, FileInstream) then begin
        BlobKey := PersistentBlob.Create();
        PersistentBlob.CopyFromInStream(BlobKey, FileInstream);
    end;
end;

We can then store the Key inside our table.

if ImportPersistentBlob(Rec."Blob Key", Rec."File Name") then
  DoSomething();

Exporting Persistent Blob to a file
To export from Persistent Blob, we will need to use TempBlob Codeunit. The reason is because we don’t have procedure CreateOutStream and CreateInStream inside the PersistentBlob codeunit itself.

local procedure ExportPersistentBlob(BlobKey: BigInteger; FileName: Text)
var
    PersistentBlob: Codeunit "Persistent Blob";
    TempBlob: Codeunit "Temp Blob";
    FileOutstream: OutStream;
    FileInstream: InStream;
begin
    if PersistentBlob.Exists(BlobKey) then begin
        TempBlob.CreateOutStream(FileOutstream);
        PersistentBlob.CopyToOutStream(BlobKey, FileOutstream);
        TempBlob.CreateInStream(FileInstream);

        DownloadFromStream(FileInstream, '', '', '', FileName);
    end else
        Error('Persistent Blob does not exist');
end;

Sample Code is available on GitHub.

Additional information from @ajkauffmann:

The purpose of the Persistent Blob module is to store blob values between sessions. For example between subsequent API requests. I don't recommend using it as a central storage for blob values because of potential locking issues.

— Arend-Jan Kauffmann (@ajkauffmann) January 26, 2023