DEV Community: fluree

What is SHACL?

Fluree Dev — Wed, 28 Feb 2024 22:06:00 +0000

SHACL is a critical tool for anyone involved in the management, curation, and utilization of RDF data. Its ability to enforce complex data quality rules in a flexible and scalable manner makes it indispensable for maintaining high-quality, interoperable datasets in the age of big data and the semantic web.

What is SHACL?

Shapes Constraint Language (SHACL) is a powerful language for validating RDF (Resource Description Framework) knowledge graphs against a set of conditions. These conditions are known as shapes and can be used by data governance professionals to streamline consistent data quality across the organization’s data ecosystem. SHACL was developed by the World Wide Web Consortium (W3C) into the open, industry standard for data quality assurance in data-centric, semantic technologies and linked data projects.

In Fluree’s graph database, users leverage policy-based SHACL to express constraints like required properties, data types, cardinality, and closed class shapes.

What is the difference between OWL and SHACL?

OWL and SHACL are typically compared as both ways in which to manage and maintain datasets, but their core competencies differ. OWL helps with inference; SHACL helps with validation. Let’s break it down further:

OWL is primarily designed for defining and reasoning about ontologies. It provides a rich set of constructs for describing the relationships between concepts in a domain, enabling sophisticated inferencing capabilities about the types of entities and their relationships. OWL is used to create complex domain models and to infer new knowledge from existing data.

SHACL, on the other hand, is focused on data validation. It allows developers and data architects to define constraints on the structure and content of RDF graphs, ensuring that the data adheres to specified patterns, value ranges, or other criteria. While OWL focuses on enabling inference, SHACL is specifically tailored for validation, offering a more direct approach to enforcing data quality rules.

What does SHACL look like?

SHACL uses a graph-based syntax, where shapes are defined as RDF graphs. Let’s take a look at a simple example: let's say that we want to ensure that all values assigned to the property "schema:birthday" are enforced as xsd:dateTime (in plain english: birthdays are formatted as valid dates and times). In Fluree, we could insert our constraint in a ledger like this:

{
  "@context": "https://ns.flur.ee",
  "ledger": "ledger/data-type",
  "insert": {
    "@id": "ex:UserShape",
    "@type": ["sh:NodeShape"],
    "sh:targetClass": { "@id": "ex:Person" },
    "sh:property": [
      {
        "sh:path": { "@id": "schema:birthDate" },
        "sh:datatype": { "@id": "xsd:dateTime" }
      }
    ]
  }
}

This example defines a shape for ex:Person instances, ensuring that the ‘birthDate’ property of such entities, if present, must be a valid date-time value.

What are the benefits of using SHACL for data validation?
Data governance is increasingly becoming critical, as organizations need to leverage clean, available, and trusted data on a day-to-day basis. By employing a global framework for data validation, organizations can save an immense amount of time and effort in standardizing data for analytics and re-use.

SHACL offers several benefits for data validation:

Flexibility and Expressiveness: SHACL can express a wide range of constraints, including property existence, value type, value range, cardinality, and more complex conditions.
Scalability: SHACL validation can be efficiently implemented, making it suitable for large datasets.
Standardization: As a W3C standard, SHACL ensures interoperability and consistency across different tools and platforms. This helps make not only the data interoperable, but also the rules that govern data consistency and validation interoperable.
Declarative Approach: SHACL allows the expression of validation rules in a declarative manner, separating the rules from their execution, which can improve maintainability and understandability of data constraints.

What kinds of quality constraints can SHACL enforce?

SHACL can enforce a variety of quality constraints, including:

Structural Constraints: Ensuring that data adheres to a specific schema or model, such as required properties, permissible property values, or specific class hierarchies.
Value Constraints: Limiting the values that can be taken by properties, including data types, value ranges, and pattern matching.
Cardinality Constraints: Defining the minimum and maximum occurrences of properties.
Logical Constraints: Applying logical conditions to properties and values, such as equality or inequality, and combinations thereof through logical operators.

How does SHACL improve enterprise data at scale?

For enterprises dealing with vast amounts of data, maintaining data quality is paramount. SHACL provides a robust framework for ensuring that data across the organization conforms to agreed-upon standards and models. At scale, SHACL helps in:

Automating Data Validation: Automated tools can leverage SHACL shapes to validate data as it is ingested, updated, or transformed, ensuring continuous data quality without manual intervention.
Enforcing Data Governance: SHACL shapes can embody data governance policies, ensuring compliance with internal and external data standards and regulations.
Improving Data Interoperability: By enforcing standardized data models and structures, SHACL facilitates data sharing and interoperability both within the enterprise and with external partners.
Enhancing Data Quality: Consistent application of SHACL validation helps identify and rectify data quality issues early, reducing errors and improving the reliability of data-driven decisions.

Try SHACL out with Fluree!
Head on over to our cookbook documentation for some examples that you can test out with your free Fluree cloud account!

What is JSON-LD?

Fluree Dev — Tue, 23 Jan 2024 17:33:17 +0000

Future-Proof Your Data with JSON-LD

Fluree has officially released native JSON-LD support. But what exactly is JSON-LD, and why does it matter?

For developers used to working with document data stores like MongoDB, JSON-LD is a bridge to the world of linked data. Linked data is the reason Google has been able to provide such unique and sophisticated services to consumers -- but that power is about to expand to far more than simple search engine optimization. Linked data allows organizations, people, and applications to access and share distributed sets of knowledge under global semantic standards- a powerful concept in the context of the modern data age.

At Fluree, we are big fans of the semantic web standards - especially RDF - because they allow for data to be organized and exchanged with universal meaning. Semantic standards are necessary for a future internet in which machines and humans can seamlessly connect to, leverage, and collaborate around disparate sets of linked data. The implications - especially in the era of emerging AI technologies, enterprise knowledge graphs, and industry data-sharing ecosystems - are profound.

But we are also realists - in the last ten years, most developers have chosen convenience over the grand vision of the semantic web, opting for JSON document data stores. JSON’s incredibly lightweight interchange format has seen mass adoption thanks in part to the influence of JavaScript on software over the last decade.

But the simplicity of JSON backfires when it comes to any case of reusing, sharing, or linking data. Without adding the context of data types, classifications, and relationships, data can easily become isolated, leading to a fragmented and siloed understanding of its implications.

That's why we're passionate about the JSON-LD specification — which Fluree has fully implemented and now supports.

What is JSON-LD?

JSON-LD -- or JavaScript Object Notation Linked Data -- combines the simplicity and ease of JSON documents with the power of linked data. JSON-LD allows you to encode meaning within your JSON document through the use of a shared vocabulary - a total upgrade from your typical JSON payload.

JSON-LD is JSON for linked data. In fact, A JSON-LD document is always a valid JSON document. Broadly speaking, there are two core capabilities that the “LD” part provides:

It allows you to embed or reference the definition of objects within your JSON payload. For example, the @context element embedded in a JSON-LD document maps object properties to concepts from an RDF ontology (a universally standardized schema).
It allows you to assign IRIs to properties in order to establish uniqueness.

🔍 What is an IRI?

An IRI (Internationalized Resource Identifier) is a generalization of the more commonly known URI (Uniform Resource Identifier). While URIs are limited to a subset of the ASCII character set, IRIs provide a way to include characters from a wider range, including Unicode. This expansion allows for the use of scripts and characters from various languages around the world, making it more globally inclusive.

In the context of linked data and the semantic web, IRIs are used to uniquely identify resources. This ensures that there's no ambiguity when referring to particular entities, concepts, or relationships, regardless of where they originate or the language they're represented in.

Understanding @ context, @ id and @ type

@ context - The @ context tag in a JSON-LD payload gives us just that - context - in the form of mapping objects in the document to a vocabulary. For example, one might map @ context to schema.org, a well-known reference site for structured data schemas.

@ id - The @ id tag gives us a way to establish uniqueness for data - which is fundamentally critical to prevent ambiguity and duplication in linked data systems. The @ id tag is sort of like a digital version of an address where we can ‘park’ unique data at URIs and point to them later on. Uniqueness in data allows us to distinguish between things or recognize that one thing in a dataset is the exact same as one thing in another dataset.

@ type - Represents the data type or class of the object, providing a way to categorize the data in terms of what it represents in the real world.

Let’s take a look at a JSON-LD document:

{
  "@context": {
    "schema": "https://schema.org/",
    "name": "schema:name",
    "author": "schema:author",
    "datePublished": "schema:datePublished",
    "articleBody": "schema:articleBody"
  },
  "@type": "schema:Article",
  "@id": "https://example.com/articles/json-ld-introduction",
  "name": "Introduction to JSON-LD",
  "author": {
    "@type": "schema:Person",
    "name": "John Doe"
  },
  "datePublished": "2023-10-27",
  "articleBody": "JSON-LD is a powerful way to represent linked data using JSON. It combines the simplicity of JSON with the capabilities of linked data, allowing for richer metadata, better SEO, and improved data interoperability..."
}

@ context: This defines the context of the JSON-LD document. It maps terms to IRIs so that properties such as "name" or "author" are clearly associated with concepts defined at "schema.org", a popular vocabulary for structured data on the internet.
@ type: Specifies that this JSON-LD document represents an article. The "schema:Article" IRI defines this as an article type as per the schema.org vocabulary.
@ id: Provides a unique identifier for this article. In this case, it's a URL to the article on "example.com".
author: Contains information about the author of the article. Nested within it, we see another @type that specifies this entity as a "Person" as per the schema.org vocabulary. The author has a "name" property.

Why use JSON-LD?

JSON-LD gives developers a familiar format in which to deliver the value of linked data and provides organizations with an easy path to integrate the benefits of linked data into a broader range of their data management operations.

Webinar | Getting Started with Fluree V3 - YouTube

Are you ready for Fluree Version 3? With an intuitive cloud-based managed service option and full JSON-LD support, we are excited to walk through our product...

