Dataset Save function is confusing

I am referencing this doc: save - Velo API Reference -

I have a page that renders a form. I want to save the form inputs to my dataset on submit. But according to the documentation the save function does not take any parameters. How is that possible? How can I define the data that I want to save? Is there something else I should be using to accomplish this?

Hello. I just took a look and yes, those examples don’t really tell the whole story.

If you want to save a new item to the dataset, you will first want to use the setFieldValue or Values apis to update the dataset and then call save()

If what you want to do is update the collection directly, you may want to consider the wix-data API’s save() or insert/update depending on what you are trying to accomplish

Thank you for the clarification. So if I try to call dataset.setFieldValues and pass in an object without an “_id” value then it will create a new item

By the same logic If I search for an item and it does exist I can call setFieldValues and pass in the existing “_id” of the item and it will update an item correct?

@amotor I tend to use the wix-data api’s so I can’t say I’ve tested this yet. In looking at the API docs more, actually if you are trying to create a new row of data but through the dataset, you would likely need to add() a new item first and then populate it and then call save() to save the new row with it’s data

From the docs:
“The add() function saves the current item and then adds a new blank item. When the editing of the new item is complete, you will need to call another function that will save the new item.”

setFieldValues is for updating the current dataset item For example updating a title or name and then calling save() to save the new values.

from the docs:
“The setFieldValues function sets the value of a set of fields in the current item.”

In short, when using datasets the save() function is called after any action that manipulates the data so you will want to look through the different API functions and see exactly which one covers what you are trying to do.

Let me know how it goes, I don’t have a personal working example of this ready to go but if it’s not behaving as expected I can get one together

1 Like

@amandam Thank you. The wix-data api will work perfectly for this. I was just looking at the wrong thing.

1 Like

@amotor Oh good! Yes, I prefer the direct interacting with collections that the data API provides. But you did bring up a good point about the dataset docs. It’s a good place to create some better examples. Thanks!