Struct grafana_plugin_sdk::data::Frame

pub struct Frame {
    pub name: String,
    pub meta: Option<Metadata>,
    /* private fields */
}

A structured, two-dimensional data frame.

Frames can be created manually using Frame::new if desired. Alternatively, the IntoFrame trait (and its reciprocal, FromFields) provide a convenient way to create a frame from an iterator of Fields.

Frames generally can’t be passed back to the SDK without first being checked that they are valid. The Frame::check method performs all required checks (e.g. that all fields have the same length), and returns a [CheckedFrame<'_>] which contains a reference to the original frame. This can then be used throughout the rest of the SDK (e.g. to be sent back to Grafana).

Examples

Creating a Frame using the Frame::new:

use grafana_plugin_sdk::{
    data::{Field, Frame},
    prelude::*,
};

let field = [1_u32, 2, 3].into_field("x");
let frame = Frame::new("new")
    .with_field(field);

Using the IntoFrame trait:

use grafana_plugin_sdk::prelude::*;

let frame = [
    [1_u32, 2, 3].into_field("x"),
    ["a", "b", "c"].into_field("y"),
]
.into_frame("super convenient");

Fields can be accessed using either Frame::fields and Frame::fields_mut, or by using the Index and IndexMut implementations with field indexes or names:

use grafana_plugin_sdk::prelude::*;

let frame = [
    [1_u32, 2, 3].into_field("x"),
    ["a", "b", "c"].into_field("y"),
]
.into_frame("frame");

assert_eq!(
    frame.fields()[0].name,
    "x",
);
assert_eq!(
    frame.fields()[1],
    frame["y"],
);

Fields

name: String

The name of this frame.

meta: Option<Metadata>

Optional metadata describing this frame.

This can include custom metadata.

Implementations

impl Frame

pub fn new(name: impl Into<String>) -> Self

Create a new, empty Frame with no fields and no metadata.

Examples

Creating a Frame using the Frame::new:

use grafana_plugin_sdk::{
    data::Frame,
    prelude::*,
};

let frame = Frame::new("frame");
assert_eq!(&frame.name, "frame");

pub fn add_field(&mut self, field: Field)

Add a field to this frame.

This is similar to Frame::with_field but takes the frame by mutable reference.

Example

use grafana_plugin_sdk::prelude::*;

let mut frame = [
    [1_u32, 2, 3].into_field("x"),
]
.into_frame("frame");
assert_eq!(frame.fields().len(), 1);
frame.add_field(["a", "b", "c"].into_field("y"));
assert_eq!(frame.fields().len(), 2);
assert_eq!(&frame.fields()[1].name, "y");

pub fn fields(&self) -> &[Field]

Get an immutable reference to the the Fields of this Frame.

Example

use grafana_plugin_sdk::prelude::*;

let mut frame = [
    [1_u32, 2, 3].into_field("x"),
]
.into_frame("frame");
assert_eq!(frame.fields().len(), 1);
assert_eq!(&frame.fields()[0].name, "x");

pub fn fields_mut(&mut self) -> &mut [Field]

Get a mutable reference to the the Fields of this Frame.

Example

use arrow2::array::{PrimitiveArray, Utf8Array};
use grafana_plugin_sdk::prelude::*;

// Create an initial `Frame`.
let mut frame = [
    [1_u32, 2, 3].into_field("x"),
    ["a", "b", "c"].into_field("y"),
]
.into_frame("frame");

// Update the frame's fields.
frame.fields_mut()[0].set_values(4u32..7).unwrap();
frame.fields_mut()[1].set_values(["d", "e", "f"]).unwrap();

assert_eq!(
    frame
        .fields()[0]
        .values()
        .as_any()
        .downcast_ref::<PrimitiveArray<u32>>()
        .unwrap()
        .iter()
        .collect::<Vec<_>>(),
    vec![Some(&4), Some(&5), Some(&6)],
);
assert_eq!(
    frame
        .fields()[1]
        .values()
        .as_any()
        .downcast_ref::<Utf8Array<i32>>()
        .unwrap()
        .iter()
        .collect::<Vec<_>>(),
    vec![Some("d"), Some("e"), Some("f")],
);
assert!(frame.check().is_ok());

pub fn check(&self) -> Result<CheckedFrame<'_>, Error>

Check this unchecked Frame, returning a CheckedFrame ready for serializing.

Frames may be in an intermediate state whilst being constructed (for example, their field lengths may differ). Calling this method validates the frame and returns a CheckedFrame if successful. Checked frames can then be used throughout the rest of the SDK (e.g. to be sent back to Grafana).

Errors

Returns an error if the fields of self do not all have the same length.

Example

use arrow2::array::{PrimitiveArray, Utf8Array};
use grafana_plugin_sdk::prelude::*;

assert!(
    [
        [1_u32, 2, 3].into_field("x"),
        ["a", "b", "c"].into_field("y"),
    ]
    .into_frame("frame")
    .check()
    .is_ok()
);

assert!(
    [
        [1_u32, 2, 3, 4].into_field("x"),
        ["a", "b", "c"].into_field("y"),
    ]
    .into_frame("frame")
    .check()
    .is_err()
);

pub fn with_name(self, name: impl Into<String>) -> Self

Return a new frame with the given name.

Example

use grafana_plugin_sdk::data::Frame;

let frame = Frame::new("frame")
    .with_name("other name");
assert_eq!(&frame.name, "other name");

pub fn with_metadata(self, metadata: impl Into<Option<Metadata>>) -> Self

Return a new frame with the given metadata.

Example

use grafana_plugin_sdk::data::{Frame, Metadata, Notice, Severity};

let mut notice = Notice::new("read this notice".to_string());
notice.severity = Some(Severity::Warning);
let mut metadata = Metadata::default();
metadata.path = Some("a path".to_string());
metadata.notices = Some(vec![notice]);
let frame = Frame::new("frame").with_metadata(metadata);
assert_eq!(frame.meta.unwrap().path, Some("a path".to_string()));

pub fn with_field(self, field: Field) -> Self

Return a new frame with an added field.

Example

use grafana_plugin_sdk::{data::Frame, prelude::*};

let frame = Frame::new("frame")
    .with_field([1_u32, 2, 3].into_field("x"))
    .with_field(["a", "b", "c"].into_field("y"));
assert_eq!(frame.fields().len(), 2);
assert_eq!(&frame.fields()[0].name, "x");
assert_eq!(&frame.fields()[1].name, "y");

pub fn with_fields(self, fields: impl IntoIterator<Item = Field>) -> Self

Return a new frame with added fields.

Example

use grafana_plugin_sdk::{data::Frame, prelude::*};

let frame = Frame::new("frame")
    .with_fields([
        [1_u32, 2, 3].into_field("x"),
        ["a", "b", "c"].into_field("y"),
    ]);
assert_eq!(frame.fields().len(), 2);
assert_eq!(&frame.fields()[0].name, "x");
assert_eq!(&frame.fields()[1].name, "y");

pub fn set_channel(&mut self, channel: Channel)

Set the channel of the frame.

This is used when a frame can be ‘upgraded’ to a streaming response, to tell Grafana that the given channel should be used to subscribe to updates to this frame.

Trait Implementations

impl Debug for Frame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Frame

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: IntoFrame> FromFields<T> for Frame

fn from_fields(name: impl Into<String>, fields: T) -> Frame

Create a Frame with the given name from fields.

impl Index<&str> for Frame

type Output = Field

The returned type after indexing.

fn index(&self, name: &str) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<usize> for Frame

type Output = Field

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<&str> for Frame

fn index_mut(&mut self, name: &str) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<usize> for Frame

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl Serialize for Frame

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.