youtube.com

What’s the deal with Linked Data? Linked data is the practice of connecting data across domains through the use of semantic standards. Linked data uses standardized schemas known as ontologies to transform information into organized, connected, and contextual knowledge. These properties allow data to become interlinked and machine-readable on the web and promote knowledge discovery and federated analytics. Linked data can be applied within the enterprise in the form of semantic knowledge graphs, on the public internet in the form of Open Linked Data, or in a hybrid model in the form of semantic data-sharing ecosystems.

JSON-LD allows organizations to gain all the benefits of linked data - without the hassle and overhead of transforming data or forcing developers to use a foreign data format. JSON-LD immediately increases the value of JSON documents by making the data stored within them interoperable with other linked data systems - such as internal knowledge graphs or on the open linked web - as well as by providing an accessible medium for developers and applications to interact with linked data.

Here’s a few examples of how JSON-LD makes an impact:

Building Data-Centric Applications - Software increasingly produces data that has more than one purpose - whether analytics, sharing, compliance reporting, or re-operationalization into a new application - data is versatile. JSON-LD future-proofs data for reuse within a data-centric architecture, allowing data to exist independently of a singular application and to power multiple data applications without duplication. Read more about data-centricity here.
Participation in the Semantic Web - JSON-LD gives document data a path towards participation in the semantic web. This core initial use case has seen wide adoption in the SEO (Search Engine Optimization) field because JSON-LD helps add metadata and structure to webpages. Beyond SEO, JSON data will need to interoperate at webscale for a variety of use cases - and JSON-LD is the perfect tool for the job.
Broadening the Impact and Capabilities of Enterprise Knowledge Graphs: Linking data allows the formation of ontology-driven knowledge graphs, a data management trend that supports advanced analytics and insights through the use of semantic data standards. JSON-LD allows knowledge graphs to incorporate semantically tagged documents as part of their data domains - but it also provides a medium in which to operationalize applications atop knowledge graphs.
Knowledge graphs should be dynamic and operational in that they power multiple data applications and are contributed to by multiple data source domains. This is supported by our data-centric philosophy in which data should be able to connect to, influence and power multiple data applications. Because JSON-LD extends JSON with linked data capabilities, adding and deleting objects in knowledge graphs is as simple as performing transactions against a document database like MongoDB. This read/write capability then allows a knowledge graph to serve as an operational backend to real-time web-based applications that use a JSON interface.
Feeding Analytics Better Data - JSON-LD extends the value and versatility of data with context, thereby preparing it for downstream activity. For instance, JSON-LD prepares data (that would otherwise be too simple or obscure) for an instantaneous analytical experience within data science teams. Because JSON-LD data arrives with self-describing context and a standardized semantic schema, downstream systems can immediately understand, evaluate, and take action on insights. For these systems, JSON-LD makes data immediately F.A.I.R. (Findable, Accessible, Interoperable and Reusable).
Machine-readability - JSON-LD upgrades JSON documents to become machine-readable, meaning computers can automatically exchange, access and understand information without the need for a human intermediary. This capability will be crucial for data to participate in the machine-to-machine web and power the next wave of automation and AI.
Data sharing ecosystems - Data sharing ecosystems are on the rise, introducing complexities that data systems have not had to account for in the past. For example, data from a single repository might be contributed to by multiple organizations. Or, records in a consortium might need to flow across systems and applications - in a hospital system, for example, patient information is securely collaborated on by different clinics and insurance providers.
Linked data supports these complexities - with semantic standards, we can exchange information across systems, execute federate queries across multiple disparate data sets, and collaborate around data sets with standardized schemas.
Verifiable Credentials & Decentralized Semantics - Allows for authentication and assurance of the data's source, ensuring its validity and credibility. By incorporating decentralized semantics, data gets rooted in a universally accepted framework, making it trustworthy and interoperable across a network. (check out our cool work with the Trusted Learner Network!)

Conclusion

At Fluree, our vision of the Web3.0 involves an internet of trusted and linked data. The problem is that our tools haven’t addressed the need for data to be linked - developers have found document databases quite preferable for simplicity’s sake. It’s time to prepare our data -- at the source of its creation -- with capabilities for interoperability and exchange across disparate data systems. JSON-LD is that needed bridge. Try JSON-LD out for yourself here.

There are emerging innovations for trusted and interoperable data exchange that JSON-LD will help fuel - including personal knowledge graphs and verifiable credentials. We’ll cover examples of those specifications in future blog posts.

Resources:

