Records

file format 6
Rust SDK 1.0 preview

One record: parsing it from a JSON line, its kind and version, its identity, and typed views of entities and relations.

On this page, Result<T> is std::result::Result<T, plxi_sdk::Error>.

Every public struct and enum with a public field or variant is marked #[non_exhaustive]: code outside the crate builds one through its constructors and matches an enum with a _ arm.

Structs

struct

Record

Spec §4

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct Record { /* private fields */ }

impl FromStr for Record

Summary

One record: its kind, its per-kind version and its JSON line.

Identity (canonical_json, dedup_key, sort_key) is computed here, once, by the SDK.

Example

Example 7: Identity

Spec

Spec §4

method

Record::from_json_line

Spec §4.2

pub fn from_json_line(line: &str) -> Result<Record>

Summary

Parse one JSON line (spec §4).

The line is parsed and written out again, so json_line is the SDK's spelling of it (spec §4.3-§4.4), which can differ from the input bytes in the member order of typed records, in escapes and in number spelling.

Parameters

line: &str

Returns

Result<Record>

Errors

json for invalid JSON or a typed record that fails its schema; invalid_record for a value that is not an object or has no string k.

Example

Example 1: Write and read

Spec

Spec §4.2

method

Record::kind

Spec §4

pub fn kind(&self) -> &str

Summary: The record kind (k).
Parameters: None.
Returns: &str
Example: Example 7: Identity
Spec: Spec §4

method

Record::version

Spec §4

pub fn version(&self) -> u32

Summary: The per-kind format version (v; absent means 1).
Parameters: None.
Returns: u32
Example: Example 7: Identity
Spec: Spec §4

method

Record::json_line

Spec §4.3

pub fn json_line(&self) -> &str

Summary: The record's JSON line, as the SDK writes it.
Parameters: None.
Returns: &str
Example: Example 1: Write and read
Spec: Spec §4.3

method

Record::canonical_json

Spec §10.3

pub fn canonical_json(&self) -> String

Summary: The record's identity form (spec §10.3).
Parameters: None.
Returns: String
Example: Example 7: Identity
Spec: Spec §10.3

method

Record::primary_id

Spec §5.3

pub fn primary_id(&self) -> &str

Summary: The primary id (spec §5.3). For an opaque record without an id member and for outcome, the identity form of the object or of its outcome member, so the key is the same in every build.
Parameters: None.
Returns: &str
Example: Example 7: Identity
Spec: Spec §5.3

method

Record::dedup_key

Spec §5.3

pub fn dedup_key(&self) -> (String, String)

Summary: The dedup key (kind, primary id) (spec §5.3).
Parameters: None.
Returns: (String, String)
Example: Example 7: Identity
Spec: Spec §5.3

method

Record::sort_key

Spec §5.3

pub fn sort_key(&self) -> (u32, String, String)

Summary: The sort key (rank, kind, primary id) (spec §5.3): typed kinds rank by the §5.1 table, every other kind ranks last.
Parameters: None.
Returns: (u32, String, String)
Example: Example 7: Identity
Spec: Spec §5.3

method

Record::as_entity

Spec §5.1

pub fn as_entity(&self) -> Option<EntityView<'_>>

Summary: An entity view, when this is a typed ent record.
Parameters: None.
Returns: Option<EntityView<'_>>
Example: Example 3: Filter and views
Spec: Spec §5.1

method

Record::as_relation

Spec §5.1

pub fn as_relation(&self) -> Option<RelationView<'_>>

Summary: A relation view, when this is a typed rel record.
Parameters: None.
Returns: Option<RelationView<'_>>
Example: Example 3: Filter and views
Spec: Spec §5.1

method

Record::to_json_value

Spec §4

pub fn to_json_value(&self) -> Result<Value>

Summary: The parsed JSON value of the line.
Parameters: None.
Returns: Result<Value>
Errors: json
None in practice; json if it ever fails to parse.
Example: Example 7: Identity
Spec: Spec §4

struct

EntityView

Spec §5.1

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EntityView<'a> {
    pub id: &'a str,
    pub t: &'a str,
    pub name: Option<&'a str>,
    pub salience: Option<f32>,
    pub stub: bool,
}

Summary: Borrowed view of an ent record (spec §5.1 rank 3).
Fields: id: &'a strid.
t: &'a strt, the entity type.
name: Option<&'a str>name, when present.
salience: Option<f32>salience, when present.
stub: boolstub.
Example: Example 3: Filter and views
Spec: Spec §5.1

struct

RelationView

Spec §5.1

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RelationView<'a> {
    pub src: &'a str,
    pub tgt: &'a str,
    pub kind: &'a str,
}

Summary: Borrowed view of a rel record (spec §5.1 rank 4).
Fields: src: &'a strsrc.
tgt: &'a strtgt.
kind: &'a strkind, the relation label.
Example: Example 3: Filter and views
Spec: Spec §5.1

Anyone may implement this format. Copying or republishing the text of this specification requires permission from Cintile Inc.