今天就來研究怎麼開始用 SDK 在 Cloud Firestore 建立資料吧。

在 Cloud Firestore，我們大致有幾種方式可以寫入資料：

1. 在指定集合中，去建立由開發者自己命名 ID 的文件，並且設定（Set）該文件的資料。
2. 在指定集合中，先要求系統自動建立起一個文件參照，並在之後才塞資料進去。這時文件的 ID 是系統自動隨機產生的。
3. 在指定集合中，直接說要加入（Add）一組資料並建立起文件，這時系統會自動隨機產生文件的 ID ，

由於目前 Web SDK 的功能是相對完整的，這邊就直接用 JS 作為示例。並透過程式碼去解釋相關行為。

let cityDocRef = db.collection('cities').doc('LA')
cityDocRef.set({
    name: 'Los Angeles',
    state: 'CA',
    country: 'USA'
})
.then(function() {
    console.log('Document successfully written!')
})
.catch(function(error) {
    console.error('Error writing document: ', error)
})

從上面的程式碼我們可以看出大致分為四個部分：

1. 先建立起文件的參照，也就是 db.collection('cities').doc('LA')
2. 將資料塞進該文件參照裡，也就是 set() 方法。
3. 成功執行後的回呼函式，也就是 then() 方法。
4. 執行失敗後的回呼函示，也就是 catch() 方法。

這樣的範例程式碼基本上就屬於一開始講的情境，也就是指定文件 ID 並且設置其資料。那如果我們要讓系統幫我們產生 ID 時該怎麼做呢？那就只要把 doc() 裡面的參數刪掉即可，以這個示例來說，就是這樣更改：

// 自訂文件 ID
let cityDocRef = db.collection('cities').doc('LA')

// 系統隨機產生文件 ID
let cityDocRef = db.collection('cities').doc()

這樣的改法，就是去面提到的第二種方式，那第三種方式又該怎麼做呢？這時就要用到 add() 方法了：

let citiesRef = db.collection('cities')
citiesRef.add({
    name: 'Los Angeles',
    state: 'CA',
    country: 'USA'
})
.then(function(docRef) {
    console.log('Document written with ID: ', docRef.id);
})
.catch(function(error) {
    console.error('Error writing document: ', error)
})

是的，剛剛提到的 set() 是文件參照的方法，而現在使用的 add() 是集合參照的方法，也就讓我們要求集合將塞進去的這組資料直接建立成文件。

那假設預定的文件參照已經存在時，我們使用 set() 在塞資料會發生什麼事呢？那就會讓我們塞進去的資料完全取代舊有的資料，不會有任何的合併。若舊資料原本有某個欄位、但在設定的新資料是沒有的，那個欄位就會不見。基本上你可以視為我們先將這個參照既有的文件刪除，再以現有提供的資料建立起一個新的文件，所以在使用上要特別注意。