(https://json-ld.org/)
(https://flur.ee/json-ld/)
(https://www.slideshare.net/gkellogg1/json-for-linked-data )

Seamless Data Sharing, Baked Right In

Fluree Dev — Thu, 21 Dec 2023 20:25:39 +0000

Explore fundamental principles, uncover challenges, and discover how Fluree's open web standards effortlessly facilitate sharing data.

As things start to wind down at the end of the year, those of us in tech start looking for easy wins, like updating our email signatures to match the new company branding guidelines or scheduling a “first thing next year” check-in for that data integration effort that has as much chance of reporting progress as Santa’s milk and cookies have seeing Christmas Day.

We who manage data and share it with others knowingly smile because we’ve all seen a “data integration” project or even a “simple data request” that seems straightforward but is actually fraught with unforeseen challenges and setbacks. Why is it that these kinds of efforts are so widely known to cause grief? It’s because in a career that’s so often filled with miraculous technological advances and software tools that exponentially narrow development time and widen the impact of our efforts, we feel ridiculous estimating (and inevitably extending) a timeline of half a year or more for any project that involves sharing existing data across applications and firewalls.

Let’s get into the fundamentals of sharing data, expose the challenges lurking in the implementation details, and learn why projects that use Fluree need not be concerned about any of this thanks to a few open web standards – baked right into Fluree – that enable seamless data sharing.

The chestnut of this article came from our walkthrough documentation on the fictional Academic Credential Dataset. If you’d like to dive deeper into solving the issues tackled in this post, head on over to our docs site to see what it’s like solving hard problems with Fluree.

The Data Sharing Problem

In our fantastic doc Collaborative Data we highlight the core problem with sharing data: naming! Because you and I describe the same things in different ways – my Customers table and your CustomerDetails table might both describe Freddy the Yeti and may even contain the same exact data for Freddy, but in typical database systems, there is no way for us to know we’re describing the same yeti, nor can we even compare the data we have on Freddy from our separate systems without a mapping definition and process.

In fact, when there are any discrepancies between the source and destination schemas, the task of sharing data shifts from a self-service and, dare I say, automated task to a more complex endeavor that requires business analysts, developers, database administrators, and, of course, project managers to corral the whole circus of defining, communicating, building, and validating the necessary data pipeline. I may be exaggerating a bit, especially for smaller requests where a simple export of a small set of records is concerned, but even for a small task, some understanding of the target data and context is required by the provider and consumer to make sense of the request and resulting data. Note that in the case of building a data pipeline, much of the burden is put on the shoulders of tech knowledge workers where we’re expected to learn and reason about multiple contexts and construct systems integrations that must communicate over time and space and handle edge cases and dirty data and will eventually be asked to shoulder the weight of maintenance and changes of requirements and feature creep. This is where the cost and grief comes from.

If maintaining a consistent mapping is crucial for the data owner, it can be achieved by layering it in as the source data is added. However, this approach often results in data duplication, as the information must be stored in multiple formats. Alternatively, the mapping can be automated and done on-the-fly, as the data is requested, but this takes development resources and, depending on the amount of data and frequency of requests, can get expensive (and deeply annoying). Neither of these methods takes into account scenarios where mappings evolve over time or when there are numerous requestors, each with their unique data format requirements.

Okay so differing data schemas mean trouble for data sharing, making it complex, expensive and generally slow. So why do we have these differences in the first place? If it's such an effort to map and transform data, why can't the receiver just use the same schema as the sender? Or vice versa?

There are many reasons that vary with size and scale, but most of them boil down to communication, coordination, and cost.

Different Goals, Different Contexts

When building data exports, APIs, and other data sharing infrastructure, data owners lean on their own internal understandings of their data. There are intrinsic properties of the data (e.g. relationships, data types, field names) that only exist as a byproduct of the context in which the data owner collected and generated the data, and yet these properties dictate the format, shape, and content of the data being shared. On the other hand, each and every data consumer (those that receive data from data owners) have another distinct understanding of the data they're interested in. They operate within a different context. They have applications and analytics that are built on data of a certain shape with certain properties that have certain names and types.

Efficiently conveying these distinct contexts and ensuring that everyone consistently employs the same data context for their specific use cases can appear to be an insurmountable challenge. On the other hand, if we permit each consumer to maintain their own context, any modification to the data sharing infrastructure necessitates an equivalent degree of communication and coordination, resulting in each individual bearing the cost of staying up-to-date.

The challenges with data formatting and mapping make sharing data and hosting data sources difficult to accomplish and, when successful, constrained to niche, data-intensive research fields that require a consistent context. To mitigate, these problem spaces must rely on centralized data brokers that dictate the sharing format and other rules of engagement. This setup means relinquishing data ownership and control, reduced benefit of data partnerships, and the limited reach of knowledge and information.

The tl;dr is: the current state of data infrastructure can only produce data silos which constrain the impact of our data.

In an ideal world, we would all use the same schema, the same data context. We would use the same table names, use the same column names and data types, and, while we’re dreaming, we’d use the same identifiers for our records! That way, there’s no need for a translation layer, there’s just retrieving data. Seems silly right? There’s no way we can all use the same database schema. What would that even mean?

Fluree builds on web standards to provide essential features that, when combined, solve these traditionally challenging problems. One of these standards is the JSON-LD format, which gives our data the ability to describe itself enabling portability beyond the infrastructure where it originated. We call this “schema on write" and “schema on read,” which just means developers can build their databases on top of universal standards, and that data can be immediately shared, pre-packaged with mappings and context for consumer use cases. Let’s take a closer look at how Fluree’s approach to data management obviates these problems.

The Data Sharing Solution

What does it mean for our data to be able to "describe itself" and how does this concept solve these longstanding data-sharing problems? I mentioned the term "context" a bit in my statement of the problem. In a nutshell, the data context contains all of the semantic meaning of the data. This includes field names, relationships among objects and concepts, type information like is this data a number, a date, or a more complex class like an invoice or a patient visit. This contextual data is traditionally defined all over the place: in table and column definitions, in application and API layers, in data dictionaries distributed with static datasets, in notes columns in a spreadsheet, in the head of the overworked and under-resourced data architect. This contextual data, as discussed, can be difficult to maintain, represent, and transfer to data consumers.

But wait! What if all this data was stored and retrieved as data in the dataset? What would it look like if we took all of the contextual data that can be found in the best, most-complete data dictionary, API documentation, or SQL schema explorer and just inject it right in there with the data content itself? JSON-LD and a few other open web standards, like RDF and RDFS, do this exactly and Fluree relies on them to enable simple and seamless data sharing.

RDF and JSON-LD are simply data formats that can represent graph data. We go into more detail in our Data Model doc and there are some excellent resources online as RDF has been around for a bit. RDFS is an extension of RDF that adds some very useful data modeling concepts like classes and subclasses, which enables us to describe the hierarchies in our data. JSON-LD and its ability to convey contextual and vocabulary data alongside the data itself is talked about extensively in our excellent Collaborative Data doc.

The gist is that by using universally defined identifiers for both subjects and properties, all participants (both data sources and consumers) can build on top of a fully-defined and open understanding of the data schema. No more data silos.

Oh hey! Thanks for reading! I’ll leave you with another benefit of using Fluree: portability! Portability, the opposite of “vendor lock in”, is another one of Fluree’s incredible side effects. Because Fluree is built on open standards, like the ones discussed in this article, all of the value provided is baked right into the data itself! This means that Fluree is relying on externally-defined mechanisms (including the storage format, RDF) that have meaning outside of any Fluree database or platform. So when sharing your data or if you decide to use a different database in the future, all of the self-describability goes along for the ride!

Blog credits to Fluree Developer Jack White

Fluree is moving to Discord

Trey Botard — Tue, 04 Jan 2022 01:06:44 +0000

The Fluree community has seen substantial growth over the last year.
With the velocity of growth and the big goals we have for the community,
we need a new home.

Discord has become an ever-present tool for communication on the web. The Fluree community has been on Slack for the past several years and for the most part we have been satisfied by the platform. However, over the past year, we've seen significant growth and as we've grown, we've begun to run up against some of the shortcomings of Slack as a platform for an open community. As we imagined where we want to take the Fluree community going forward, it became harder and harder to see how we could modify our vision to fit within the bounds of Slack. We needed a new platform for our community. After investigating the alternatives, we found Discord to be an extremely attractive option with all of the benefits provided by Slack and a ton of new functionality to boot. We did some preliminary internal testing, then tested the waters with a couple weeks of beta testing (shout out to our Beta testers!) and found the experience to be even better than we had hoped.

So, we made the exciting decision to migrate our community on over.

Why Migrate?

No message limits

The primary limitation in Slack is the message limits. If you weren't aware, Slack only allows up to 10,000 messages per workspace. There are over 700 members in the public Fluree Slack and the amount of chat happening meant that we were only able to see messages within about a 6-month window. As our community grows, that window will only shrink and the knowledge shared within this space will be lost at an accelerated pace. Discord has no message limit.

Voice chat and screen share

Another big point of differentiation between the two platforms is the availability of voice chat and screen sharing. Discord has a ton of features around this which we will begin to take full advantage of. We want to enable our members to self-organize and work on things together using the Fluree Discord as needed. This will enable just that. Not to mention the functionality the Fluree team can use to host events and activities from with Discord. (We have some fun stuff planned for this year!)

Open by default

Another issue with Slack for an open community is the way channels are structured. Channels are hidden by default and require a member to be invited or actively search for new channels to join. This is not the way Discord is set up. All channels are public by default, which creates an easy path to exploration and cross-pollination, with good tooling for a user to manage notifications per channel or category as desired. We think this is better for an open community and are excited for this change in structure.

Better moderation tooling

Fortunately, this hasn't been an issue thus far, but moderation is a vital part of community management. Creating a safe space for all of our community members is extremely important to the Fluree team and frankly the tooling for moderation in Slack is practically non-existent. Discord provides functionality which will enable us to create the spaces we want and ensure a welcoming, helpful, and safe environment for all who choose to join us.

Timeline

Here's the plan for the migration:

Thurs. Jan 6th: Open Discord server to the public.
Mon. Jan 10th, and Fri. Jan 14: Fluree DevRel team will be available for questions in the Discord to assist with the new tool.
Mon. Jan. 31st: Close public Slack channels to new comments. Begin migrating private channels to shared channels where needed.
- We will migrate private support channels to shared Slack channels from our internal Slack workspace.
Thurs. Feb 3rd: February Office Hours to be held in the new Discord server!!

Of course, the team will be available for any questions in both Discord and Slack for the duration of the migration and are more than happy to assist where needed.

We are extremely excited for this new chapter of the Fluree community. There will be bumps in the road as we migrate such a large community, but we are confident this is the right choice, both for the long term health of the Fluree community and for Fluree itself.
Keep an eye on our Twitter in the coming weeks for an invite link to the new Discord server. If you're in the Fluree Slack, we'll
be making an announcement there as well.

We look forward to seeing you in the new Fluree Discord!

Fluree in Docker - A Single Instance

Trey Botard — Thu, 07 Oct 2021 21:25:12 +0000

Managing dependencies is a pain in the tuchus. Whether in the cloud, in a private data center, or just on your laptop, ensuring that you have the correct version of Java or Node or whatever other runtime works properly with both the application and the OS and all of the other dependencies can quickly turn into a nightmare. Docker solves this by bundling all of the dependencies together in a single image such that as long as the Docker runtime is deployed on the target infra, your app should function as desired. No muss, no fuss. 🥳

Let's walk through the set up necessary to get your Fluree backend up and running. (Deployment to a public cloud will be out of scope for this post). This will be the first of a 3 part series on working with Fluree in Docker. The next one will be about setting up a Transactor Group!

Getting Started

To begin with, you will need to have Docker on your machine. Please visit the Docker Getting Started Docs to get it set up, if you don't have it configured already.
Once Docker is installed and running you will need to grab the Fluree ledger image from DockerHub. The Docker CLI is a great tool for managing images on your machine. We will use the docker pull command to grab the fluree/ledger image. Open a terminal and run:

docker pull fluree/ledger:latest

At the time of writing, this will pull the 1.0.0 beta 15 ledger image from Docker Hub, which is the most up-to-date version of Fluree. Once the Fluree ledger 1.0.0 is released, beta releases will go under their own tag. At any time, you can pull a specific release, if that is needed. You would simply define the image to pull using the tag like this: fluree/ledger:1.0.0-beta14.
You can see all of the release tags for Fluree in our Github Repo.

Set up and run the container

Ok, you have the image, now what?
There are a couple of parameters which Fluree needs in order to start up correctly.
These can be passed in when starting the container using the docker run command.

You can simply start the image by calling docker run fluree/ledger, but this will not expose the ports you will need to have in order to use the HTTP endpoints. Internally, Fluree listens on port 8090 for the HTTP calls, so this port will need to be mapped to an exposed, public port on the container. This can be done with:

docker run -p 8090:8090 fluree/ledger

The ports correspond to ExternalPort:InternalPort. So, if you have 2 containers running, you will need to map the first of the two to a different port and leave the second number as-is because that is the port which Fluree is listening on. So for your second container, you would pass -p 8091:8090 or some other port number of your choosing.
This spins up Fluree inside of your container, you will see the default configs print to the terminal and some messages about the consensus and state of the server. You can see the container and some metadata by running docker ps in another terminal.

Naming your Container

By default, Docker will assign your container both a CONTAINER_ID and a NAME, which you can see via the docker ps command or in the Docker Desktop UI. The name will be 2 randomly assigned words, but you can name your container when you initialize it with the docker run command. This is useful because you can then use that name to restart your container, if you stop it for whatever reason. (At this point stopping the container will lose any data, but in a bit, we will connect the container's file system to a local directoy for data persistence 🙌). You can do this by adding the --name flag to the run command, like this:

docker run -p 8090:8090 --name ledger1 fluree/ledger

Now, when you run docker ps, the NAMES field will be ledger1 instead of a randomized pair of words.

One caveat to using the --name flag is that if you stop your container or kill the terminal, that name will still be associated with that container. So you may need to run docker rm ledger1 to remove the container, if you want to docker run with the name ledger1 again. (This applies to the randomly-assigned container names as well. They will exist on the machine until they are removed.)

Interacting with your Instance

Now that your ledger is up and running on your machine, there are a few ways for you to interact with the ledger.

Admin UI

Every instance of Fluree contains a small utility for working with the ledgers, called the AdminUI. This is a browser based UI maintained by the Fluree team for working with instances of Fluree, whether as a single instance or in a transactor group. Once you have your Fluree instance ready with the HTTP port exposed, you can start the Admin UI by going to http://localhost:[EXPOSED PORT] in your browser.
If you used the command above to start up your instance, use 8090 for the [EXPOSED PORT].

We have a YouTube video walkthrough of the AdminUI coming soon.

HTTP Calls

Fluree also contains an HTTP client which exposes several HTTP endpoints for programmatically working with Fluree. Any of these endpoints can be hit by calling http://localhost:8090/fdb/[endpoint] or if the endpoint is ledger specific http://localhost:8090/fdb/[network]/[db][endpoint].

At startup, there are no dbs on your instance, so it is recommended to start by using the /new-db endpoint first.

Create a Persistent Volume

Fluree is a ledger and database. Both of these things require persisting data, which Docker does by default, but we'll want to configure it ourselves. To do that, we will need to do what is called mounting a volume to the container. This volume will live on after the container is spun down or goes offline for some reason in the place where we told it to be.

Fluree already has a mechanism for writing to a file system. In fact, there is a customizable parameter which enables you to specify the path in the file system where you would like Fluree to write its data. You can see all of the configuration options in the docs. The config we are interested in now is fdb-storage-file-directory. By default, this is set to /var/lib/fluree whether Fluree is being run in a container or in a JVM directly on a server. This means we can use some functionality in the Docker CLI to bind a directory in our local filesystem to this directory inside the container. Docker run has a flag called --volume (aliased to -v) where you can specify the two directories to be bound together. It will look like this -v "[local/path/to/dir]:[container/path/to/dir]".

For my example, I will tell my container to bind to Users/treybotard/Projects/fluree-data/docker-blog/. To put this together with the run command from above; your command should look like this:

docker run -p 8090:8090 -v "/Users/treybotard/Projects/fluree-data/docker-blog/:/var/lib/fluree" fluree/ledger

Now that I've run this command, I can open up the AdminUI, add a new ledger to my Fluree instance, and when I path to my docker-blog folder, I will see 2 folders, group/ and ledger/. These are the folders Fluree uses to maintain raft logs (in group/) and the encrypted indexes (in ledger/). I'm not going to go into too much detail here about this structure. If you are interested in reading more about how Fluree maintains the indexes or how Fluree interacts with the file system you can read more in the docs.

Private key file

When using the --volume command to persist your data outside of the container, if a private key is not provided on start-up, Fluree will create a default private key. This key (whether provided or generated at startup) is used for a few access controls in developement mode. What this means is that if you want to reuse the same identity to access the persisted data, you will need to store your key outside of the container and pass it in when spinning up a fresh container. This can be done a few different ways, but for simplicity's sake, we'll just look at passing the private key into the container as an environment variable with -e. Using an environment variable requires passing in -e FDB_GROUP_PRIVATE_KEY=[PRIVATE_KEY] when starting the container.

Now our command looks like this:

docker run -p 8090:8090 -v "/Users/treybotard/Projects/fluree-data/Docker-blog/:/var/lib/fluree" --name ledger1 -e FDB_GROUP_PRIVATE_KEY=123456789 fluree/ledger:latest

Docker start and stop

One very convenient way to maintain my development environment is to use the --name flag on a container with a volume mounted on it. What this enables is the stop and start functionality in the Docker CLI. If i have a container specifically for a client project or a demo I am working on, I give it a meaningful name "docker-blog" and mount it to a volume stored next to the source code where I am working. I can then conveniently run docker start docker-blog when I am ready to work on the container. It knows which ports to use and can spin up the container exactly the way it was when I ran docker stop docker-blog when I stopped working on it before.

Other Convenience Commands and Flags

`--rm`

If you are just testing out some some ledgers and are making some throw-away ledgers, I recommend adding the --rm flag. Going to spin up a named container which you forgot to spin down, but getting an error that the container name already exists gets old quickly. This will remove the container when you either CTRL+C or send SIGINT to the container some other way.

`-d` and `attach`

If you have been spun up a Fluree container before, you will have seen that the output is relatively chatty. One easy way to not have to see that in your terminal is to pass the -d flag when starting up the container. This will run Fluree in a detached process and not print to the console. You can run docker attach [container name] to reattach to the console and see the logs in your terminal. If you didn't give the container a name, you can look it up with docker ps -a to see all the containers, including the ones which are stopped.

`docker exec`

Sometimes, it can be very useful to have a bash terminal inside a running container while Fluree is running. You can use the docker exec command to run a command inside a running container. One useful way which I use this is to run docker exec -it [container name] /bin/bash. This opens a bash terminal in the working directory of my container where Fluree is running.

It can also be useful to access the file system in a container with Fluree inside it, even when Fluree is not running. To startup a container without initializing Fluree, you need to use docker run, but override the --entrypoint. That looks like this:

docker run -it --entrypoint=bash fluree/ledger

This will start up a container and give you a bash terminal with which to explore.

With these commands, a large percentage of the functionality needed to work with Fluree locally can be achieved. Next week, we'll take a look at how to set up a Transactor Group (several Fluree instances networked together) in Docker using similar commands and Docker compose!

Time traveling with Fluree

Trey Botard — Thu, 01 Jul 2021 18:18:35 +0000

Intro

When you get down to it, if you are building an app with Fluree as the backend, it is simplest to think of Fluree as a database. This can be a useful way to think about working with Fluree, but by doing so there is a lot being left on the table. The unique combination of technologies which make Fluree what it is enable some extremely powerful functionality and unlock ways of working with data which are either uncommon or simply not possible with other data stores. Let's talk about what some of those are, how to use them, and what this type of functionality could enable in your Fluree-backed application.

Background

In addition to a graph database for querying data, Fluree is built with an immutable ledger as the backbone which holds the dataset. This part of Fluree is what enables some really interesting and particularly unique functionality. 'Immutable ledger' is one of those terms which I had to Google in order to understand when I started at Fluree, so let's break that down a bit.

Fluree associates related data elements, called subjects. Each subject has an _id which is used to correlate the attributes (called predicates) and the values of those predicates together to form the "facts" about that subject.

Fluree is based on an extended version of the W3C standard for RDF, which is where this notion of SPO (Subject, Predicate, Object) comes from.

You can think of it like a row in a db table with _id being the unique identifier for the row, predicates are the columns, and the values are the fields. Each field makes up a fact about the instance of data stored in that particular row in the db. For example, in a Dog table with a Breed column, each row corresponds to a unique Dog who is described by the attributes and fields. The same idea holds in Fluree. An _id groups the related predicates, which point to values, in order to make up the "facts" of that subject. So, the dog/breed predicate would point at an object, "french bulldog", for example. At the point in time when that fact was written to the ledger, that specific subject's breed was french bulldog.

Each of these facts are stored in an immutable data structure. Immutable means that those data structures are not available to be modified or changed in any way. Instead of simply changing a value or updating a "row" in the data, Fluree will make a new true fact in the ledger and associate it with the appropriate subject. If this is a value which is being "modified" then Fluree will make two new facts; one where the old fact is false and the second a new, true fact, both of these facts are then associated with the subject and written to the ledger.

This is part of the "extension" to RDF. Each flake contains a boolean which indicates whether it is true or has been falsified. You can read more about this in the flakes page in the docs.

This brings us to what a ledger is. You can think of a ledger as discrete units or "blocks" which contain the history of the data as it is transacted. These blocks are made of groups of immutable facts which are sent to an instance of Fluree. Each block is linked to the one which came before it so there is a chain of blocks from when the ledger was created to the current block. In Fluree, this chain is queryable, which means once some data has been transacted to Fluree you have the history of every data element in that data set!

Time travel

So, back to those powerful pieces of functionality I mentioned at the beginning.
There are two ways of querying the data which enable what we call time travel in the Fluree world. There are block queries and history queries, both unlock elements of Fluree which are only possible because of the immutable data structures and the ledger. Block queries enable querying the data state at specific moments in time and history queries allow you to get an overview of all of the modifications to a particular subject.

Why

We'll get into how each of these types of queries work, but first, why does this even matter?
One of the primary benefits to having this type of view into your data is the ability to correlate events with the data state at the time that event happened. For example, say you are tracking prices for flights and you want to see what effect the weather had on flight prices or which day of the week prices tended to be the cheapest. The sky's the limit for these types of analytical queries.
You also may want to enable your users to see the state of some piece of data when it was updated. I saw a comment on a LinkedIn post once and was pretty sure that the commenter worked for the company who's post he was commenting on, but his current job title was recently updated so I couldn't tell where he worked when the comment was added, only where he currently worked - the current state of the data.
This type of functionality can be useful in a wide range of circumstances or situations. Having a way to view not only the current state of the data (table stakes for any database), but a way to see the state of a piece of data at a specified time OR for a specified range of time, can be extremely useful. Fluree goes a step further though. When you are querying some data a point in time, you are also seeing all of the facts which were true at that time as well. This includes all of the relationships which existed at the time. This is something which is not possible in any other database or data store that I am aware of. You are able to query not only the historical values of something in your data but also all of the context associated with that data as well. That is huge.

Now, think about how you would go about making something like this in your db of choice. Building out a historical view of a table in a traditional database, whether in a relational or NoSQL db, is a large and expensive maintenance burden, the size of your db will explode because of data duplication without significant optimization, and querying these db tables or documents can become relatively complex; specifically what happens to references? Does the reference point to the current table or is there a way to manage the reference such that it points to the correct row in the historical table? What happens when you want to do a join to with another table? There isn't an expedient or simple way to do either of those things, to my knowledge. One or two other data stores enable historical views, but are not able to pull in all of the context and maintain relationships as well.

Putting it all together

Both of these operations are exposed via an API within a Fluree db instance. Simply passing a JSON to the /block or /history endpoint is all that is needed to query this type of data. Let's get into how to use each of these queries. I will be using the Fluree Query Language (FlureeQL), which is a JSON-based way to query the backend. Fluree also supports querying via GraphQL, SPARQL, SQL or calling these endpoints directly from Clojure, but we'll use FlureeQL to illustrate this functionality. If you want to read more about our query surfaces, check out the query pages for more details.

Block Queries

There are two ways to query a block in Fluree. You can either issue a query against the /block endpoint which returns the flakes in that particular block or range of blocks, or you can add a "block" key to a basic query issued to the /query endpoint. This basic query method of querying can, and probably will, pull in facts which were transacted to the ledger before the specified block. When you issue a regular query with a block key, you are issuing a query as if the specified block were the current block.
Each of these types of query is beneficial, and can be useful depending on how you need to view your data.

Let's start with a query issued to the /block endpoint. This type of query currently supports 2 keys:

  "block": number,
  "prettyPrint": boolean

"prettyPrint" is a boolean, which if true, prints the results in a pretty printed, aka styled format, for easier reading, as well as separating the asserted and retracted flakes into their own arrays in order to make them easier to parse. The "block" key is much more interesting. It can take a number, a string in the form of an ISO-8601 formatted date-time or duration, or an array which specifies a range of block for the query.

For example, to query a specific block:

{
  "block": 3
}

You can query via a time stamp. This will return the first block which was transacted before this timestamp. In other words, it will give you the facts which were true at that time.

{
  "block": "2017-11-14T20:59:36.097Z"
}

You can also use an ISO-8601 formatted duration:

{
  "block": "PT5M"
}

This will return the state of the data as of 5 minutes ago.

If you would like to query a range of blocks, you can pass an array containing the blocks you would like to see. This range is inclusive, meaning the data returned will include both blocks you put in the array.

{
  "block": [5, 18]
}

You can also pass an array with a single block which will specify a lower, also inclusive, block and return the facts from that block up to the current block.

Using the /block endpoint will return an array of flakes, each of which is a fact stored in Fluree at that block or range of blocks. While this is useful, it is probably more realistic that you would want to see a specific set of data using a normal query, but have the results returned as if they had been issued at some point in the past. This is also enabled in Fluree by issuing a query to the /query endpoint which contains the "block" key-value pair. This key expects the value to be structured in the same way as the examples above, with the value being one of a number, a formatted string, or an array of block numbers. So the main difference is that this type of query will pull in data which is not limited to a specific block, it returns data as if the query had been issued when that block was the current block. For example, if you had a Dog collection of subjects in your ledger, you could issue this query to see all of the dogs which had been transacted and not deleted as of block 7:

{
  "select": ["*"],
  "from": "Dog",
  "block": 7
}

To read more on querying blocks, check out the docs pages for block queries and querying with the block key

History Queries

The way a /history query is structured and issued is relatively similar to /block queries, but are fairly different in what results are returned. As I mentioned above, a history query returns all of the modifications to a subject. I like to think of a block query showing the breadth of the data at a specific time and the history query as looking down the timeline of a specific piece of data.
For example, if you had a customer in your dataset who has connections to other customers, you could see the history of that customer's connections from when they first joined your application up to the current block. If you wanted to see the connections that customer had at a specific block or over a range of blocks, that is possible, as is using the ISO-8601 date-times or durations.

You can build a /history query using FlureeQL in JSON the same way you would with a /block query. For example, if you know the subject's _id you can simply hit the /history endpoint like this:

{
  "history": 351843720888320
}

This query will return an array of objects, each object containing the block and t numbers for that block and an array of flakes for that subject.

Another option is to issue a history query with a block key in order to constrain the results of the query to a specific timeframe in your data. That looks like this:

{
  "history": 369435906932737,
  "block": 4
}

This query will return the flakes for this _id up to block 4. You can also use a block range or use the ISO-8601 formatted string similar to the /block queries.

Using a flake format is another way you can issue a history query. This means that you can use pieces of data to identify the subject you want to query. This works via the subject, predicate, object structure of a flake. You pass the elements you want to use to query in an array as the value of the "history" key in the query JSON. The array needs to be passed as ["subject", "predicate", "object"], but you do not have to use all 3 elements in the array for the query to resolve.

Please note that the order of these within the array is important and either a subject or a predicate is required.

For example, if you want to query for the history of all subjects matching the predicate object pair dog/breed "french bulldog" in your collection, you could query the ledger like this:

{
  "history": [
    null, 
    "dog/breed", 
    "french bulldog"
  ]
}

Another way this could be done is using either a subject _id with a predicate, or substitute a two-tuple which uniquely identifies a subject for the _id.
That would look like this:

{
  "history": [
    351843720888320, 
    "dog/favFoods"
  ]
}

or with a two-tuple

{
  "history": [
    ["dog/name" "Jacques"], 
    "dog/favFoods"
  ]
}

Both of these queries will return the history of the predicate "dog/favFoods" for the dog specified, with either the subject _id or the unique identifier of ["dog/name" "Jacques"] used to identify the subject you want to inspect.
Similar to the "/block" queries, a "/history" query can also accept a "prettyPrint" key-value pair. When true this will return the history of the subject or predicate as indicated, but will separate out the retracted and asserted flakes per block into their own arrays. That looks like this:

{
  "history": 351843720888320,
  "prettyPrint": true
}

which will return something in this type of structure:

{
  "4": {
    "asserted": [
      {
        "_id": 351843720888320,
        "dog/breed": "french bulldog"
      }
    ],
    "retracted": []
  }
}

In the return JSON, each block containing data which matches the query is its own labeled object containing a named array for asserted and retracted.

"showAuth"

There is one other extremely powerful way to use "/history" queries to audit the history of who transacted the data. You can issue a "showAuth" boolean key-value pair or an array of _auth/id or _auth subject _id's in order to filter the history query to specific auth record's transactions. Because each transaction is signed by a private key which is associated cryptographically with the _auth/id, every flake in Fluree contains a record of who issued that transaction. This is the way to view that data. It looks like this:

{
  "history": 351843720888320,
  "showAuth": true
}

This will return an array of block objects, each of which will contain a named array of "auth" which consists of the auth's subject _id and the "_auth/id of the individual (man or machine) which signed that block. Which will look something like this:

[
  {
    "block": 2,
    "flakes": [
      [ 17592186044436, 40, "dog", -3, true, null ],
      [ 17592186044437, 40, "cat", -3, true, null ],
      [ 17592186044438, 40, "ferret", -3, true, null ]
    ],
    "t": -3,
    "auth": [
      105553116266496,
      "TexTgp1zpMkxJq1nThrgwkU5dp9wzaXA7BX"
    ]
  }
]

For more information on how Fluree stores and interacts with identity and authorization, please take a look at the identity section in the docs.

Wrap it up

So that's how you can go about time traveling in Fluree. There are powerful tools which come out-of-the box which enable you to do things like query as of a specific moment in time, see how a subject evolved over time in your dataset, or get all of the data which was transacted by a specific auth record. You can read more about it in our docs site or if you would prefer to engage with our community, come join us on Slack.

For more detail about this subject, you can watch our Time and Immutability Webinar on YouTube:
This has video has a publicly available demo which you can review here:

fluree / time-webinar

Demo app which uses the create-react-app template for Fluree to embed a webworker with the application. This demo showcases functionality around issuing block and history queries.

Time and Immutability Webinar Demo

This is the repository used for the demo in the Time and Immutability Webinar.

Set up

To begin working with this demo app, you will need to have Fluree running locally on your machine For detailed instruction on getting Fluree installed, please visit the installation page on the docs site.

You will also need to have Node.js installed on your machine.

The data folder contains the seed data for using this application as it is shown in the webinar. To get the data loaded into your Fluree instance, follow these steps:

Open the Admin UI and create a ledger called time/webinar.
Using either the Admin UI or a REST client of your choosing (Postman, Insomnia, etc.) transact the files in the data/ folder, in order, to your ledger
- This will transact the schema
- The airports and tags for the statuses
- The flight.json files…

View on GitHub

Tutorial: To-Do List Generator V2: Identity and Permissions

Flor Marshall — Mon, 21 Jun 2021 18:06:30 +0000

Issuing Identity and Permissions at the Data layer with Fluree DB

Recap

This tutorial is a follow up to the first tutorial found here on dev.to or on github on the to-do-list branch, where we built a to-do list generator using React and Fluree. If you are not familiar with Fluree, please refer to the first part of this tutorial series to learn the basics.

Getting started

To get started git clone the repo via git clone https://github.com/fluree/version-2-lists-generator.git, or any other preferred method.
cd into the repo and run npm install
then run npm start to locally serve the app in your browser at http://localhost:3000

Fluree

As previously mentioned Fluree is a Web3-capable graph database platform powered by an immutable ledger. The architecture of Fluree gives developers a lot of freedom and control over the way data is managed, specifically the enabling of permissions that go along with data maintenance. Unlike regular dbs, plagued with data-silos and ever changing APIs to manage application-specific permissions and identity, Fluree offers the ability to implement them directly in the data layer.

Identity and Permissions

To fully understand the way identity and permissions work in Fluree, we will need to dive into the different collections and predicates that help facilitate this capability.

User, Auth, Rules, and Roles

_user, _auth, _rule, and _role are built in collections within Fluree that hold the criteria needed to implement user permissions and control identity. Below is a diagram showcasing how each collection is connected to each other by their predicates.

A user can have an auth record associated with their identity, that auth record is then governed by the roles associated with it. Each specific role has rules that dictate their access (read and write) to the data. The role that comes straight out of the box in Fluree is ["_role/id","root"], this role has full read and write access to the db. Users can have multiple roles connected to their auth record, and each role can have a different set of rules as well. Also users can have multiple auth records, but multiple users cannot share the same auth record.

It is worth noting that an auth record does not need to be tied to a user, they can be used independently with a collection of your choosing.

Generating Auth records with Public-Private Keys

The way auth records control identity in Fluree are by tying the record to a specific public-private key pair (specifically generated using the secp256k1 elliptic curve). This cryptographic identity enables the user to sign their transactions and queries according to their permissions. There are a number of ways to generate the public-private key/auth id triple, and can be found here in the docs. In this tutorial we will be issuing them using the Admin UI in the sections below.

Signing queries and transactions can be done in different ways found here, in this tutorial we use the @fluree/crypto-utils library.

Integrating identity and permissions into the Application

Now that we have a basic understanding of how identity and permissions can be used within Fluree lets take these concepts and configure them within our application. We will need to refine our schema, add roles and rules, create smart functions, and generate auth records with private-public keys.

Make sure to change the network and db variables located in the appConfig.js to mirror your Fluree network and db namespace, and double-check that you're using the correct port (e.g. :8090).

Schema Changes

In the previous version of this application the _user collection was not used, but now that we need to leverage permissioning we will utilize the _user collection, along with their username predicate. The only other additions are the following predicates: list/listOwner, assignee/user, and task/issuedBy, where all of these predicates reference the _user collection. The list/listOwner predicate references a single user, while theassignee/user predicate is multi: true, meaning it can reference multiple users, given that a list can have more than one assignee. The entire schema can be found hereand transacted to a new Fluree ledger.

Roles and Rules

We have two types of users: list-owners and assignees. In this scenario we do not need to create multiple roles for these users, one role is suitable to control what the different users can see and do. Any difference in how list-owners and assignees can interact with lists and tasks can be permissioned based on how each user is linked to those records in the schema.

We will create an endUser role and utilize the existing root role.

We can transact our new role to the DB:

[
  {
    "_id": "_role?endUser",
    "id": "endUser"
  }
]

Now that we have the root role and our additional endUser role we need to create the rules that will govern what the roles can and cannot do. Below is a graphic with the rules associated with each role.

At first glance it doesn't seem like the root user and the endUser differ in what they can and cannot do, but in order to fully grasp how the rules are enforced we need to dive into Smart Functions. Smart functions are functions written in Clojure*, they can be triggered with any query or transaction that a user attached to a certain role issues. These smart functions live in the _fn collection, the _rule collection has a predicate called _rule/fns which is a reference to this collection. So when an action takes place the smart function that is connected to a certain rule is evaluated and will either return true or false depending if the user in question has the permission to execute the desired action.

*Currently, Smart Functions are only usable in Clojure, although we are alpha-testing a version of Fluree that allows for JavaScript-written Smart Functions as well. Stay tuned for updates!

Rules and Smart Functions

It is important to note that smart functions are not limited to use in rules, they can be used in _collection/spec, _predicate/spec, _predicate/txSpec and even in transactions, an example of each can be found here. But for the purpose of demonstrating permissions, all of our smart functions are connected to the rules mentioned above. Now lets create a rule that is connected to a smart function:

[
  {
    "_id": "_rule$fullAccessOwnListData",
    "id": "fullAccessOwnListData",
    "doc": "A _user with this rule can only view and edit their own list data",
    "fns": ["_fn$fullAccessOwnListData"],
    "ops": ["all"],
    "collection": "list",
    "predicates": ["*"]
  },
  {
    "_id": "_fn$fullAccessOwnListData",
    "name": "fullAccessOwnListData?",
    "doc": "A _user can query and edit their own list data",
    "code": "(relationship? (?sid) [\"list/listOwner\" \"_user/auth\"] (?auth_id))"
  }
]

The JSON snippet above is an example of a transaction that issues both a rule and its accompanying fn. Starting with the rule object it includes a temporary id (for the transaction) that will evaluate to a integer once it's in Fluree. It also includes an id, a description, the fns associated with the rule in the form of a temporary id, ops is set to all (meaning this applies to both actions: transact and query), and the collection and its predicates to which this rule is attributed to. In this case it applies to the list collection and all of its predicates.

In short, this rule indicates that the fullAccessOwnListData smart function will be run every time a user with this rule either transacts or queries any data field available to records in the list collection.

The next object is a transaction item that creates the smart function connected to this rule. It uses a temporary id, a name, a description, and the code is in Clojure. Clojure is a Lisp family language developed for the Java Virtual Machine, and is the language Fluree uses to program its core software. For an in-depth look at Clojure's syntax visit Learn X in Y minutes: Clojure, and useful introduction material can be found at Clojure for the Brave and True. Lets break the code down:

(relationship? (?sid) [\"list/listOwner\" \"_user/auth\"] (?auth_id))

There are a subset of Clojure functions that can be used in the code, but in this tutorial all of our smart functions use the relationship? function. The syntax for the relationship? function is as follows (function startSubject path endSubject).

In our implementation, this maps to the following:

function: relationship?
startSubject: (?sid)
- (?sid) is a context-dependent function which refers to the specific subject id being queried/transacted in the context of the current function evaluation.
path: [\"list/listOwner\" \"_user/auth\"]
- The path can be a single predicate or a vector of predicates that potentially connect the two subjects. Essentially, for the relationship? smart function to be satisfied, we use this schema-defined path to evaluate whether a relationship exists between two subjects. In our example, if the data links a list to the user accessing the list, via the path of list/listOwner, then we can understand the user accessing the list is the owner and should be entitled to specific permissions.
endSubject: (?auth_id)
- (?auth_id) is also a context-dependent function and refers to the specific auth record (i.e. public cryptographic identity) that is querying/transacting against the data at the time of the smart function evaluation.

The whole code evaluates if the relationship between the subject id and the auth record id return true, given the path. In this example in order for a listOwner to view their list data, their id must have a connection to the auth record id, via the path [list/listOwner _user/auth] that bridges that connection within the data & the schema that models it.

Not all rules may need a custom smart function as the one above, in some cases a user's ability to query and transact certain data should always be true. That means there does not have to be a startSubject or endSubject evaluated through a path. For a rule to always evaluate to true we simply set the _rule/fns to "fns": [[ "_fn/name","true"]], the same can be done if a rule must always evaluate to false.

{
  "_id": "_rule$canViewAssignees",
  "id": "canViewAssignees",
  "doc": "A _user with this rule can view all assignee data",
  "fns": [["_fn/name", "true"]],
  "ops": ["query"],
  "collection": "assignee",
  "predicates": ["*"]
}

The transaction above is a rule where all users can view assignee data, so this rule will always evaluate to true.

We won't go over every rule and their smart functions connected to the endUser role, however they can all be found here and transacted to the Fluree ledger.

Auth records and public-private keys

Now that the roles and rules are transacted into the ledger it is time we create auth records for our users and connect them to public-private keys in order for us to sign queries and transaction, as well as see it in the app UI.

The sample schema provided here has users with nested auth records, like the example below:

[
  {
    "_id": "_user$6",
    "username": "rootUser",
    "auth": [
      {
        "_id": "_auth",
        "id": "Tf3VDot4jSKHFcLY8HSPsuf2yA5YBnRsEPU",
        "roles": [["_role/id", "root"]]
      }
    ]
  }
]

This auth id is already tied to a public-private key pair, in the sense that it is derived directly from an secp256k1 public key. This auth record just needs to be transacted, along with the rest of the sample data. The gif below shows how to generate an auth record with private-public keys through the admin UI, by selecting transact on the left navigation bar, then pressing the Generate Keys button above the code editor.

This will prompt a modal to appear with the Public Key, Private Key, and Auth Id. You can either transact the auth record within the modal (remembering to make the appropriate role changes if necessary), then connect the auth id to a user in a separate transaction, or you can copy the auth object, and nest it into a user transaction similar to the one above. But be sure to save the public and private keys externally before closing the modal. In this tutorial there have six users in our sample data and their public-private keys and auth ids are kept in the usersAuth.js. Once the sample data is fully transacted, we can now move on to issuing signed queries and transactions.

Signing Queries and Transactions

The marriage between issuing permissions and generating private-public keys takes place when users sign queries and transactions. The signature proves that whoever is issuing the query or transaction has access to the private key, and so on successful submission it validates their access to view the data or make changes. There are a few ways to go about signing, in this tutorial we use the NPM package, @fluree/crypto-utils, but other methods can be found here.

Signing Queries

The query below uses the signQuery function. It takes a private key, param, queryType, host, and db as parameters (defined below), then it returns an object with keys: header, method and body, which can be sent to the /query endpoint (or other possible endpoints such as /multi-query, history, and block). This specific query can be found here, it is triggered on load and defaults to the rootUser on the tab component. Each tab option is a different user with different permissions. The lists view changes given their identity.

import { signQuery } from '@fluree/crypto-utils';
import usersAuth from './data/usersAuth';

const fetchListData = {
  select: [
    '*',
    {
      tasks: [
        '*',
        {
          assignedTo: ['*'],
        },
      ],
    },
  ],
  from: 'list',
  opts: {
    compact: true,
    orderBy: ['ASC', '_id'],
  },
};
const privateKey = selectedUser.privateKey;
const queryType = 'query';
const host = 'localhost';
const db = `${network}/${database}`;
const param = JSON.stringify(fetchListData);
let signed = signQuery(privateKey, param, queryType, host, db);
fetch(`${baseURL}/query`, signed) //fetch issues the request to the given url and takes the output of signedQuery.
  .then((res) => res.json())
  .then((res) => {
    setLists(res);
  })
  .catch((err) => {
    if (/not found/.test(err.message)) {
      return console.log("this didn't work");
    }
  });

Signing Transactions

These are two example transactions, they both use the signTransaction function, which takes an auth id, db, expire, fuel, private key, tx, and optional deps. It is similar to the query version, but the output of signTransaction is then placed within the body of the POST request. Please refer to deleteTaskFromFluree and editTaskProps for their full implementation.

import { signTranaction } from '@fluree/crypto-utils';
import usersAuth from './data/usersAuth';

let deleteTaskFromFluree = () => {
  const privateKey = selectedUser.privateKey;
  const auth = selectedUser.authId;
  const db = `${network}/${database}`;
  const expire = Date.now() + 1000;
  const fuel = 100000;
  const nonce = 1;
  const tx = JSON.stringify([
    {
      _id: chosenTask._id,
      _action: 'delete',
    },
  ]);

  let signedCommandOne = signTransaction(
    auth,
    db,
    expire,
    fuel,
    nonce,
    privateKey,
    tx
  );
  const fetchOpts = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(signedCommandOne),
  };

  fetch(`${baseURL}command`, fetchOpts).then((res) => {
    return;
  });
};

let editTaskProps = () => {
  const privateKey = selectedUser.privateKey;
  const auth = selectedUser.authId;
  const db = `${network}/${database}`;
  const expire = Date.now() + 1000;
  const fuel = 100000;
  const nonce = 1;
  const tx = JSON.stringify(taskChangeTransact);
  let signedCommandTwo = signTransaction(
    auth,
    db,
    expire,
    fuel,
    nonce,
    privateKey,
    tx
  );

  const fetchOpts = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(signedCommandTwo),
  };
  fetch(`${baseURL}command`, fetchOpts).then((res) => {
    return;
  });
};

Wrap up

At its core identity and permissions within Fluree are simply data, but with security in the data layer power and scalability are not at the mercy of firewalls and APIs. It's time to move away from application-centricity and embrace data-centricity.

To learn more about architecture, infrastructure, and identity, visit the Fluree guides section. And for other repo examples visit our developer hub.

Tutorial: Build a To-Do List Generator With Fluree

Flor Marshall — Thu, 29 Apr 2021 15:05:11 +0000

Intro

This tutorial is designed to introduce a simple React application that utilizes FlureeDB to manage data. A basic understanding of React is assumed, as is basic experience with a relational DB and querying/inserting data with SQL.

We will break down the different technologies that make up Fluree, and show how data lives and is connected within Fluree. Then demonstrate how to integrate it in an application, by using any HTTP client (in this application we use axios), queries and transactions are issued to create, read, update, and destroy data from the FlureeDB.

Getting started

To get started git clone the repo via git clone https://github.com/fluree/to-do-lists-generator.git, or any other preferred method.
cd into the repo and run npm install
then run npm start to locally serve the app in your browser at http://localhost:3000

React

To keep things simple this application uses Create React App.

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

What is Fluree?

Fluree is a Web3-capable graph database platform powered by an immutable ledger backplane.

If you are not familiar with chain or blockchain data, think of it as a list of provable transactions that are sequenced by time. This ledger is tamper-proof and each block in the ledger is linked to the previous block.

Every block contains critical metadata like a hash, a timestamp, and the size of the block data (block-bytes). The core data that constitutes each block, though, are extensions of RDF triples that we call flakes. These flakes contain all the data that is added, updated, or deleted at the moment in time described by each block. Flakes are an integral part of Fluree and are used to represent everything: for a in-depth look at Flakes refer to the architecture docs.

Fluree's graph schemas are made up of collections and predicates, we will go further into how to use them in the Schema section below.

At its core, data in Fluree leverages the Resource Description Framework (RDF). RDF is a W3C standard model for data interchange on the Web*. Data in Fluree is modelled by the RDF Triple, which contains a subject, a predicate, and an object.

A simple example would be: "The sky's color is blue", where 'sky' is the subject, 'color' is the predicate, and 'blue' is the object. When comparing the same sentence to the typical approach of an entity–attribute–value model: entity(sky), attribute(color), value(blue).

*For a more in-depth look into RDF refer to the W3C docs.

Getting Started with Fluree

This to-do list app uses Fluree Anywhere to manage data, for a in-depth installation guide of Fluree visit the Installation docs. For brief installation points refer below.

Installing Fluree

Download latest stable version and unzip Fluree (fluree-1.0-latest)
Launch Fluree with default options by running ./fluree_start.sh in the terminal for Macs and in Bash emulator for Windows.
Once Fluree is done starting up it will be available for use behind port 8090, e.g. http://localhost:8090. [Note: for versions below 1.0.0 the default web server port may be :8080]. Navigating to :8090 in your browser will serve Fluree's default AdminUI. The Fluree server behind :8090 will also respond to POST requests against Fluree's HTTP API endpoints.
To exit, click ctrl + c to kill the thread in your terminal. This will not delete any ledgers or successful transactions.
For further installation information visit the Installation docs.

Fluree requires Java 11 or above. To verify your version run java --version in the terminal or visit java to download.

For those who use Docker: docker run -p 8090:8090 -v $PWD/data:/var/lib/fluree fluree/ledger (no installation or other dependencies necessary). Refer to Fluree Docker installation here.

Creating your Ledger, Schema, and Sample Data

In this section we will break down ledger creation, implementing a basic schema, and adding sample data.

Ledger

A ledger in Fluree is basically the mechanism which stores and keeps track of updates or transactions to your data. There are a few different ways to create a new ledger, for more details refer to the ledger docs.

Here we will create a new ledger in the admin UI:

After pressing the 'Add Ledger' button you will see the modal below. Enter a network name and DB name, for example: test/one1

The name of your network and ledger will become part of the unique URL that includes the API endpoint. Example: http://localhost:8090/fdb/test/one1/query

Schema

Once the ledger has been created the next step is to build your schema. Schemas in Fluree consist of collections and predicates.

You can think of collections as tables in a relational DB and predicates as columns, although you should refer to the Schema section in the docs for a more elaborate explanation. An important detail to note is that Schemas in Fluree are just data, and the easiest way to add data is using our JSON syntax to represent the schema and transact it into the database. As you see below, we are using this JSON syntax -- aka FlureeQL -- to create our transactions. FlureeQL combines features from GraphQL and SPARQL while maintaining a convenient JSON shape.

Below is the schema for the to-do list generator:

The schema has three collections: list, task, and assignee.

    [{
        "_id": "_collection",
        "name": "list",
        "doc": "Subjects in this collection will be individual to-do lists, which can reference several specific tasks."
    },
    {
        "_id": "_collection",
        "name": "task",
        "doc": "Subjects in this collection will be individual tasks, which can reference individual assignees"
    },
    {
        "_id": "_collection",
        "name": "assignee",
        "doc": "Subjects in this collection describe individuals who could be assigned specific tasks"
    }]

We've added some doc strings to each collection and predicate to offer additional clarity for users. This descriptive metadata does not affect the schema other than to aid any developers who need to understand it.

Each collection has three predicates.

The list collection consists of list/name, list/description, and list/tasks

[
    {
        "_id": "_predicate",
        "name": "list/name",
        "type": "string",
        "index": true,
        "doc": "The name of the list. This is indexed for easier querying, but is not a unique value from one list to another"
    },
    {
        "_id": "_predicate",
        "name": "list/description",
        "type": "string",
        "doc": "A string describing the list"
    },
    {
        "_id": "_predicate",
        "name": "list/tasks",
        "type": "ref",
        "multi": true,
        "restrictCollection": "task",
        "doc": "Because one list can include multiple tasks, this allows a single list subject to make graph references to multiple task subjects"
    }
]

The task collection consists of task/name, task/assignedTo, and task/isCompleted

[
    {
        "_id": "_predicate",
        "name": "task/name",
        "type": "string",
        "index": true,
        "doc": "The name of the task"
    },
    {
        "_id": "_predicate",
        "name": "task/assignedTo",
        "type": "ref",
        "restrictCollection": "assignee",
        "doc": "A ref between a task and an assignee, modeling the individual to whom the task is assigned"
    },
    {
        "_id": "_predicate",
        "name": "task/isCompleted",
        "type": "boolean",
        "doc": "The completion status of the task"
    }
]

The assignee collection consists of assignee/name, assignee/email, and assignee/lists

[
    {
        "_id": "_predicate",
        "name": "assignee/name",
        "type": "string",
        "index": true,
        "doc": "The name of the assignee"
    },
    {
        "_id": "_predicate",
        "name": "assignee/email",
        "type": "string",
        "unique": true,
        "doc": "The email of the assignee"
    },
    {
        "_id": "_predicate",
        "name": "assignee/lists",
        "type": "ref",
        "multi": true,
        "restrictCollection": "list",
        "doc": "The lists owned by an individual -- this is potentially different from the tasks that are assigned to a specific individual"
    }
]

An important thing to note about predicates is that within Fluree they are their own type of collection, so they can consist of predicates themselves (you can think of them as properties that describe a type of predicate). For example, _predicate/name is a predicate that belongs to the _predicate collection. For a list of types and further explanation refer to the predicate docs.

Once you have solidified your schema you can insert it into your DB, using the admin UI, as your first transaction:

In the example gif above we transacted only the collection schema as a separate transaction item, but if we wanted to transact the schema (collection and predicates) together, we can easily achieve this by creating a single transaction array with each transaction item as individual objects. Refer to the example here.

To explore your schema and understand the connectedness of each collection and predicates, Fluree gives you the ability to visualize each relationship. In the gif below we select Schema on the left nav bar then press the Launch Schema Explorer button.

Sample Data

After setting your schema it is time to transact some data. Similar to how you transacted your schema you will transact data within the admin UI. To grab a copy of the sample data refer to the code here.

When the sample data has been successfully transacted, run the npm start command to view the application with populated data in the browser (i.e. by opening http://localhost:3000). You should see the following:

Querying and Transacting Data within the application

Now that you have some data inside of Fluree, we can dive into the way we structure queries and transactions in the application. As this is a simple to do list we will be able to create a new list with 1 or more sets of tasks; each task having an assignee. We are also able to delete a task, and edit a task's name and completion status, and add a new assignee.

First, lets review the functionality that is connected to the DB and the data that is being received and sent.

The application will need to pull the assignee data in order to populate the Select Assignee dropdown component in the form. We will also need to grab the list data from Fluree when the app initially mounts in order to populate the Todo and the Task components. This will all be done by querying Fluree.

While Fluree does allow querying in GraphQL, curl, and SPARQL... queries issued in this application are in FlureeQL's simplified JSON syntax. Please refer to the docs for examples in the languages mentioned above, by toggling the Display Examples at the top left corner.

Querying assignee data

Below is the query that pulls the assignee data from Fluree when the application loads. You can find it here within the loadAssignedToData function.

    {
        "select": ["_id", "email", "name"],
        "from": "assignee"
    }

    OR

    { 
        "select": [ "*" ], 
        "from": "assignee" 
    }

This is a basic query, where we are selecting all the _id, email, and name predicate values (these can also be substituted with just "*") in the assignee collection. This is similar to a SQL query where we would write the same query as,

    SELECT  _id, email,name
    FROM assignee;

    OR

    SELECT * FROM assignee;

Refer to the code base here for the API request that hold the assignee data query.

Querying list data

Below is the query that pulls all the related list data from Fluree when the application loads. You can find it here within the fetchListData function.

{
    "select": [
        "*",
        { 
            "tasks": [
                "*",
                { 
                    "assignedTo": ["*"] 
                }
            ]
        }
    ],
    "from": "list",
    "opts": { 
        "compact": true 
    }
}

We can think about this JSON query as "crawling the graph", wherein we crawl across linked data by representing references from one collection to another as nested objects within our JSON syntax. These references are available through ref predicates such as list/tasks. So essentially we are selecting ALL the data from the list collection then each of the records in the task collection that are specifically linked to each list, since list/tasks is a reference predicate in the list collection.

The next graph-crawl pulls related data from the assignee collection, since the task/assignedTo predicate in the task collection is a reference predicate to the assignee collection. All the data above is linked via the predefined predicates of type ref.

The other section of this query (below the from clause), uses the query key of opts which is not required, but gives you the ability to set optional keys when retrieving data. For a list of optional keys and their descriptions, refer to the doc here.

Another way of thinking about the predicate type of ref are as joins in relational DBs, but the ability to join is a property set to predicates (in Fluree) as displayed in the predicate schema above. A SQL example of the query below would be,

    SELECT *,
    task.isCompleted,
    task.assignedTo,
    assignee.name,
    assignee.email
    FROM list
    JOIN task ON task.list_id = list.id
    LEFT JOIN assignee on assignee.name = task.assignedTo
    ORDER BY ASC;

As a schema grows, these sorts of joins can become deeply complicated in a SQL-shaped schema, particularly when joins are mediated by additional join tables. One significant advantage of Fluree's graph schemas and graph query language is the ability to navigate links between data more directly and easily. Another advantage is the ability to query for JSON-shaped data in JSON itself.

Refer to the code base here for the API request that hold the list data query.

Transacting and updating data

The next set of functionality we will cover are the ones that send transactions to Fluree in the application, these are the equivalent to INSERT or UPDATE statements in SQL. When the form component is filled and submitted, the data is sent to Fluree via the /transaction API. The /transaction API is also used when a task is deleted, when a task name is edited, or when the checkbox completed status is changed: these are all updates that are sent to Fluree via a transaction.

Transacting data to Fluree

Here we will break down all the steps that go into transacting the form data to Fluree, and the creation of the transaction that is nested in the API request. Start at the addList function here in the code base.

The const newList is the transaction item that holds the list data. Lets run through it and dissect each part, then we will compare it to the seed data we entered earlier. If we were to just transact a list without any linked tasks, it might look like the following:

[{
    "_id": "list$1",
    "name": "My List",
    "description": "This is my grocery list"
}]

In FlureeQL's JSON syntax, we differentiate transactions by wrapping each { transaction object } in [ bracket notation ]. This also allows us to imply that a single transaction might [{ include }, { many }, { transaction }, { items }].

The _id value must describe the collection this record should belong to. In this example the $1 suffix gives the record a unique "temporary id", in case you need to reference this record elsewhere within your transaction. For more temp id examples visit Temporary Ids in the Transaction Basics section of the docs. Below is a diluted example of the query above in SQL:

    INSERT INTO list (_id, name, description)
    VALUES("list$1", "My List", "This is my grocery list")

Of course, our lists are most valuable when they link list data to independent task record data. An individual task record transaction might look like this:

[{
    "_id": "task$1",
    "name": "Get Milk",
    "isCompleted": false,
    "assignedTo": ["assignee/email", "jDoe@gmail.com"]
}]

When a ref predicate like task/assignedTo needs to refer to a subject that already exists, Fluree allows you to easily identify that subject by providing a two-tuple of [A_UNIQUE_PREDICATE, THAT_PREDICATE'S_VALUE]. So that in the example above, we can have this new task refer to an assignee whose assignee/email value is jDoe@gmail.com. You can also, however, reference a brand new assignee (see examples below where a new list references a new task), or use a current assignee's unique _id value.

Below is an example of the same transaction above in SQL:

    INSERT INTO task (_id, name, isCompleted, assignedTo)
    VALUES ('task$1', 'Get Milk', false, (SELECT id from assignee WHERE email='jDoe@gmail.com'))

In the examples above, we described list and task transactions separately, but we can easily transact them at once. Below is an example of the transaction array with nested transaction items that is sent to Fluree on submission of a new list with new tasks:

[{
    "_id": "list",
    "name": "My List",
    "description": "This is my grocery list",
    "tasks": [{
        "_id": "task",
        "name": "Get Milk",
        "isCompleted": false,
        "assignedTo": [
            "assignee/email",
            "fmarshall@flur.ee"
        ]
    },
    {
        "_id": "task",
        "name": "Get Bananas",
        "isCompleted": false,
        "assignedTo": [
            "assignee/email",
            "jDoe@gmail.com"
        ]
    },
    {
        "_id": "task",
        "name": "Get Spinach",
        "isCompleted": false,
        "assignedTo": [
            "assignee/email",
            "jDoe@gmail.com"
        ]
    }]
}]

This could also have been transacted using Temp IDs -- the Seed-data file in src/data provides exactly this example.

Refer to the code base here for the API request that holds the list data transaction.

Adding a new Assignee to Fluree

Above we presented a transaction with list data that included an assignee already within the drop down selection, but there is functionality in place to create a new assignee and send their information to Fluree, before a transaction with all list data is sent. Below is the query found in addNewAssignee

[{
    "_id": "assignee$1",
    "name": "John",
    "email": "john.doe@gmail.com"
}]

The same transaction can be mirrored in SQL as:

INSERT INTO assignee (_id, name, email)
VALUES ("assignee$1", "John", "john.doe@gmail.com")

Refer to the code here for the API request that holds the creation of a new assignee data transaction.

Updating & Deleting Existing Data in Fluree

Updating data uses the same structure and syntax as transacting new data to Fluree. We will be updating data by using the _id retrieved from the query in fetchListData.

Deleting tasks

deleteTask holds the asynchronous function deleteTaskFromFluree that deletes the task.

[{
    "_id": 369435906932736,
    "_action": "delete"
}]

Instead of using temporary ids, here we match the _id to the intended task then use the _action transact key to specify a deletion when sent to Fluree. For more on deleting data refer to the deleting data section. The same transaction can be written in SQL below

DELETE FROM task
WHERE task._id = 369435906932736;

Refer to the code base here for the API request that holds the deletion transact item.

Editing tasks

Similar to the way we delete tasks above, editTasks matches the task _id and includes the data change for the updated name of the task and updated completion status. For more detail updating data refer to the updating data section. This transaction takes a task that already exists and updates its name and its completion status:

[{
    "_id": 369435906932736,
    "name": "This is my task name now",
    "isCompleted": true,
}]

The same transaction can be written in SQL as:

UPDATE task
SET
    task.name = "This is my task name now",
    task.isCompleted = true,
WHERE
    task._id = 369435906932736

Refer to the code base here for the API request that holds the update transact item.

Learn more

For other API endpoint and examples visit the Fluree docs, here.

We also have other tutorials, which cover additional Fluree functionality in our Developer Hub.

For more information on the Fluree ledger and its Blockchain technology visit the Blockchain docs.

A deeper dive into analytical queries and examples visit the docs section, here.

A subject we did not cover in this tutorial is Smart Functions in Fluree, which can be used in setting permissions to your DB. Here is a full list of accepted smart functions.

DEV Community: fluree

What is SHACL?

What is SHACL?

What is the difference between OWL and SHACL?

What does SHACL look like?

What kinds of quality constraints can SHACL enforce?

How does SHACL improve enterprise data at scale?

What is JSON-LD?

Future-Proof Your Data with JSON-LD

What is JSON-LD?

🔍 What is an IRI?

Understanding @ context, @ id and @ type

Why use JSON-LD?

Webinar | Getting Started with Fluree V3 - YouTube

Conclusion

Resources:

Seamless Data Sharing, Baked Right In

The Data Sharing Problem

Different Goals, Different Contexts

The Data Sharing Solution

Fluree is moving to Discord

Why Migrate?

No message limits

Voice chat and screen share

Open by default

Better moderation tooling

Timeline

Fluree in Docker - A Single Instance

Getting Started

Set up and run the container

Naming your Container

Interacting with your Instance

Admin UI

HTTP Calls

Create a Persistent Volume

Private key file

Docker start and stop

Other Convenience Commands and Flags

--rm

-d and attach

docker exec

Time traveling with Fluree

Intro

Background

Time travel

Why

Putting it all together

Block Queries

History Queries

"showAuth"

Wrap it up

fluree / time-webinar

Demo app which uses the create-react-app template for Fluree to embed a webworker with the application. This demo showcases functionality around issuing block and history queries.

Time and Immutability Webinar Demo

Set up

Tutorial: To-Do List Generator V2: Identity and Permissions

Issuing Identity and Permissions at the Data layer with Fluree DB

Recap

Getting started

Fluree

Identity and Permissions

User, Auth, Rules, and Roles

Generating Auth records with Public-Private Keys

Integrating identity and permissions into the Application

Schema Changes

Roles and Rules

Rules and Smart Functions

Auth records and public-private keys

Signing Queries and Transactions

Signing Queries

Signing Transactions

Wrap up

Tutorial: Build a To-Do List Generator With Fluree

Intro

Getting started

React

What is Fluree?

Getting Started with Fluree

Installing Fluree

Creating your Ledger, Schema, and Sample Data

`--rm`

`-d` and `attach`

`docker exec`