Install
Find Shooju
in Nuget in Visual Studio or download directly from the Shooju Nuget Page.
Connect
- Create an API Key on the My Profile (under your name on the top-right of the website) page by using Create New API Key.
- Make note of the server (the url of the Shooju instance you log in to), username (it's on the top of the My Profile page)
- Instantiate a Connection in C#:
using Shooju;
...
var sj = new Connection("https://trial.shooju.com","my username", "api-key from step #1");
Read from Shooju
Get a single Series by a Queries (the query should return only 1 series):
sj.GetSeries("sid=my\\series\\id", fields: new List<string> {"description"}, df: "MAX", dt: "-4w", maxPoints: -1);
Get multiple Series more efficiently:
var m = sj.GetMultiGet();
m.GetSeries("eia_series_id=NG.E_ERTCES_XS0_R48F_C.M", fields: new List<string> {"description"}, df: "MAX", dt: "-4w", maxPoints: -1); // queues up the first series to retrieve
m.GetSeries("sid=EIA\\NG\\NG.N5070892.A", fields: new List<string> {"description"}); // queues up the second
var theTwoSeries = m.Fetch(); // only one request to the server is sent; theTwoSeries[0] has the first response and theTwoSeries[1] the second
Scroll through many Series using a single Queries (this is the most frequently used and efficient method when retrieving many series):
foreach (Series series in sj.Scroll("state:Alaska", new List<string> { "sid", "description" }))
{
Console.WriteLine($"series id {series.SeriesId}: {series.Fields["description"]}");
}
Working with Expressions
To retrieve data from Expressions, use same syntax from Series Editor:
sj.GetSeries("={{ sid=my\series\id1 }}", df: "MIN", dt: "MAX", maxPoints: -1);
Working with Expression Globals
It is also possible to retrieve results for Expression Globals you have built within Shooju using extra_params
parameter inside GetSeries():
expression = @"
query1 = "sid=my\\series\\id1"
query2 = "sid=my\\series\\id2"
# any logic can be placed here, calling F functions is also possible and should be exactly the same used in Series Editor
G.r = sjs(query1) + sjs(query2) # assign here result of your expression
"
sj.GetSeries("=G.r", df: "MIN", dt: "MAX", maxPoints: -1, extraParams: new Dictionary<string, string> {"g_expression": expression});
You can also see expression above in the Series Editor.
Write to Shooju
Instantiate a job and write a field and points for a series id:
var job = sj.RegisterJob("test job", batchSize: 20, maxPointsPerBatch: 100000);
job.PutFields(SERIES_ID, new Dictionary<string, dynamic> { { "description", "Hello World!" }, { "unit", "km" } });
job.PutPoints(SERIES_ID, new List<Point> { new Point(new DateTime(2015, 1, 1), 42.12) });
job.Finish();
Explore the Job class methods for more methods. Make sure to job.Submit() or job.Finish() at the end if the batchSize is greater than 1.
Delete Series
You can use job’s function DeleteSeries
. Except for query
it has two more params:
- one - specifies whether the query is expected to delete just one series
- force - specifies if series should be moved to “trash“, or permanently deleted
var job = conn.RegisterJob("Delete series", batchSize: 2000);
job.DeleteSeries("sid=XXX", false, false);
job.Finish();
Additional Resources
Refer to the intellisense of each function for detailed parameter explanations.