Skip to content

Public vs. Private Records

A core concept on DorsalHub and when using Dorsal is the distinction between Public and Private file records. Understanding this is key to managing your data and controlling its visibility.

The most important takeaway is that a single file (identified by its SHA-256 hash) can have both a public record and one or more private records. A private record is always tied to a specific user.

Key Takeaway

  • A Public Record is a single, shared record for a file, visible to all users.
  • A Private Record is your personal record for that same file, visible only to you.
  • If you have a private record for a file, that's the one you will see by default if you retrieve the record by its hash.

Indexing and Quotas

The most practical difference between public and private records is how they are indexed and how they count against your account's quotas.

Private Records (The Default)

By default, DorsalHub is private. When you push a file, you create a private record that only you can see.

This action counts against your account's permanent, plan-based quota. For example, if your plan includes 1,000 private records, pushing a new file uses one of those slots.

# This creates a PRIVATE record by default
dorsal file push "C:\data\my_research.pdf"

from dorsal import LocalFile

lf = LocalFile("C:\data\my_research.pdf")

# Pushing without arguments creates a PRIVATE record
lf.push() 

# This is equivalent to setting `private` to `True`, as `True` is its default value
lf.push(private=True)

Public Records

To create a public record, you must explicitly add the --public flag.

This action counts against your daily action quota (e.g., "100 public indexes per day"). This quota resets and does not consume your permanent record slots.

DorsalHub is Private by Default

When you run dorsal file push, you are telling the server to create a private record about that file.

Private records are only visible to you.

To make a public record, you must add the --public argument to the command.

# The --public flag creates a PUBLIC record
dorsal file push "C:\data\shared_dataset.csv" --public

from dorsal import LocalFile

lf = LocalFile("C:\data\shared_dataset.csv")

# Setting private=False creates a PUBLIC record
lf.push(private=False)

Visibility and Precedence

Record visibility follows a simple rule: if you own a private record, you will always see it.

This is called "Owner Precedence." When you request a file record, DorsalHub checks:

  1. Do you have a private record for this file hash?
    • Yes: Your private record is returned.
  2. If not, does a public record exist for this hash?
    • Yes: The public record is returned.
  3. If not, the file is not found.

This means you can have a private record for a file that also has a public record. Other users will see the public record, but you will see your own.

Summary: Public vs. Private

Public Record Private Record
Who can see it? Everyone Only you
Indexing Quota Daily action quota Permanent user plan quota
How to Index (CLI) dorsal file push --public dorsal file push (default)
Precedence Low (Shown if no private record exists) High (Always shown to you if it exists)
Metadata View Shows Public Metadata + Your Private Metadata Shows Public Metadata + Your Private Metadata
Permission to Add Private Tags Yes Yes
Permission to Add Public Tags Only if you indexed it Only if you indexed it