Skip to content

Commit db64685

Browse files
russcamrusscam
committed
Remove multiple types per index from documentation (#3139)
* Remove multiple types per index from documentation Closes #3138 * Remove usage of store on [Object] in docs Add additional XML comments for property mappings
1 parent 91fa59c commit db64685

File tree

9 files changed

+237
-322
lines changed

9 files changed

+237
-322
lines changed

‎.paket/Paket.Restore.targets

+2-2
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,10 @@
5353
</PropertyGroup>
5454

5555
<!-- If shasum and awk exist get the hashes -->
56-
<Exec Condition=" '$(PaketRestoreCachedHasher)' != '' " Command="$(PaketRestoreCachedHasher)" ConsoleToMSBuild='true'>
56+
<Exec StandardOutputImportance="Low" Condition=" '$(PaketRestoreCachedHasher)' != '' " Command="$(PaketRestoreCachedHasher)" ConsoleToMSBuild='true'>
5757
<Output TaskParameter="ConsoleOutput" PropertyName="PaketRestoreCachedHash" />
5858
</Exec>
59-
<Exec Condition=" '$(PaketRestoreLockFileHasher)' != '' " Command="$(PaketRestoreLockFileHasher)" ConsoleToMSBuild='true'>
59+
<Exec StandardOutputImportance="Low" Condition=" '$(PaketRestoreLockFileHasher)' != '' " Command="$(PaketRestoreLockFileHasher)" ConsoleToMSBuild='true'>
6060
<Output TaskParameter="ConsoleOutput" PropertyName="PaketRestoreLockFileHash" />
6161
</Exec>
6262

‎src/Nest/Mapping/AttributeBased/ElasticsearchCorePropertyAttributeBase.cs

+2
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,14 @@ protected ElasticsearchCorePropertyAttributeBase(FieldType type) : base(type) {
2121

2222
Union<SimilarityOption, string> ICoreProperty.Similarity { get; set; }
2323

24+
/// <inheritdoc cref="ICoreProperty" />
2425
public string Similarity
2526
{
2627
set => Self.Similarity = value;
2728
get => Self.Similarity?.Match(f => f.GetStringValue(), str => str);
2829
}
2930

31+
/// <inheritdoc cref="ICoreProperty" />
3032
public bool Store
3133
{
3234
get => Self.Store.GetValueOrDefault();

‎src/Nest/Mapping/DynamicMapping.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namespace Nest
99
public enum DynamicMapping
1010
{
1111
/// <summary>
12-
/// If new unmapped fields are passed, the whole document WON'T be added/updated
12+
/// If new unmapped fields are passed, the whole document will not be added/updated
1313
/// </summary>
1414
[EnumMember(Value = "strict")]
1515
Strict

‎src/Nest/Mapping/Types/Complex/Object/ObjectProperty.cs

+34-3
Original file line numberDiff line numberDiff line change
@@ -5,28 +5,47 @@
55

66
namespace Nest
77
{
8+
/// <summary>
9+
/// A object datatype mapping for an inner object
10+
/// </summary>
811
[JsonObject(MemberSerialization.OptIn)]
912
public interface IObjectProperty : ICoreProperty
1013
{
14+
/// <summary>
15+
/// Whether or not new properties should be added dynamically to an existing object.
16+
/// Default is <c>true</c>
17+
/// </summary>
1118
[JsonProperty("dynamic")]
1219
Union<bool, DynamicMapping> Dynamic { get; set; }
1320

21+
/// <summary>
22+
/// Whether the JSON value given for this field should be parsed and indexed. Default is <c>true</c>
23+
/// </summary>
1424
[JsonProperty("enabled")]
1525
bool? Enabled { get; set; }
1626

27+
/// <summary>
28+
/// The fields within the object
29+
/// </summary>
1730
[JsonProperty("properties", TypeNameHandling = TypeNameHandling.None)]
1831
IProperties Properties { get; set; }
1932
}
2033

34+
/// <summary>
35+
/// A object datatype mapping for an inner object
36+
/// </summary>
2137
[DebuggerDisplay("{DebugDisplay}")]
2238
public class ObjectProperty : CorePropertyBase, IObjectProperty
2339
{
2440
public ObjectProperty() : base(FieldType.Object) { }
2541

2642
protected ObjectProperty(FieldType type) : base(type) { }
2743

44+
/// <inheritdoc />
2845
public Union<bool, DynamicMapping> Dynamic { get; set; }
46+
/// <inheritdoc />
2947
public bool? Enabled { get; set; }
48+
/// <inheritdoc />
3049
public IProperties Properties { get; set; }
3150
}
3251

@@ -54,17 +73,29 @@ public abstract class ObjectPropertyDescriptorBase<TDescriptor, TInterface, TPar
5473

5574
protected ObjectPropertyDescriptorBase() : this(FieldType.Object) { }
5675

57-
protected ObjectPropertyDescriptorBase(FieldType type) : base(type)
58-
{
76+
protected ObjectPropertyDescriptorBase(FieldType type) : base(type) =>
5977
_TypeName = TypeName.Create<TChild>();
60-
}
6178

79+
/// <summary>
80+
/// Whether or not new properties should be added dynamically to an existing object.
81+
/// Default is <c>true</c>
82+
/// </summary>
6283
public TDescriptor Dynamic(Union<bool, DynamicMapping> dynamic) => Assign(a => a.Dynamic = dynamic);
6384

85+
/// <summary>
86+
/// Whether or not new properties should be added dynamically to an existing object.
87+
/// Default is <c>true</c>
88+
/// </summary>
6489
public TDescriptor Dynamic(bool dynamic = true) => Assign(a => a.Dynamic = dynamic);
6590

91+
/// <summary>
92+
/// Whether the JSON value given for this field should be parsed and indexed. Default is <c>true</c>
93+
/// </summary>
6694
public TDescriptor Enabled(bool? enabled = true) => Assign(a => a.Enabled = enabled);
6795

96+
/// <summary>
97+
/// The fields within the object
98+
/// </summary>
6899
public TDescriptor Properties(Func<PropertiesDescriptor<TChild>, IPromise<IProperties>> selector) =>
69100
Assign(a => a.Properties = selector?.Invoke(new PropertiesDescriptor<TChild>(a.Properties))?.Value);
70101

‎src/Nest/Mapping/Types/CorePropertyBase.cs

+22-1
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,33 @@ namespace Nest
88
[ContractJsonConverter(typeof(PropertyJsonConverter))]
99
public interface ICoreProperty : IProperty
1010
{
11+
/// <summary>
12+
/// Whether the field value should be stored and retrievable separately from the _source field
13+
/// Default is <c>false</c>.
14+
/// </summary>
15+
/// <remarks>
16+
/// Not valid on <see cref="ObjectProperty"/>
17+
/// </remarks>
1118
[JsonProperty("store")]
1219
bool? Store { get; set; }
1320

21+
/// <summary>
22+
/// Configures multi-fields for this field. Allows one field to be indexed in different
23+
/// ways to serve different purposes
24+
/// </summary>
1425
[JsonProperty("fields", DefaultValueHandling = DefaultValueHandling.Ignore)]
1526
IProperties Fields { get; set; }
1627

28+
/// <summary>
29+
/// Which relevancy scoring algorithm or similarity should be used. Defaults to BM25
30+
/// </summary>
1731
[JsonProperty("similarity")]
1832
Union<SimilarityOption, string> Similarity { get; set; }
1933

34+
/// <summary>
35+
/// Copies the value of this field into another field, which can be queried as a single field.
36+
/// Allows for the creation of custom _all fields
37+
/// </summary>
2038
[JsonProperty("copy_to")]
2139
[JsonConverter(typeof(FieldsJsonConverter))]
2240
Fields CopyTo { get; set; }
@@ -27,10 +45,13 @@ public abstract class CorePropertyBase : PropertyBase, ICoreProperty
2745
{
2846
protected CorePropertyBase(FieldType type) : base(type) { }
2947

30-
48+
/// <inheritdoc />
3149
public Fields CopyTo { get; set; }
50+
/// <inheritdoc />
3251
public IProperties Fields { get; set; }
52+
/// <inheritdoc />
3353
public Union<SimilarityOption, string> Similarity { get; set; }
54+
/// <inheritdoc />
3455
public bool? Store { get; set; }
3556
}
3657
}

‎src/Nest/Mapping/Types/PropertyBase.cs

+9-6
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,19 @@ namespace Nest
1111
[ContractJsonConverter(typeof(PropertyJsonConverter))]
1212
public interface IProperty : IFieldMapping
1313
{
14+
/// <summary>
15+
/// The name of the property
16+
/// </summary>
1417
PropertyName Name { get; set; }
1518

19+
/// <summary>
20+
/// The datatype of the property
21+
/// </summary>
1622
[JsonProperty("type")]
1723
string Type { get; set; }
1824

1925
/// <summary>
20-
/// Local property metadata that will NOT be stored in Elasticsearch with the mappings
26+
/// Local property metadata that will not be stored in Elasticsearch with the mappings
2127
/// </summary>
2228
[JsonIgnore]
2329
IDictionary<string, object> LocalMetadata { get; set; }
@@ -32,11 +38,7 @@ public interface IPropertyWithClrOrigin
3238
public abstract class PropertyBase : IProperty, IPropertyWithClrOrigin
3339
{
3440
private string _type;
35-
protected string TypeOverride
36-
{
37-
get => _type;
38-
set => _type = value;
39-
}
41+
protected string TypeOverride { get => _type; set => _type = value; }
4042

4143
string IProperty.Type { get => _type; set => _type = value; }
4244

@@ -49,6 +51,7 @@ protected PropertyBase(FieldType type)
4951

5052
protected string DebugDisplay => $"Type: {((IProperty)this).Type ?? "<empty>"}, Name: {Name.DebugDisplay} ";
5153

54+
/// <inheritdoc />
5255
public PropertyName Name { get; set; }
5356

5457
/// <inheritdoc />

‎src/Tests/ClientConcepts/HighLevel/Mapping/AttributeMapping.doc.cs

+39-72
Original file line numberDiff line numberDiff line change
@@ -26,29 +26,16 @@ namespace Tests.ClientConcepts.HighLevel.Mapping
2626
* When you use attributes, you *must* also call `.AutoMap()` for the attributes to be applied.
2727
* --
2828
*
29-
* Here we define the same two types as before, but this time using attributes to define the mappings.
29+
* Here we define an `Employee` type and use attributes to define the mappings.
3030
*/
3131
public class AttributeMapping
3232
{
3333
private IElasticClient client = TestClient.GetInMemoryClient(c => c.DisableDirectStreaming());
3434

35-
[ElasticsearchType(Name = "company")]
36-
public class Company
37-
{
38-
[Keyword(NullValue = "null", Similarity = "BM25")]
39-
public string Name { get; set; }
40-
41-
[Text(Name = "office_hours")]
42-
public TimeSpan? HeadOfficeHours { get; set; }
43-
44-
[Object(Store = false)]
45-
public List<Employee> Employees { get; set; }
46-
}
47-
4835
[ElasticsearchType(Name = "employee")]
4936
public class Employee
5037
{
51-
[Text(Name = "first_name")]
38+
[Text(Name = "first_name", Norms = false, Similarity = "LMDirichlet")]
5239
public string FirstName { get; set; }
5340

5441
[Text(Name = "last_name")]
@@ -66,15 +53,29 @@ public class Employee
6653
[Nested]
6754
[PropertyName("empl")]
6855
public List<Employee> Employees { get; set; }
56+
57+
[Text(Name = "office_hours")]
58+
public TimeSpan? OfficeHours { get; set; }
59+
60+
[Object]
61+
public List<Skill> Skills { get; set; }
6962
}
7063

64+
public class Skill
65+
{
66+
[Text]
67+
public string Name { get; set; }
68+
69+
[Number(NumberType.Byte, Name = "level")]
70+
public int Proficiency { get; set; }
71+
}
72+
7173
/**Then we map the types by calling `.AutoMap()` */
7274
[U]
7375
public void UsingAutoMapWithAttributes()
7476
{
7577
var createIndexResponse = client.CreateIndex("myindex", c => c
7678
.Mappings(ms => ms
77-
.Map<Company>(m => m.AutoMap())
7879
.Map<Employee>(m => m.AutoMap())
7980
)
8081
);
@@ -86,61 +87,6 @@ public void UsingAutoMapWithAttributes()
8687
{
8788
mappings = new
8889
{
89-
company = new
90-
{
91-
properties = new
92-
{
93-
employees = new
94-
{
95-
properties = new
96-
{
97-
birthday = new
98-
{
99-
format = "MMddyyyy",
100-
type = "date"
101-
},
102-
empl = new
103-
{
104-
properties = new {},
105-
type = "nested"
106-
},
107-
first_name = new
108-
{
109-
type = "text"
110-
},
111-
isManager = new
112-
{
113-
null_value = false,
114-
store = true,
115-
type = "boolean"
116-
},
117-
last_name = new
118-
{
119-
type = "text"
120-
},
121-
salary = new
122-
{
123-
coerce = true,
124-
doc_values = false,
125-
ignore_malformed = true,
126-
type = "float"
127-
}
128-
},
129-
type = "object",
130-
store = false
131-
},
132-
name = new
133-
{
134-
null_value = "null",
135-
similarity = "BM25",
136-
type = "keyword"
137-
},
138-
office_hours = new
139-
{
140-
type = "text"
141-
}
142-
}
143-
},
14490
employee = new
14591
{
14692
properties = new
@@ -157,7 +103,9 @@ public void UsingAutoMapWithAttributes()
157103
},
158104
first_name = new
159105
{
160-
type = "text"
106+
type = "text",
107+
norms = false,
108+
similarity = "LMDirichlet"
161109
},
162110
isManager = new
163111
{
@@ -169,12 +117,31 @@ public void UsingAutoMapWithAttributes()
169117
{
170118
type = "text"
171119
},
120+
office_hours = new
121+
{
122+
type = "text"
123+
},
172124
salary = new
173125
{
174126
coerce = true,
175127
doc_values = false,
176128
ignore_malformed = true,
177129
type = "float"
130+
},
131+
skills = new
132+
{
133+
properties = new
134+
{
135+
level = new
136+
{
137+
type = "byte"
138+
},
139+
name = new
140+
{
141+
type = "text"
142+
}
143+
},
144+
type = "object"
178145
}
179146
}
180147
}

0 commit comments

Comments
 (0)