From ee8af9cfa38f1f73d724e53636e7b7d96dda3b63 Mon Sep 17 00:00:00 2001
From: Patrick Mezard <patrick@mezard.eu>
Date: Sun, 4 Oct 2015 11:25:58 +0200
Subject: [PATCH] doc: document field values storage and retrieval

---
 mapping_field.go |  2 ++
 search.go        |  3 ++-
 search/search.go | 16 ++++++++++------
 3 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/mapping_field.go b/mapping_field.go
index 0cc10082..bc08b055 100644
--- a/mapping_field.go
+++ b/mapping_field.go
@@ -28,6 +28,8 @@ type FieldMapping struct {
 	// the IndexMapping.DefaultAnalyzer.
 	Analyzer string `json:"analyzer,omitempty"`
 
+	// Store indicates whether to store field values in the index. Stored
+	// values can be retrieved from search results using SearchRequest.Fields.
 	Store              bool   `json:"store,omitempty"`
 	Index              bool   `json:"index,omitempty"`
 	IncludeTermVectors bool   `json:"include_term_vectors,omitempty"`
diff --git a/search.go b/search.go
index 1d123af1..dc523a74 100644
--- a/search.go
+++ b/search.go
@@ -152,7 +152,8 @@ func (h *HighlightRequest) AddField(field string) {
 // Highlight describes optional search result
 // highlighting.
 // Fields describes a list of field values which
-// should be retrieved for result documents.
+// should be retrieved for result documents, provided they
+// were stored while indexing.
 // Facets describe the set of facets to be computed.
 // Explain triggers inclusion of additional search
 // result score explanations.
diff --git a/search/search.go b/search/search.go
index aabb0c76..f3997fff 100644
--- a/search/search.go
+++ b/search/search.go
@@ -37,12 +37,16 @@ type FieldTermLocationMap map[string]TermLocationMap
 type FieldFragmentMap map[string][]string
 
 type DocumentMatch struct {
-	ID        string                 `json:"id"`
-	Score     float64                `json:"score"`
-	Expl      *Explanation           `json:"explanation,omitempty"`
-	Locations FieldTermLocationMap   `json:"locations,omitempty"`
-	Fragments FieldFragmentMap       `json:"fragments,omitempty"`
-	Fields    map[string]interface{} `json:"fields,omitempty"`
+	ID        string               `json:"id"`
+	Score     float64              `json:"score"`
+	Expl      *Explanation         `json:"explanation,omitempty"`
+	Locations FieldTermLocationMap `json:"locations,omitempty"`
+	Fragments FieldFragmentMap     `json:"fragments,omitempty"`
+
+	// Fields contains the values for document fields listed in
+	// SearchRequest.Fields. Text fields are returned as strings, numeric
+	// fields as float64s and date fields as time.RFC3339 formatted strings.
+	Fields map[string]interface{} `json:"fields,omitempty"`
 }
 
 func (dm *DocumentMatch) AddFieldValue(name string, value interface{}) {